Backport PR #32499: Better error message for OOB result (#32605)

Author: meeseeksmachine

doc/source/whatsnew/v1.0.2.rst

@@ -65,6 +65,7 @@ Bug fixes
 
 - Bug in :meth:`DataFrame.reindex` and :meth:`Series.reindex` when reindexing with a tz-aware index (:issue:`26683`)
 - Bug where :func:`to_datetime` would raise when passed ``pd.NA`` (:issue:`32213`)
+- Improved error message when subtracting two :class:`Timestamp` that result in an out-of-bounds :class:`Timedelta` (:issue:`31774`)
 
 **Categorical**
 

pandas/_libs/tslibs/c_timestamp.pyx

@@ -286,6 +286,10 @@ cdef class _Timestamp(datetime):
         # coerce if necessary if we are a Timestamp-like
         if (PyDateTime_Check(self)
                 and (PyDateTime_Check(other) or is_datetime64_object(other))):
+            # both_timestamps is to determine whether Timedelta(self - other)
+            # should raise the OOB error, or fall back returning a timedelta.
+            both_timestamps = (isinstance(other, _Timestamp) and
+                               isinstance(self, _Timestamp))
             if isinstance(self, _Timestamp):
                 other = type(self)(other)
             else:
@@ -301,7 +305,14 @@ cdef class _Timestamp(datetime):
             from pandas._libs.tslibs.timedeltas import Timedelta
             try:
                 return Timedelta(self.value - other.value)
-            except (OverflowError, OutOfBoundsDatetime):
+            except (OverflowError, OutOfBoundsDatetime) as err:
+                if isinstance(other, _Timestamp):
+                    if both_timestamps:
+                        raise OutOfBoundsDatetime(
+                            "Result is too large for pandas.Timedelta. Convert inputs "
+                            "to datetime.datetime with 'Timestamp.to_pydatetime()' "
+                            "before subtracting."
+                        ) from err
                 pass
         elif is_datetime64_object(self):
             # GH#28286 cython semantics for __rsub__, `other` is actually

pandas/tests/scalar/timestamp/test_arithmetic.py

@@ -3,6 +3,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import OutOfBoundsDatetime
+
 from pandas import Timedelta, Timestamp
 
 from pandas.tseries import offsets
@@ -60,6 +62,18 @@ def test_overflow_offset_raises(self):
         with pytest.raises(OverflowError, match=msg):
             stamp - offset_overflow
 
+    def test_overflow_timestamp_raises(self):
+        # https://github.com/pandas-dev/pandas/issues/31774
+        msg = "Result is too large"
+        a = Timestamp("2101-01-01 00:00:00")
+        b = Timestamp("1688-01-01 00:00:00")
+
+        with pytest.raises(OutOfBoundsDatetime, match=msg):
+            a - b
+
+        # but we're OK for timestamp and datetime.datetime
+        assert (a - b.to_pydatetime()) == (a.to_pydatetime() - b)
+
     def test_delta_preserve_nanos(self):
         val = Timestamp(1337299200000000123)
         result = val + timedelta(1)