Fix pandas.Timedelta range

closes #12727

*Problem*  Pandas Timedelta derives from `datetime.timedelta` and
increase  the resolution of the timedeltas. As such the
Pandas.Timedelta  object can only have a smaller range of values.
*Solution*  This change modifies the properties that report  the range
and resolution to reflect Pandas capabilities.    **Reference**  https
://github.com/python/cpython/blob/8d1d7e6816753248768e4cc1c0370221814e
9cf1/Lib/datetime.py#L651-L654

Author: Hassan Kibirige <[email protected]>

Closes #12728 from has2k1/fix-timedelta-limits and squashes the following commits:

2b78e5a [Hassan Kibirige] DOC: Timedelta & timestamp limitations
f1a93d1 [Hassan Kibirige] BUG: pandas.Timedelta min and max limits

Author: has2k1

doc/source/gotchas.rst

@@ -356,27 +356,6 @@ such as ``numpy.logical_and``.
 See the `this old issue <https://github.com/pydata/pandas/issues/2388>`__ for a more
 detailed discussion.
 
-.. _gotchas.timestamp-limits:
-
-Timestamp limitations
----------------------
-
-Minimum and maximum timestamps
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Since pandas represents timestamps in nanosecond resolution, the timespan that
-can be represented using a 64-bit integer is limited to approximately 584 years:
-
-.. ipython:: python
-
-   begin = pd.Timestamp.min
-   begin
-
-   end = pd.Timestamp.max
-   end
-
-See :ref:`here <timeseries.oob>` for ways to represent data outside these bound.
-
 Parsing Dates from Text Files
 -----------------------------
 

doc/source/timedeltas.rst

@@ -109,6 +109,20 @@ The ``unit`` keyword argument specifies the unit of the Timedelta:
    to_timedelta(np.arange(5), unit='s')
    to_timedelta(np.arange(5), unit='d')
 
+.. _timedeltas.limitations:
+
+Timedelta limitations
+~~~~~~~~~~~~~~~~~~~~~
+
+Pandas represents ``Timedeltas`` in nanosecond resolution using
+64 bit integers. As such, the 64 bit integer limits determine
+the ``Timedelta`` limits.
+
+.. ipython:: python
+
+   pd.Timedelta.min
+   pd.Timedelta.max
+
 .. _timedeltas.operations:
 
 Operations

doc/source/timeseries.rst

@@ -307,6 +307,21 @@ using various combinations of parameters like ``start``, ``end``,
 The start and end dates are strictly inclusive. So it will not generate any
 dates outside of those dates if specified.
 
+.. _timeseries.timestamp-limits:
+
+Timestamp limitations
+---------------------
+
+Since pandas represents timestamps in nanosecond resolution, the timespan that
+can be represented using a 64-bit integer is limited to approximately 584 years:
+
+.. ipython:: python
+
+   pd.Timestamp.min
+   pd.Timestamp.max
+
+See :ref:`here <timeseries.oob>` for ways to represent data outside these bound.
+
 .. _timeseries.datetimeindex:
 
 DatetimeIndex
@@ -1691,7 +1706,7 @@ the quarter end:
 Representing out-of-bounds spans
 --------------------------------
 
-If you have data that is outside of the ``Timestamp`` bounds, see :ref:`Timestamp limitations <gotchas.timestamp-limits>`,
+If you have data that is outside of the ``Timestamp`` bounds, see :ref:`Timestamp limitations <timeseries.timestamp-limits>`,
 then you can use a ``PeriodIndex`` and/or ``Series`` of ``Periods`` to do computations.
 
 .. ipython:: python

doc/source/whatsnew/v0.18.1.txt

@@ -129,6 +129,7 @@ Bug Fixes
 
 
 - Bug in ``Timestamp.__repr__`` that caused ``pprint`` to fail in nested structures (:issue:`12622`)
+- Bug in ``Timedelta.min`` and ``Timedelta.max``, the properties now report the true minimum/maximum ``timedeltas`` as recognized by Pandas. See :ref:`documentation <timedeltas.limitations>`. (:issue:`12727`)
 
 
 

pandas/tseries/tests/test_timedeltas.py

@@ -1083,6 +1083,35 @@ def test_timedelta_hash_equality(self):
         ns_td = Timedelta(1, 'ns')
         self.assertNotEqual(hash(ns_td), hash(ns_td.to_pytimedelta()))
 
+    def test_implementation_limits(self):
+        min_td = Timedelta(Timedelta.min)
+        max_td = Timedelta(Timedelta.max)
+
+        # GH 12727
+        # timedelta limits correspond to int64 boundaries
+        self.assertTrue(min_td.value == np.iinfo(np.int64).min + 1)
+        self.assertTrue(max_td.value == np.iinfo(np.int64).max)
+
+        # Beyond lower limit, a NAT before the Overflow
+        self.assertIsInstance(min_td - Timedelta(1, 'ns'),
+                              pd.tslib.NaTType)
+
+        with tm.assertRaises(OverflowError):
+            min_td - Timedelta(2, 'ns')
+
+        with tm.assertRaises(OverflowError):
+            max_td + Timedelta(1, 'ns')
+
+        # Same tests using the internal nanosecond values
+        td = Timedelta(min_td.value - 1, 'ns')
+        self.assertIsInstance(td, pd.tslib.NaTType)
+
+        with tm.assertRaises(OverflowError):
+            Timedelta(min_td.value - 2, 'ns')
+
+        with tm.assertRaises(OverflowError):
+            Timedelta(max_td.value + 1, 'ns')
+
 
 class TestTimedeltaIndex(tm.TestCase):
     _multiprocess_can_split_ = True

pandas/tslib.pyx

@@ -2722,6 +2722,11 @@ class Timedelta(_Timedelta):
     __pos__ = _op_unary_method(lambda x: x, '__pos__')
     __abs__ = _op_unary_method(lambda x: abs(x), '__abs__')
 
+
+# Resolution is in nanoseconds
+Timedelta.min = Timedelta(np.iinfo(np.int64).min+1, 'ns')
+Timedelta.max = Timedelta(np.iinfo(np.int64).max, 'ns')
+
 cdef PyTypeObject* td_type = <PyTypeObject*> Timedelta
 
 cdef inline bint is_timedelta(object o):