From 38dcf723252b200ae1f579ce05d8fc2c49963e7f Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 12 Aug 2025 14:10:09 +0200 Subject: [PATCH 1/5] ENH/DOC: doctest doc/source/reference ReST files This still misses subdirectories. Also, some subdirectories (reference/random as an example) use `.. code-block :: python` and `.. ipython` syntax, which the doctest finder/parser misses. --- .spin/cmds.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.spin/cmds.py b/.spin/cmds.py index 66885de630e0..e89f535e5f0e 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( From f5b16a549ac2b378774c06c75a0d46d5fce0d232 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 12 Aug 2025 14:46:07 +0200 Subject: [PATCH 2/5] DOC: tweak arrays.promotion.rst for warnings There is no good way to show both the result *and* a warning in the doctesting machinery otherwise. --- doc/source/reference/arrays.promotion.rst | 28 +++++++++++++++++++---- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/doc/source/reference/arrays.promotion.rst b/doc/source/reference/arrays.promotion.rst index d2dead0ce7b5..166c5e85526a 100644 --- a/doc/source/reference/arrays.promotion.rst +++ b/doc/source/reference/arrays.promotion.rst @@ -114,9 +114,20 @@ cannot be coerced to the NumPy dtype, an error is raised: Traceback (most recent call last): ... OverflowError: Python int too large to convert to C long + + For floating-point values, however, NumPy returns an infinity and emits a warning: + >>> np.float32(1) + 1e300 + Traceback (most recent call last): + ... + RuntimeWarning: overflow encountered in cast + + >>> import warnings + >>> with warnings.catch_warnings(): + ... warnings.simplefilter('ignore') + ... x = np.float32(1) + 1e300 + >>> x np.float32(inf) - ... RuntimeWarning: overflow encountered in cast Second, since the Python float or integer precision is always ignored, a low precision NumPy scalar will keep using its lower precision unless explicitly @@ -125,12 +136,19 @@ converted to a higher precision NumPy dtype or Python scalar (e.g. via ``int()`` some calculations or lead to incorrect results, especially in the case of integer overflows: - >>> np.int8(100) + 100 # the result exceeds the capacity of int8 + >>> import warnings + >>> with warnings.catch_warnings(): + ... warnings.simplefilter('ignore') + ... x = np.int8(100) + 100 # the result exceeds the capacity of int8 + >>> x np.int8(-56) - ... RuntimeWarning: overflow encountered in scalar add -Note that NumPy warns when overflows occur for scalars, but not for arrays; -e.g., ``np.array(100, dtype="uint8") + 100`` will *not* warn. + +Note that NumPy warns when overflows occur for scalars, but not for arrays: + + >>> np.array(100, dtype="int8") + 100 + np.int8(-56) # overflows, does not warn + Numerical promotion ------------------- From 1d57c4843d40ef951da6c7cf98253a4f18a475d1 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 12 Aug 2025 14:59:36 +0200 Subject: [PATCH 3/5] DOC: tweak arrays.promotion.rst for warnings --- doc/source/reference/constants.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/source/reference/constants.rst b/doc/source/reference/constants.rst index 79d758bddada..42ee3079b5b8 100644 --- a/doc/source/reference/constants.rst +++ b/doc/source/reference/constants.rst @@ -67,7 +67,11 @@ NumPy includes several constants: >>> import numpy as np >>> np.inf inf - >>> np.array([1]) / 0. + >>> import warnings + >>> with warnings.catch_warnings(): + ... warnings.simplefilter('ignore') + ... x = np.array([1]) / 0. # emits a 'Division by zero' warning + >>> x array([inf]) From 894f2782d022cf5582d2448050ed56afb57a9619 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 12 Aug 2025 14:59:59 +0200 Subject: [PATCH 4/5] DOC: fix doctests in doc/source/reference --- doc/source/reference/arrays.classes.rst | 2 +- doc/source/reference/arrays.datetime.rst | 10 +++++----- doc/source/reference/arrays.ndarray.rst | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/source/reference/arrays.classes.rst b/doc/source/reference/arrays.classes.rst index 80821c2c08fa..1a19131395e7 100644 --- a/doc/source/reference/arrays.classes.rst +++ b/doc/source/reference/arrays.classes.rst @@ -682,7 +682,7 @@ iterating. The ndenumerate iterator can achieve this. >>> import numpy as np >>> for i, val in np.ndenumerate(a): ... if sum(i)%5 == 0: - print(i, val) + ... print(i, val) (0, 0, 0) 10 (1, 1, 3) 25 (2, 0, 3) 29 diff --git a/doc/source/reference/arrays.datetime.rst b/doc/source/reference/arrays.datetime.rst index 2095dc3aea49..cde058d09a97 100644 --- a/doc/source/reference/arrays.datetime.rst +++ b/doc/source/reference/arrays.datetime.rst @@ -90,12 +90,12 @@ returns the current UTC date with day precision. NAT (not a time): >>> np.datetime64('nat') - np.datetime64('NaT') + np.datetime64('NaT','generic') The current date: >>> np.datetime64('today') - np.datetime64('2025-08-05') # result will depend on the current date + np.datetime64('2025-08-05') # may vary: result will depend on the current date When creating an array of datetimes from a string, it is still possible to automatically select the unit from the inputs, by using the @@ -232,7 +232,7 @@ simple datetime calculations. np.timedelta64('NaT','D') >>> np.datetime64('2009-01-01') + np.timedelta64('nat') - np.datetime64('NaT') + 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 @@ -253,7 +253,7 @@ calculating the averaged values from the 400 year leap-year cycle. >>> a = np.timedelta64(1, 'Y') >>> np.timedelta64(a, 'M') - numpy.timedelta64(12,'M') + np.timedelta64(12,'M') >>> np.timedelta64(a, 'D') Traceback (most recent call last): @@ -548,7 +548,7 @@ given below. >>> a = np.datetime64("0000-01-01", "us") >>> b = np.datetime64("1600-01-01", "us") >>> b - a - numpy.timedelta64(50491123200000000,'us') + np.timedelta64(50491123200000000,'us') The computed results, `50491123200` seconds, are obtained as the elapsed number of days (`584388`) times `86400` seconds; this is the number of diff --git a/doc/source/reference/arrays.ndarray.rst b/doc/source/reference/arrays.ndarray.rst index 4dca5b541a38..86b0331ed601 100644 --- a/doc/source/reference/arrays.ndarray.rst +++ b/doc/source/reference/arrays.ndarray.rst @@ -51,7 +51,7 @@ objects implementing the :class:`memoryview` or :ref:`array >>> # The element of x in the *second* row, *third* column, namely, 6. >>> x[1, 2] - 6 + np.int32(6) For example :ref:`slicing ` can produce views of the array: From fa44f3805812af5f7f9b04578fd453b2e026dd87 Mon Sep 17 00:00:00 2001 From: Evgeni Burovski Date: Tue, 12 Aug 2025 15:17:48 +0200 Subject: [PATCH 5/5] MAINT/DOC: skip problematic rst files in doc/source/reference [skip actions][skip azp][skip cirrus] --- numpy/conftest.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/numpy/conftest.py b/numpy/conftest.py index fde4defc926d..0ed558e072f5 100644 --- a/numpy/conftest.py +++ b/numpy/conftest.py @@ -220,6 +220,9 @@ def warnings_errors_and_rng(test=None): 'basics.dispatch.rst': 'errors out in /testing/overrides.py', 'basics.subclassing.rst': '.. testcode:: admonitions not understood', 'misc.rst': 'manipulates warnings', + 'arrays.nditer.cython.rst': 'uses non-python syntax', + 'distutils.rst': '', + 'coremath.rst': 'numpy.distutils does not exis' } # ignores are for things fail doctest collection (optionals etc)