BUG: Raise OutOfBoundsDatetime instead of silently upcasting in replace (pandas-dev#61671)

The previous fix silently widened datetime64[ns] to datetime64[us], which
could truncate sub-microsecond data. Instead, raise OutOfBoundsDatetime
with a message telling the user to explicitly cast before operating.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -168,7 +168,7 @@ Datetimelike
 - Bug in :func:`date_range` where ``inclusive`` parameter failed to filter endpoints when only ``start`` and ``periods`` or ``end`` and ``periods`` were specified (:issue:`46331`)
 - Bug in :func:`to_datetime` and :func:`to_timedelta` on ARM platforms where round ``float`` values outside the int64 domain (e.g. ``float(2**63)``) could silently produce incorrect results instead of raising (:issue:`64619`)
 - Bug in :func:`to_datetime` and :func:`to_timedelta` where ``uint64`` values greater than ``int64`` max silently overflowed instead of raising :class:`OutOfBoundsDatetime` or :class:`OutOfBoundsTimedelta` (:issue:`60677`)
-- Bug in :meth:`DataFrame.replace` and :meth:`Series.replace` raising ``AssertionError`` when replacing with a ``datetime`` value outside the ``datetime64[ns]`` range (:issue:`61671`)
+- Bug in :meth:`DataFrame.replace` and :meth:`Series.replace` raising ``AssertionError`` instead of :class:`OutOfBoundsDatetime` when replacing with a ``datetime`` value outside the ``datetime64[ns]`` range (:issue:`61671`)
 - Bug in :meth:`DatetimeArray.isin` and :meth:`TimedeltaArray.isin` where mismatched resolutions could silently truncate finer-resolution values, leading to false matches (:issue:`64545`)
 - Bug in adding non-nano :class:`DatetimeIndex` with non-vectorized offsets (e.g. :class:`CustomBusinessDay`, :class:`CustomBusinessMonthEnd`) having a sub-unit ``offset`` parameter incorrectly truncating the result or raising ``AttributeError`` (:issue:`56586`)
 

pandas/core/dtypes/cast.py

@@ -1206,20 +1206,6 @@ def find_result_type(left_dtype: DtypeObj, right: Any) -> DtypeObj:
         dtype, _ = infer_dtype_from(right)
         new_dtype = find_common_type([left_dtype, dtype])
 
-        # GH#61671: for datetime64/timedelta64, find_common_type picks the
-        # highest resolution (e.g. ns over us), but this may have too narrow
-        # a range for the value. If the inferred dtype has lower resolution
-        # (wider range), prefer it so the value can be represented.
-        if (
-            new_dtype == left_dtype
-            and isinstance(new_dtype, np.dtype)
-            and new_dtype.kind in "mM"
-            and isinstance(dtype, np.dtype)
-            and dtype.kind == new_dtype.kind
-            and dtype != new_dtype
-        ):
-            new_dtype = dtype
-
     return new_dtype
 
 

pandas/core/internals/blocks.py

@@ -437,6 +437,15 @@ def coerce_to_target_dtype(self, other, raise_on_upcast: bool) -> Block:
         """
         new_dtype = find_result_type(self.values.dtype, other)
         if new_dtype == self.dtype:
+            if lib.is_np_dtype(new_dtype, "mM"):
+                # GH#61671 e.g. datetime64[ns] column and a replacement value
+                # outside ns range. find_common_type picked the highest
+                # resolution which can't represent the value.
+                raise OutOfBoundsDatetime(
+                    f"Incompatible (high-resolution) value for "
+                    f"dtype='{self.dtype}'. "
+                    "Explicitly cast before operating."
+                )
             # GH#52927 avoid RecursionError
             raise AssertionError(
                 "Something has gone wrong, please report a bug at "

pandas/tests/dtypes/test_inference.py

@@ -2158,10 +2158,9 @@ def test_find_result_type_floats(right, result):
 @pytest.mark.parametrize(
     "right,result",
     [
-        # GH#61671 - out-of-bounds for ns, needs wider range (us)
-        (datetime(3000, 1, 1), np.dtype("datetime64[us]")),
-        # in-range value still infers as us (Python datetime resolution)
-        (datetime(2020, 1, 1), np.dtype("datetime64[us]")),
+        # GH#61671 - find_common_type picks highest resolution (ns)
+        (datetime(3000, 1, 1), np.dtype("datetime64[ns]")),
+        (datetime(2020, 1, 1), np.dtype("datetime64[ns]")),
         # np.datetime64 with explicit ns resolution stays ns
         (np.datetime64("2020-01-01", "ns"), np.dtype("datetime64[ns]")),
     ],

pandas/tests/frame/methods/test_replace.py

@@ -6,6 +6,7 @@
 import numpy as np
 import pytest
 
+from pandas.errors import OutOfBoundsDatetime
 import pandas.util._test_decorators as td
 
 import pandas as pd
@@ -1473,9 +1474,8 @@ def test_replace_nan_nullable_ints(self, dtype, using_nan_is_na):
     def test_replace_datetime_out_of_bounds_for_ns(self):
         # GH#61671
         df = DataFrame([np.nan], dtype="datetime64[ns]")
-        result = df.replace(np.nan, datetime(3000, 1, 1))
-        expected = DataFrame([Timestamp("3000-01-01")], dtype="datetime64[us]")
-        tm.assert_frame_equal(result, expected)
+        with pytest.raises(OutOfBoundsDatetime, match="Explicitly cast"):
+            df.replace(np.nan, datetime(3000, 1, 1))
 
 
 class TestDataFrameReplaceRegex:

pandas/tests/series/methods/test_replace.py

@@ -4,6 +4,7 @@
 import numpy as np
 import pytest
 
+from pandas.errors import OutOfBoundsDatetime
 import pandas.util._test_decorators as td
 
 import pandas as pd
@@ -745,6 +746,5 @@ def test_replace_from_index():
 def test_replace_datetime_out_of_bounds_for_ns():
     # GH#61671
     ser = pd.Series([np.nan], dtype="datetime64[ns]")
-    result = ser.replace(np.nan, datetime(3000, 1, 1))
-    expected = pd.Series([pd.Timestamp("3000-01-01")], dtype="datetime64[us]")
-    tm.assert_series_equal(result, expected)
+    with pytest.raises(OutOfBoundsDatetime, match="Explicitly cast"):
+        ser.replace(np.nan, datetime(3000, 1, 1))