REF: consolidate datetime parsing paths and exception handling (#50790)

* REF: fewer paths through datetime parsing code

* dont catch in conversion.pyx

* REF: move exception handling within dateutil_parse

Author: jbrockmendel

doc/source/user_guide/timeseries.rst

@@ -292,7 +292,7 @@ The default behavior, ``errors='raise'``, is to raise when unparsable:
 .. code-block:: ipython
 
     In [2]: pd.to_datetime(['2009/07/31', 'asd'], errors='raise')
-    ValueError: Unknown string format
+    ValueError: Unknown datetime string format
 
 Pass ``errors='ignore'`` to return the original input when unparsable:
 

pandas/_libs/tslibs/conversion.pyx

@@ -544,16 +544,9 @@ cdef _TSObject convert_str_to_tsobject(str ts, tzinfo tz, str unit,
                 maybe_localize_tso(obj, tz, obj.creso)
                 return obj
 
-        try:
-            dt = parse_datetime_string(
-                ts, dayfirst=dayfirst, yearfirst=yearfirst
-            )
-        except ValueError as err:
-            if "out of range for month" in str(err):
-                # dateutil raised when constructing a datetime object,
-                #  let's give a nicer exception message
-                raise ValueError("could not convert string to Timestamp") from err
-            raise
+        dt = parse_datetime_string(
+            ts, dayfirst=dayfirst, yearfirst=yearfirst
+        )
 
     return convert_datetime_to_tsobject(dt, tz)
 

pandas/_libs/tslibs/parsing.pyx

@@ -286,19 +286,10 @@ def parse_datetime_string(
     except ValueError:
         pass
 
-    try:
-        dt = du_parse(date_string, default=_DEFAULT_DATETIME,
-                      dayfirst=dayfirst, yearfirst=yearfirst)
-    except TypeError:
-        # following may be raised from dateutil
-        # TypeError: 'NoneType' object is not iterable
-        raise ValueError(f'Given date string "{date_string}" not likely a datetime')
-    except OverflowError as err:
-        # with e.g. "08335394550" dateutil raises when trying to pass
-        #  year=8335394550 to datetime.replace
-        raise OutOfBoundsDatetime(
-            f'Parsing "{date_string}" to datetime overflows'
-            ) from err
+    dt, _ = dateutil_parse(date_string, default=_DEFAULT_DATETIME,
+                           dayfirst=dayfirst, yearfirst=yearfirst,
+                           ignoretz=False)
+
     if dt.tzinfo is not None:
         # dateutil can return a datetime with a tzoffset outside of (-24H, 24H)
         #  bounds, which is invalid (can be constructed, but raises if we call
@@ -415,15 +406,9 @@ def parse_datetime_string_with_reso(
     except ValueError:
         pass
 
-    try:
-        parsed, reso = dateutil_parse(date_string, _DEFAULT_DATETIME,
-                                      dayfirst=dayfirst, yearfirst=yearfirst,
-                                      ignoretz=False)
-    except (ValueError, OverflowError) as err:
-        # TODO: allow raise of errors within instead
-        raise DateParseError(err)
-    if parsed is None:
-        raise DateParseError(f"Could not parse {date_string}")
+    parsed, reso = dateutil_parse(date_string, _DEFAULT_DATETIME,
+                                  dayfirst=dayfirst, yearfirst=yearfirst,
+                                  ignoretz=False)
     return parsed, reso
 
 
@@ -612,7 +597,7 @@ cpdef quarter_to_myear(int year, int quarter, str freq):
 
 cdef dateutil_parse(
     str timestr,
-    object default,
+    datetime default,
     bint ignoretz=False,
     bint dayfirst=False,
     bint yearfirst=False,
@@ -623,13 +608,15 @@ cdef dateutil_parse(
         str attr
         datetime ret
         object res
-        object reso = None
+        str reso = None
         dict repl = {}
 
     res, _ = DEFAULTPARSER._parse(timestr, dayfirst=dayfirst, yearfirst=yearfirst)
 
     if res is None:
-        raise ValueError(f"Unknown datetime string format, unable to parse: {timestr}")
+        raise DateParseError(
+            f"Unknown datetime string format, unable to parse: {timestr}"
+        )
 
     for attr in ["year", "month", "day", "hour",
                  "minute", "second", "microsecond"]:
@@ -639,15 +626,27 @@ cdef dateutil_parse(
             reso = attr
 
     if reso is None:
-        raise ValueError(f"Unable to parse datetime string: {timestr}")
+        raise DateParseError(f"Unable to parse datetime string: {timestr}")
 
     if reso == "microsecond":
         if repl["microsecond"] == 0:
             reso = "second"
         elif repl["microsecond"] % 1000 == 0:
             reso = "millisecond"
 
-    ret = default.replace(**repl)
+    try:
+        ret = default.replace(**repl)
+    except ValueError as err:
+        # e.g. "day is out of range for month"
+        # we re-raise to match dateutil's exception message
+        raise DateParseError(str(err) + ": " + timestr) from err
+    except OverflowError as err:
+        # with e.g. "08335394550" dateutil raises when trying to pass
+        #  year=8335394550 to datetime.replace
+        raise OutOfBoundsDatetime(
+            f'Parsing "{timestr}" to datetime overflows'
+        ) from err
+
     if res.weekday is not None and not res.day:
         ret = ret + relativedelta.relativedelta(weekday=res.weekday)
     if not ignoretz:

pandas/tests/frame/test_block_internals.py

@@ -259,7 +259,7 @@ def f(dtype):
             f("float64")
 
         # 10822
-        msg = "^Unknown string format: aa, at position 0$"
+        msg = "^Unknown datetime string format, unable to parse: aa, at position 0$"
         with pytest.raises(ValueError, match=msg):
             f("M8[ns]")
 

pandas/tests/indexes/datetimes/test_constructors.py

@@ -1037,7 +1037,7 @@ def test_from_freq_recreate_from_data(self, freq):
 
     def test_datetimeindex_constructor_misc(self):
         arr = ["1/1/2005", "1/2/2005", "Jn 3, 2005", "2005-01-04"]
-        msg = r"(\(')?Unknown string format(:', 'Jn 3, 2005'\))?"
+        msg = r"(\(')?Unknown datetime string format(:', 'Jn 3, 2005'\))?"
         with pytest.raises(ValueError, match=msg):
             DatetimeIndex(arr)
 

pandas/tests/indexes/datetimes/test_date_range.py

@@ -980,7 +980,7 @@ def test_misc(self):
     def test_date_parse_failure(self):
         badly_formed_date = "2007/100/1"
 
-        msg = "Unknown string format: 2007/100/1"
+        msg = "Unknown datetime string format, unable to parse: 2007/100/1"
         with pytest.raises(ValueError, match=msg):
             Timestamp(badly_formed_date)
 

pandas/tests/io/pytables/test_select.py

@@ -594,7 +594,7 @@ def test_frame_select(setup_path):
         # invalid terms
         df = tm.makeTimeDataFrame()
         store.append("df_time", df)
-        msg = "could not convert string to Timestamp"
+        msg = "day is out of range for month: 0"
         with pytest.raises(ValueError, match=msg):
             store.select("df_time", "index>0")
 

pandas/tests/scalar/timestamp/test_constructors.py

@@ -439,7 +439,7 @@ def test_constructor_nanosecond(self, result):
     @pytest.mark.parametrize("z", ["Z0", "Z00"])
     def test_constructor_invalid_Z0_isostring(self, z):
         # GH 8910
-        msg = f"Unknown string format: 2014-11-02 01:00{z}"
+        msg = f"Unknown datetime string format, unable to parse: 2014-11-02 01:00{z}"
         with pytest.raises(ValueError, match=msg):
             Timestamp(f"2014-11-02 01:00{z}")
 

pandas/tests/series/test_constructors.py

@@ -75,7 +75,7 @@ def test_infer_with_date_and_datetime(self):
     def test_unparseable_strings_with_dt64_dtype(self):
         # pre-2.0 these would be silently ignored and come back with object dtype
         vals = ["aa"]
-        msg = "^Unknown string format: aa, at position 0$"
+        msg = "^Unknown datetime string format, unable to parse: aa, at position 0$"
         with pytest.raises(ValueError, match=msg):
             Series(vals, dtype="datetime64[ns]")
 

pandas/tests/tools/test_to_datetime.py

@@ -2498,7 +2498,7 @@ def test_string_na_nat_conversion_malformed(self, cache):
         malformed = np.array(["1/100/2000", np.nan], dtype=object)
 
         # GH 10636, default is now 'raise'
-        msg = r"Unknown string format:|day is out of range for month"
+        msg = r"Unknown datetime string format"
         with pytest.raises(ValueError, match=msg):
             with tm.assert_produces_warning(
                 UserWarning, match="Could not infer format"
@@ -2812,7 +2812,7 @@ def test_day_not_in_month_coerce(self, cache, arg, format, warning):
             assert isna(to_datetime(arg, errors="coerce", format=format, cache=cache))
 
     def test_day_not_in_month_raise(self, cache):
-        msg = "could not convert string to Timestamp"
+        msg = "day is out of range for month: 2015-02-29, at position 0"
         with pytest.raises(ValueError, match=msg):
             with tm.assert_produces_warning(
                 UserWarning, match="Could not infer format"
@@ -3239,9 +3239,10 @@ def test_invalid_origins_tzinfo(self):
 
     def test_incorrect_value_exception(self):
         # GH47495
-        with pytest.raises(
-            ValueError, match="Unknown string format: yesterday, at position 1"
-        ):
+        msg = (
+            "Unknown datetime string format, unable to parse: yesterday, at position 1"
+        )
+        with pytest.raises(ValueError, match=msg):
             with tm.assert_produces_warning(
                 UserWarning, match="Could not infer format"
             ):

pandas/tests/tseries/frequencies/test_inference.py

@@ -387,7 +387,7 @@ def test_invalid_index_types_unicode():
     # see gh-10822
     #
     # Odd error message on conversions to datetime for unicode.
-    msg = "Unknown string format"
+    msg = "Unknown datetime string format"
 
     with pytest.raises(ValueError, match=msg):
         frequencies.infer_freq(tm.makeStringIndex(10))
@@ -422,7 +422,7 @@ def test_series_invalid_type(end):
 
 def test_series_inconvertible_string():
     # see gh-6407
-    msg = "Unknown string format"
+    msg = "Unknown datetime string format"
 
     with pytest.raises(ValueError, match=msg):
         frequencies.infer_freq(Series(["foo", "bar"]))