From 67fff7b7d9dbcd11535d82c7d9f42f79b4658232 Mon Sep 17 00:00:00 2001 From: Michael Niklas Date: Fri, 23 Oct 2026 11:28:19 +0200 Subject: [PATCH 1/2] Fix the time coding docs for pandas 3.1 pandas 3.1 gives microsecond resolution for numeric input with any unit, so the int64 extremes with unit='s' overflow. Build the timestamps from np.datetime64 instead, which keeps its resolution. Co-Authored-By: Claude Opus 5.5 --- doc/internals/time-coding.md | 6 +++--- doc/whats-new.rst | 3 +++ 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/doc/internals/time-coding.md b/doc/internals/time-coding.md index bca49be9c2b..a7fcfdd8b74 100644 --- a/doc/internals/time-coding.md +++ b/doc/internals/time-coding.md @@ -212,9 +212,9 @@ except Exception as err: {py:class}`pandas.Timestamp` is used within xarray to wrap strings of CF encoding reference times and datetime.datetime. -When arguments are numeric (not strings) "unit" can be anything from `'Y'`, `'W'`, `'D'`, `'h'`, `'m'`, `'s'`, `'ms'`, `'us'` or `'ns'`, though the returned resolution will be `"ns"`. +When arguments are numeric (not strings) "unit" can be anything from `'Y'`, `'W'`, `'D'`, `'h'`, `'m'`, `'s'`, `'ms'`, `'us'` or `'ns'`. It only defines how the number is interpreted: since pandas 3.1 the returned resolution is `'us'`, or `'ns'` if the input needs nanosecond precision. -In normal operation {py:class}`pandas.Timestamp` holds the timestamp in the provided resolution, but only one of `'s'`, `'ms'`, `'us'`, `'ns'`. Lower resolution input is automatically converted to `'s'`, higher resolution input is truncated to `'ns'`. +{py:class}`pandas.Timestamp` holds the timestamp in one of `'s'`, `'ms'`, `'us'`, `'ns'`. Created from a {py:class}`numpy.datetime64` it keeps that resolution, lower resolution input is converted to `'s'`, higher resolution input is truncated to `'ns'`. The same conversion rules apply here as for {py:func}`pandas.to_timedelta` (see [to_timedelta]). Depending on the internal resolution Timestamps can be represented in the range: @@ -222,7 +222,7 @@ Depending on the internal resolution Timestamps can be represented in the range: ```{code-cell} for unit in ["s", "ms", "us", "ns"]: print( - f"unit: {unit!r} time range ({pd.Timestamp(int64_min, unit=unit)}, {pd.Timestamp(int64_max, unit=unit)})" + f"unit: {unit!r} time range ({pd.Timestamp(np.datetime64(int64_min, unit))}, {pd.Timestamp(np.datetime64(int64_max, unit))})" ) ``` diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 21f3671188a..3680e9a6b7b 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -406,6 +406,9 @@ Documentation (:issue:`10832`, :pull:`11156`). By `dolliecoder `_ and `Michael Niklas `_. +- Fix the time coding docs for pandas 3.1, which now gives microsecond + resolution for numeric input with any ``unit``. + By `Michael Niklas `_. Performance ~~~~~~~~~~~ From af8b0caf1b4ded3f7b47ce9c17ea6257ca3a0d7b Mon Sep 17 00:00:00 2001 From: Michael Niklas Date: Fri, 23 Oct 2026 11:28:33 +0200 Subject: [PATCH 2/2] Add PR number to whats-new Co-Authored-By: Claude Opus 5.5 --- doc/whats-new.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 3680e9a6b7b..ca0091d97b8 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -407,7 +407,7 @@ Documentation By `dolliecoder `_ and `Michael Niklas `_. - Fix the time coding docs for pandas 3.1, which now gives microsecond - resolution for numeric input with any ``unit``. + resolution for numeric input with any ``unit`` (:pull:`11796`). By `Michael Niklas `_. Performance