Skip to content

DOC: Add 'now' string to datetime64 documentation #29534

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

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

DOC: Add 'now' string to datetime64 documentation #29534

wants to merge 1 commit into from
+18 −2

Conversation

lzblack
Copy link
Contributor

@lzblack lzblack commented Aug 9, 2025

Summary

This PR adds documentation for the string "now" as a valid argument to np.datetime64.

The string "now" returns the current UTC time. By default, it uses second (s) precision, but you can specify a different unit (e.g., 'M', 'D', 'h') to truncate the result to that precision. Units finer than seconds (such as 'ms' or 'ns') are supported but will display fractional parts as zeros, effectively truncating to whole seconds. This behavior is already supported internally but was previously undocumented.

✅ Example added

>>> np.datetime64('now')
np.datetime64('2025-08-05T02:22:14')  # result will depend on the current time

>>> np.datetime64('now', 'D')
np.datetime64('2025-08-05')

>>> np.datetime64('now', 'ms')
np.datetime64('2025-08-05T02:22:14.000')

The example is placed immediately before the "today" example in the "Basic datetimes" section, so readers can compare their behaviors easily.

Context

  • Issue #10003 discusses undocumented support for "now" and notes its UTC semantics and default second-level precision.
  • PR #26477 proposed documenting "now" with an example, but was closed without merge due to procedural issues.
  • PR #29514 documented "today" string (merged), adding its explanation and example to this section.

This PR documents "now" with explicit mention of its default precision, UTC behavior, and unit truncation to address potential user confusion.

Thanks for considering this improvement!

@mattip
Copy link
Member

mattip commented Aug 10, 2025

How are these documentation examples passing the doctests without any hints to doctest to ignore the results? @ev-br are we running doctests on this?

@ev-br
Copy link
Contributor

ev-br commented Aug 10, 2025

are we running doctests on this?

We don't and I don't know if we ever did :-).

Applying

$ git diff
diff --git a/.spin/cmds.py b/.spin/cmds.py
index 66885de630..e89f535e5f 100644
--- a/.spin/cmds.py
+++ b/.spin/cmds.py
@@ -242,7 +242,7 @@ def check_tutorials(*, parent_callback, pytest_args, **kwargs):
     #   - `spin check-tutorials path/to/rst`, and
     #   - `spin check-tutorials path/to/rst -- --durations=3`
     if (not pytest_args) or all(arg.startswith('-') for arg in pytest_args):
