Skip to content

Commit 2b78e5a

Browse files
committed
DOC: Timedelta & timestamp limitations
1 parent f1a93d1 commit 2b78e5a

File tree

4 files changed

+43
-23
lines changed

4 files changed

+43
-23
lines changed

doc/source/gotchas.rst

Lines changed: 0 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -356,27 +356,6 @@ such as ``numpy.logical_and``.
356356
See the `this old issue <https://github.com/pydata/pandas/issues/2388>`__ for a more
357357
detailed discussion.
358358

359-
.. _gotchas.timestamp-limits:
360-
361-
Timestamp limitations
362-
---------------------
363-
364-
Minimum and maximum timestamps
365-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
366-
367-
Since pandas represents timestamps in nanosecond resolution, the timespan that
368-
can be represented using a 64-bit integer is limited to approximately 584 years:
369-
370-
.. ipython:: python
371-
372-
begin = pd.Timestamp.min
373-
begin
374-
375-
end = pd.Timestamp.max
376-
end
377-
378-
See :ref:`here <timeseries.oob>` for ways to represent data outside these bound.
379-
380359
Parsing Dates from Text Files
381360
-----------------------------
382361

doc/source/timedeltas.rst

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -109,6 +109,26 @@ The ``unit`` keyword argument specifies the unit of the Timedelta:
109109
to_timedelta(np.arange(5), unit='s')
110110
to_timedelta(np.arange(5), unit='d')
111111
112+
.. _timedeltas.limitations:
113+
114+
Timedelta limitations
115+
~~~~~~~~~~~~~~~~~~~~~
116+
117+
Pandas represents ``Timedeltas`` in nanosecond resolution using
118+
64 bit integers. As such, the 64 bit integer limits determine
119+
the ``Timedelta`` limits.
120+
121+
.. ipython:: python
122+
min_int = np.iinfo(np.int64).min
123+
max_int = np.iinfo(np.int64).max
124+
125+
# Note: the smallest integer gives a NaT
126+
Timedelta(min_int)
127+
Timedelta(min_int+1) == Timedelta.min
128+
Timedelta(max_int) == Timedelta.max
129+
130+
# (min_int - 1) and (max_int + 1) result in OverflowErrors
131+
112132
.. _timedeltas.operations:
113133

114134
Operations

doc/source/timeseries.rst

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -307,6 +307,27 @@ using various combinations of parameters like ``start``, ``end``,
307307
The start and end dates are strictly inclusive. So it will not generate any
308308
dates outside of those dates if specified.
309309

310+
.. _timeseries.timestamp-limits:
311+
312+
Timestamp limitations
313+
---------------------
314+
315+
Minimum and maximum timestamps
316+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
317+
318+
Since pandas represents timestamps in nanosecond resolution, the timespan that
319+
can be represented using a 64-bit integer is limited to approximately 584 years:
320+
321+
.. ipython:: python
322+
323+
begin = pd.Timestamp.min
324+
begin
325+
326+
end = pd.Timestamp.max
327+
end
328+
329+
See :ref:`here <timeseries.oob>` for ways to represent data outside these bound.
330+
310331
.. _timeseries.datetimeindex:
311332

312333
DatetimeIndex
@@ -1691,7 +1712,7 @@ the quarter end:
16911712
Representing out-of-bounds spans
16921713
--------------------------------
16931714

1694-
If you have data that is outside of the ``Timestamp`` bounds, see :ref:`Timestamp limitations <gotchas.timestamp-limits>`,
1715+
If you have data that is outside of the ``Timestamp`` bounds, see :ref:`Timestamp limitations <timeseries.timestamp-limits>`,
16951716
then you can use a ``PeriodIndex`` and/or ``Series`` of ``Periods`` to do computations.
16961717

16971718
.. ipython:: python

doc/source/whatsnew/v0.18.1.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -129,7 +129,7 @@ Bug Fixes
129129

130130

131131
- Bug in ``Timestamp.__repr__`` that caused ``pprint`` to fail in nested structures (:issue:`12622`)
132-
- Bug in ``Timedelta.min`` and ``Timedelta.max``, the properties now report the true minimum/maximum timedeltas as recognized by Pandas. (:issue:`12727`)
132+
- 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`)
133133

134134

135135

0 commit comments

Comments
 (0)