Add date overflow message to tz_localize (pandas-dev#32967) (pandas-dev#35187)

* Add date overflow message to tz_localize (pandas-dev#32967)

* Delay evaluating timestamp

Author: gabrielNT

doc/source/whatsnew/v1.1.0.rst

@@ -922,6 +922,7 @@ Datetimelike
   resolution which converted to object dtype instead of coercing to ``datetime64[ns]``
   dtype when within the timestamp bounds (:issue:`34843`).
 - The ``freq`` keyword in :class:`Period`, :func:`date_range`, :func:`period_range`, :func:`pd.tseries.frequencies.to_offset` no longer allows tuples, pass as string instead (:issue:`34703`)
+- ``OutOfBoundsDatetime`` issues an improved error message when timestamp is out of implementation bounds. (:issue:`32967`)
 
 Timedelta
 ^^^^^^^^^

pandas/_libs/tslibs/conversion.pyx

@@ -639,11 +639,20 @@ cdef inline check_overflows(_TSObject obj):
     # GH#12677
     if obj.dts.year == 1677:
         if not (obj.value < 0):
-            raise OutOfBoundsDatetime
+            from pandas._libs.tslibs.timestamps import Timestamp
+            fmt = (f"{obj.dts.year}-{obj.dts.month:02d}-{obj.dts.day:02d} "
+                   f"{obj.dts.hour:02d}:{obj.dts.min:02d}:{obj.dts.sec:02d}")
+            raise OutOfBoundsDatetime(
+                f"Converting {fmt} underflows past {Timestamp.min}"
+            )
     elif obj.dts.year == 2262:
         if not (obj.value > 0):
-            raise OutOfBoundsDatetime
-
+            from pandas._libs.tslibs.timestamps import Timestamp
+            fmt = (f"{obj.dts.year}-{obj.dts.month:02d}-{obj.dts.day:02d} "
+                   f"{obj.dts.hour:02d}:{obj.dts.min:02d}:{obj.dts.sec:02d}")
+            raise OutOfBoundsDatetime(
+                f"Converting {fmt} overflows past {Timestamp.max}"
+            )
 
 # ----------------------------------------------------------------------
 # Localization

pandas/tests/scalar/timestamp/test_timezones.py

@@ -21,16 +21,23 @@ class TestTimestampTZOperations:
     # Timestamp.tz_localize
 
     def test_tz_localize_pushes_out_of_bounds(self):
-        msg = "^$"
         # GH#12677
         # tz_localize that pushes away from the boundary is OK
+        msg = (
+            f"Converting {Timestamp.min.strftime('%Y-%m-%d %H:%M:%S')} "
+            f"underflows past {Timestamp.min}"
+        )
         pac = Timestamp.min.tz_localize("US/Pacific")
         assert pac.value > Timestamp.min.value
         pac.tz_convert("Asia/Tokyo")  # tz_convert doesn't change value
         with pytest.raises(OutOfBoundsDatetime, match=msg):
             Timestamp.min.tz_localize("Asia/Tokyo")
 
         # tz_localize that pushes away from the boundary is OK
+        msg = (
+            f"Converting {Timestamp.max.strftime('%Y-%m-%d %H:%M:%S')} "
+            f"overflows past {Timestamp.max}"
+        )
         tokyo = Timestamp.max.tz_localize("Asia/Tokyo")
         assert tokyo.value < Timestamp.max.value
         tokyo.tz_convert("US/Pacific")  # tz_convert doesn't change value