-        pytest_args = ('doc/source/user',) + pytest_args
+        pytest_args = ('doc/source/user', 'doc/source/reference/') + pytest_args
 
     # make all paths relative to the numpy source folder
     pytest_args = tuple(

produces on main

$ spin check-tutorials -v
Invoking `build` prior to running tests:
$ /home/br/miniforge3/envs/numpy-dev/bin/python3.12 vendored-meson/meson/meson.py compile -C build
INFO: autodetecting backend as ninja
INFO: calculating backend command to run: /home/br/miniforge3/envs/numpy-dev/bin/ninja -C /home/br/repos/numpy/build
ninja: Entering directory `/home/br/repos/numpy/build'
[1/1] Generating numpy/generate-version with a custom command
Saving version to numpy/version.py
$ /home/br/miniforge3/envs/numpy-dev/bin/python3.12 vendored-meson/meson/meson.py install --only-changed -C build --destdir ../build-install
$ export PYTHONPATH="/home/br/repos/numpy/build-install/usr/lib/python3.12/site-packages"
$ /home/br/miniforge3/envs/numpy-dev/bin/python3.12 -P -c 'import numpy'
$ cd /home/br/repos/numpy/build-install/usr/lib/python3.12/site-packages
$ /home/br/miniforge3/envs/numpy-dev/bin/python3.12 -P -m pytest -v -m 'not slow' /home/br/repos/numpy/.spin/../doc/source/user /home/br/repos/numpy/.spin/../doc/source/reference '--doctest-glob=*rst'
============================================ test session starts ============================================
platform linux -- Python 3.12.10, pytest-8.3.5, pluggy-1.6.0 -- /home/br/miniforge3/envs/numpy-dev/bin/python3.12
cachedir: .pytest_cache
hypothesis profile 'np.test() profile' -> database=None, deadline=None, print_blob=True, derandomize=True, suppress_health_check=(HealthCheck.data_too_large, HealthCheck.filter_too_much, HealthCheck.too_slow, HealthCheck.large_base_example, HealthCheck.function_scoped_fixture, HealthCheck.differing_executors, HealthCheck.nested_given)
rootdir: /home/br/repos/numpy
configfile: pytest.ini
plugins: scipy_doctest-1.9.0.dev0, anyio-4.9.0, xdist-3.7.0, hypothesis-6.131.30, cov-6.1.1
collected 47 items                                                                                          

../../../../../doc/source/user/absolute_beginners.rst::absolute_beginners.rst PASSED                  [  2%]
../../../../../doc/source/user/basics.broadcasting.rst::basics.broadcasting.rst PASSED                [  4%]
../../../../../doc/source/user/basics.copies.rst::basics.copies.rst PASSED                            [  6%]
../../../../../doc/source/user/basics.creation.rst::basics.creation.rst PASSED                        [  8%]
../../../../../doc/source/user/basics.dispatch.rst::basics.dispatch.rst XPASS (errors out in /tes...) [ 10%]
../../../../../doc/source/user/basics.indexing.rst::basics.indexing.rst PASSED                        [ 12%]
../../../../../doc/source/user/basics.interoperability.rst::basics.interoperability.rst XFAIL (ne...) [ 14%]
../../../../../doc/source/user/basics.io.genfromtxt.rst::basics.io.genfromtxt.rst PASSED              [ 17%]
../../../../../doc/source/user/basics.rec.rst::basics.rec.rst PASSED                                  [ 19%]
../../../../../doc/source/user/basics.strings.rst::basics.strings.rst PASSED                          [ 21%]
../../../../../doc/source/user/basics.subclassing.rst::basics.subclassing.rst XFAIL (.. testcode:...) [ 23%]
../../../../../doc/source/user/basics.types.rst::basics.types.rst PASSED                              [ 25%]
../../../../../doc/source/user/basics.ufuncs.rst::basics.ufuncs.rst PASSED                            [ 27%]
../../../../../doc/source/user/byteswapping.rst::byteswapping.rst PASSED                              [ 29%]
../../../../../doc/source/user/c-info.ufunc-tutorial.rst::c-info.ufunc-tutorial.rst XFAIL             [ 31%]
../../../../../doc/source/user/how-to-index.rst::how-to-index.rst PASSED                              [ 34%]
../../../../../doc/source/user/how-to-io.rst::how-to-io.rst PASSED                                    [ 36%]
../../../../../doc/source/user/how-to-partition.rst::how-to-partition.rst PASSED                      [ 38%]
../../../../../doc/source/user/how-to-print.rst::how-to-print.rst PASSED                              [ 40%]
../../../../../doc/source/user/how-to-verify-bug.rst::how-to-verify-bug.rst XFAIL                     [ 42%]
../../../../../doc/source/user/misc.rst::misc.rst XFAIL (manipulates warnings)                        [ 44%]
../../../../../doc/source/user/numpy-for-matlab-users.rst::numpy-for-matlab-users.rst PASSED          [ 46%]
../../../../../doc/source/user/quickstart.rst::quickstart.rst PASSED                                  [ 48%]
../../../../../doc/source/user/troubleshooting-importerror.rst::troubleshooting-importerror.rst PASSED [ 51%]
../../../../../doc/source/reference/array_api.rst::array_api.rst FAILED                               [ 53%]
../../../../../doc/source/reference/arrays.classes.rst::arrays.classes.rst FAILED                     [ 55%]
../../../../../doc/source/reference/arrays.datetime.rst::arrays.datetime.rst FAILED                   [ 57%]
../../../../../doc/source/reference/arrays.dtypes.rst::arrays.dtypes.rst PASSED                       [ 59%]
../../../../../doc/source/reference/arrays.ndarray.rst::arrays.ndarray.rst FAILED                     [ 61%]
../../../../../doc/source/reference/arrays.nditer.cython.rst::arrays.nditer.cython.rst FAILED         [ 63%]
../../../../../doc/source/reference/arrays.nditer.rst::arrays.nditer.rst PASSED                       [ 65%]
../../../../../doc/source/reference/arrays.promotion.rst::arrays.promotion.rst FAILED                 [ 68%]
../../../../../doc/source/reference/arrays.scalars.rst::arrays.scalars.rst PASSED                     [ 70%]
../../../../../doc/source/reference/c-api/coremath.rst::coremath.rst FAILED                           [ 72%]
../../../../../doc/source/reference/constants.rst::constants.rst PASSED                               [ 74%]
../../../../../doc/source/reference/distutils.rst::distutils.rst FAILED                               [ 76%]
../../../../../doc/source/reference/maskedarray.baseclass.rst::maskedarray.baseclass.rst PASSED       [ 78%]
../../../../../doc/source/reference/maskedarray.generic.rst::maskedarray.generic.rst PASSED           [ 80%]
../../../../../doc/source/reference/random/generator.rst::generator.rst PASSED                        [ 82%]
../../../../../doc/source/reference/random/index.rst::index.rst PASSED                                [ 85%]
../../../../../doc/source/reference/routines.char.rst::routines.char.rst PASSED                       [ 87%]
../../../../../doc/source/reference/routines.emath.rst::routines.emath.rst PASSED                     [ 89%]
../../../../../doc/source/reference/routines.polynomials.classes.rst::routines.polynomials.classes.rst PASSED [ 91%]
../../../../../doc/source/reference/routines.polynomials.rst::routines.polynomials.rst PASSED         [ 93%]
../../../../../doc/source/reference/routines.rec.rst::routines.rec.rst PASSED                         [ 95%]
../../../../../doc/source/reference/routines.strings.rst::routines.strings.rst PASSED                 [ 97%]
../../../../../doc/source/reference/routines.version.rst::routines.version.rst PASSED         

.... snip ...

============================ 8 failed, 33 passed, 5 xfailed, 1 xpassed in 1.56s =============================

Some errors are relatively mild and are easy to fix or work around. Otherwise, there's a list problematic tutorials to skip wholesale: https://github.com/numpy/numpy/blob/main/numpy/conftest.py#L215

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
04 - Documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@lzblack @mattip @ev-br