Thanks to visit codestin.com
Credit goes to github.com

Skip to content

DOC: update datetime documentation to explain that "NaT" also requires specific unit #31282

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
charris merged 4 commits into from
Apr 23, 2026
+36 −14
Merged

DOC: update datetime documentation to explain that "NaT" also requires specific unit #31282

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9b63788
DOC: update datetime documentation to explain NaT also requires speci…
riku-sakamoto Apr 20, 2026
3720a77
DOC: tweak the wording.
riku-sakamoto Apr 20, 2026
fb8f5d7
DOC: Add linebreaks following to review
riku-sakamoto Apr 20, 2026
e02b7a4
DOC: Address review comments
riku-sakamoto Apr 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 36 additions & 14 deletions doc/source/reference/arrays.datetime.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,8 @@ as ``now``.

NAT (not a time):

>>> np.datetime64('nat')
np.datetime64('NaT')
>>> np.datetime64('nat', 'D')
np.datetime64('NaT', 'D')

The current time (UTC, default second precision):

Expand All @@ -118,6 +118,12 @@ When creating an array of datetimes from a string, it is still possible
to automatically select the unit from the inputs, by using the
datetime type with generic units.

.. deprecated:: 2.5
The generic units of `timedelta64` were deprecated in NumPy 2.5 and
will raise an error in the future. With this change,
``NaT`` in `datetime64` is now required to have an explicit time unit.


.. admonition:: Example

.. try_examples::
Expand Down Expand Up @@ -218,8 +224,8 @@ data type also accepts the string "NAT" in place of the number for a "Not A Time
>>> np.timedelta64(4, 'h')
np.timedelta64(4,'h')

>>> np.timedelta64('nAt')
np.timedelta64('NaT')
>>> np.timedelta64('nAt', 'D')
np.timedelta64('NaT', 'D')

Datetimes and Timedeltas work together to provide ways for
simple datetime calculations.
Expand All @@ -245,11 +251,11 @@ simple datetime calculations.
>>> np.timedelta64(1,'W') % np.timedelta64(10,'D')
np.timedelta64(7,'D')

>>> np.datetime64('nat') - np.datetime64('2009-01-01')
>>> np.datetime64('nat', 'D') - np.datetime64('2009-01-01')
np.timedelta64('NaT','D')

>>> np.datetime64('2009-01-01') + np.timedelta64('nat')
np.datetime64('NaT')
>>> np.datetime64('2009-01-01') + np.timedelta64('nat', 'D')
np.datetime64('NaT', 'D')

There are two Timedelta units ('Y', years and 'M', months) which are treated
specially, because how much time they represent changes depending
Expand Down Expand Up @@ -285,7 +291,8 @@ The Datetime and Timedelta data types support a large number of time
units, as well as generic units which can be coerced into any of the
other units based on input data.
The generic units are deprecated since NumPy 2.5
and will raise an error in the future. Migration guidance is provided in the `migration guide for deprecation of generic units`_ section below.
and will raise an error in the future. Migration guidance is provided
in the `migration guide for deprecation of generic units`_ section below.

Datetimes are always stored with
an epoch of 1970-01-01T00:00. This means the supported dates are
Expand Down Expand Up @@ -349,7 +356,7 @@ The protocol is described in the following table:


.. deprecated:: 2.5
The generic units of `timedelta64` are deprecated since NumPy 2.5 and
The generic units of `timedelta64` are deprecated in NumPy 2.5 and
will raise an error in the future.


Expand All @@ -359,10 +366,10 @@ The protocol is described in the following table:

>>> import numpy as np

>>> type(np.datetime64('NaT').item())
>>> type(np.datetime64('NaT', 'D').item())
<class 'NoneType'>

>>> type(np.timedelta64('NaT').item())
>>> type(np.timedelta64('NaT', 'D').item())
<class 'NoneType'>

