ENH: Fix out-of-bounds error handling in _to_datetime_with_unit

Author: kosiew

pandas/core/tools/datetimes.py

@@ -75,7 +75,6 @@
 from pandas.core.construction import extract_array
 from pandas.core.indexes.base import Index
 from pandas.core.indexes.datetimes import DatetimeIndex
-
 if TYPE_CHECKING:
     from collections.abc import (
         Callable,
@@ -479,49 +478,70 @@ def _array_strptime_with_fallback(
     return Index(result, dtype=result.dtype, name=name)
 
 
-def _to_datetime_with_unit(arg, unit, name, utc: bool, errors: str) -> Index:
+
+
+
+def _to_datetime_with_unit(arg, unit, name, utc: bool, errors: str) -> DatetimeIndex:
     """
-    to_datetime specalized to the case where a 'unit' is passed.
+    to_datetime specialized to the case where a 'unit' is passed.
+    Fixes a bug where scalar out-of-bounds values were not raising
+    an error consistently.
     """
+    # Ensure we handle both array-likes and scalars the same way.
+    # extract_array can return a scalar if 'arg' is scalar-like;
+    # so we force everything into at least 1D shape.
     arg = extract_array(arg, extract_numpy=True)
+    arg = np.atleast_1d(arg)
 
     # GH#30050 pass an ndarray to tslib.array_to_datetime
     # because it expects an ndarray argument
     if isinstance(arg, IntegerArray):
+        # For IntegerArray, we can directly convert
         arr = arg.astype(f"datetime64[{unit}]")
         tz_parsed = None
+
     else:
+        # Now we have a guaranteed ndarray
         arg = np.asarray(arg)
 
         if arg.dtype.kind in "iu":
             # Note we can't do "f" here because that could induce unwanted
-            #  rounding GH#14156, GH#20445
+            # rounding GH#14156, GH#20445
             arr = arg.astype(f"datetime64[{unit}]", copy=False)
             try:
                 arr = astype_overflowsafe(arr, np.dtype("M8[ns]"), copy=False)
             except OutOfBoundsDatetime:
                 if errors == "raise":
                     raise
+                # errors != "raise" => coerce to object and retry
                 arg = arg.astype(object)
                 return _to_datetime_with_unit(arg, unit, name, utc, errors)
             tz_parsed = None
 
         elif arg.dtype.kind == "f":
+            # Floating dtypes
             with np.errstate(over="raise"):
                 try:
                     arr = cast_from_unit_vectorized(arg, unit=unit)
                 except OutOfBoundsDatetime as err:
                     if errors != "raise":
+                        # coerce to object and retry
                         return _to_datetime_with_unit(
-                            arg.astype(object), unit, name, utc, errors
+                            arg.astype(object),
+                            unit,
+                            name,
+                            utc,
+                            errors,
                         )
                     raise OutOfBoundsDatetime(
                         f"cannot convert input with unit '{unit}'"
                     ) from err
 
             arr = arr.view("M8[ns]")
             tz_parsed = None
+
         else:
+            # Fallback: treat as object dtype
             arg = arg.astype(object, copy=False)
             arr, tz_parsed = tslib.array_to_datetime(
                 arg,
@@ -531,23 +551,22 @@ def _to_datetime_with_unit(arg, unit, name, utc: bool, errors: str) -> Index:
                 creso=NpyDatetimeUnit.NPY_FR_ns.value,
             )
 
+    # Construct a DatetimeIndex from the array
     result = DatetimeIndex(arr, name=name)
-    if not isinstance(result, DatetimeIndex):
-        return result
 
-    # GH#23758: We may still need to localize the result with tz
-    # GH#25546: Apply tz_parsed first (from arg), then tz (from caller)
-    # result will be naive but in UTC
+    # May need to localize result to parsed tz or convert to UTC if requested
     result = result.tz_localize("UTC").tz_convert(tz_parsed)
 
     if utc:
         if result.tz is None:
             result = result.tz_localize("utc")
         else:
             result = result.tz_convert("utc")
+
     return result
 
 
+
 def _adjust_to_origin(arg, origin, unit):
     """
     Helper function for to_datetime.