DOC: Timedelta & timestamp limitations

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,26 @@ 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
+   min_int = np.iinfo(np.int64).min
+   max_int = np.iinfo(np.int64).max
+
+   # Note: the smallest integer gives a NaT
+   Timedelta(min_int)
+   Timedelta(min_int+1) == Timedelta.min
+   Timedelta(max_int) == Timedelta.max
+
+   # (min_int - 1) and (max_int + 1) result in OverflowErrors
+
 .. _timedeltas.operations:
 
 Operations

doc/source/timeseries.rst

@@ -307,6 +307,27 @@ 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
+---------------------
+
+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.
+
 .. _timeseries.datetimeindex:
 
 DatetimeIndex
@@ -1691,7 +1712,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,7 +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. (:issue:`12727`)
+- 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`)