>>> type(np.timedelta64(123, 'ns').item())
Expand All @@ -375,7 +382,9 @@ The protocol is described in the following table:
<class 'datetime.timedelta'>


In the case where conversion of `datetime64` and/or `timedelta64` is done against Python types like ``int``, ``float``, and ``str`` the corresponding return types will be ``np.str_``, ``np.int64`` and ``np.float64``.
In the case where conversion of `datetime64` and/or `timedelta64` is done
against Python types like ``int``, ``float``, and ``str`` the corresponding return types
will be ``np.str_``, ``np.int64`` and ``np.float64``.


.. admonition:: Example
Expand Down Expand Up @@ -653,9 +662,12 @@ Migration guide for deprecation of generic units
The generic units of `timedelta64` are deprecated since NumPy 2.5
and will raise an error in the future.
This section provides guidance on how to update code
that uses generic units of `timedelta64` to avoid future errors.
that uses generic units of `timedelta64` and `datetime64` to avoid future errors.

The straight forward way is to replace the generic unit with a specific time unit such as 'D' (day), 'h' (hour), 'm' (minute), 's' (second), etc. The choice of the specific time unit will depend on the context of your code and the level of precision you require.
The straight forward way is to replace the generic unit with a specific time unit
such as 'D' (day), 'h' (hour), 'm' (minute), 's' (second), etc.
The choice of the specific time unit will depend on the context of your code and
the level of precision you require.


.. admonition:: Example
Expand Down Expand Up @@ -686,3 +698,13 @@ The straight forward way is to replace the generic unit with a specific time uni

>>> arr = np.ones(5, dtype='m8[s]')
>>> np.testing.assert_allclose(arr, np.timedelta64(1, "s"), atol=np.timedelta64(0, "s"))

Previously, `datetime64` allowed `NaT` without specifying a time unit.
With the deprecation of generic units, `NaT` is now required to have an explicit time unit
for consistency with other datetime and timedelta operations.

Copy link
Copy Markdown
Member

@charris charris Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Be nice to break the long lines here and elsewhere. You need hard linebreaks.

Copy link
Copy Markdown
Contributor Author

@riku-sakamoto riku-sakamoto Apr 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the review! I've updated them accordingly.

>>> np.datetime64("NAT")
DeprecationWarning: The 'generic' unit for NumPy timedelta is deprecated, and will raise an error in the future. This includes implicit conversion of bare integers (e.g. `+ 1`).Please use a specific unit instead.
Copy link
Copy Markdown
Member

@charris charris Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI suggests you can break this like so:

>>> np.datetime64("NAT")
DeprecationWarning: The 'generic' unit for NumPy timedelta is deprecated, ... Please use a specific unit instead.

I don't know if that works. We should probably fix the warning text.

Copy link
Copy Markdown
Contributor Author

@riku-sakamoto riku-sakamoto Apr 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left it as is because this is inside a code snippet.
When I tried to break the lines, the documentation ended up like below, so the line breaks appear as is.

Would you prefer line breaks even inside a code snippet, or should I keep it?

image

Copy link
Copy Markdown
Member

@charris charris Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

AI suggested shortening the output line using elipses ... for missing text. I don't know if it works, but maybe worth a try to find out. No, I wouldn't break the line.

Copy link
Copy Markdown
Contributor Author

@riku-sakamoto riku-sakamoto Apr 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the clarification.

I tried it locally, but I’m not sure if it improves the situation because it still doesn't fit one page width
Anyway, if you prefer, I am happy to push the changes.

image

Copy link
Copy Markdown
Member

@charris charris Apr 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If it works, we can always shorten the line more. I assume it worked? That is good to know. I'll put this in and you can make another PR if the improvement looks good. I think we could break it right after the elipses. It is just an example, if it occurs in the wild the user will see the whole thing.

Strictly speaking, it would be better to put some line breaks in the emitted warning message.


>>> np.datetime64("NAT", "D")
np.datetime64('NaT', 'D')
Loading