From d17824fbea5c23971e43d6497d1a8e90d1b9483e Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 3 Mar 2024 20:38:52 +0100 Subject: [PATCH 1/3] DOC: clean up "Release notes" doc page with smaller toctree The page was almost completely unreadable before, and the level 3 section headers were a random grab bag of topics. Now it's down to version numbers and links to the main sections (Improvements, Pull requests merged, etc.). --- doc/source/release.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/release.rst b/doc/source/release.rst index cd0003d4df4e..41eeac87bf64 100644 --- a/doc/source/release.rst +++ b/doc/source/release.rst @@ -3,7 +3,7 @@ Release notes ************* .. toctree:: - :maxdepth: 3 + :maxdepth: 2 2.0.0 1.26.4 From 34a81708883641155bf370b5c7349939b6816244 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 3 Mar 2024 20:42:56 +0100 Subject: [PATCH 2/3] DOC: incorporate "upcoming changes" fragments into 2.0.0 release notes --- doc/release/upcoming_changes/25168.change.rst | 21 ---- doc/release/upcoming_changes/25754.c_api.rst | 13 --- doc/release/upcoming_changes/25812.c_api.rst | 7 -- doc/release/upcoming_changes/25816.c_api.rst | 12 -- doc/release/upcoming_changes/25816.change.rst | 6 - doc/release/upcoming_changes/25866.c_api.rst | 14 --- doc/source/reference/c-api/array.rst | 2 +- doc/source/release/2.0.0-notes.rst | 103 +++++++++++++++++- 8 files changed, 101 insertions(+), 77 deletions(-) delete mode 100644 doc/release/upcoming_changes/25168.change.rst delete mode 100644 doc/release/upcoming_changes/25754.c_api.rst delete mode 100644 doc/release/upcoming_changes/25812.c_api.rst delete mode 100644 doc/release/upcoming_changes/25816.c_api.rst delete mode 100644 doc/release/upcoming_changes/25816.change.rst delete mode 100644 doc/release/upcoming_changes/25866.c_api.rst diff --git a/doc/release/upcoming_changes/25168.change.rst b/doc/release/upcoming_changes/25168.change.rst deleted file mode 100644 index 139c15679f6f..000000000000 --- a/doc/release/upcoming_changes/25168.change.rst +++ /dev/null @@ -1,21 +0,0 @@ -New ``copy`` keyword meaning for `numpy.array` and `numpy.asarray` ------------------------------------------------------------------- -Now `numpy.array` and `numpy.asarray` support three values for ``copy`` parameter: - -* ``None`` - A copy will only be made if it is necessary. -* ``True`` - Always make a copy. -* ``False`` - Never make a copy. If a copy is required a ``ValueError`` is raised. - -The meaning of ``False`` changed as it now raises an exception if a copy is needed. - -The ``__array__`` special method now takes a ``copy`` keyword argument. ------------------------------------------------------------------------ - -NumPy will pass ``copy`` to the ``__array__`` special method in situations where -it would be set to a non-default value (e.g. in a call to -``np.asarray(some_object, copy=False)``). Currently, if an -unexpected keyword argument error is raised after this, NumPy will print a -warning and re-try without the ``copy`` keyword argument. Implementations of -objects implementing the ``__array__`` protocol should accept a ``copy`` keyword -argument with the same meaning as when passed to `numpy.array` or -`numpy.asarray`. diff --git a/doc/release/upcoming_changes/25754.c_api.rst b/doc/release/upcoming_changes/25754.c_api.rst deleted file mode 100644 index 43c1b6e4e499..000000000000 --- a/doc/release/upcoming_changes/25754.c_api.rst +++ /dev/null @@ -1,13 +0,0 @@ -New Public DType API --------------------- - -The C implementation of the NEP 42 DType API is now public. While the DType API -has shipped in NumPy for a few versions, it was only usable in sessions with a -special environment variable set. It is now possible to write custom DTypes -outside of NumPy using the new DType API and the normal ``import_array()`` -mechanism for importing the numpy C API. - -See :ref:`dtype-api` for more details about the API. As always with a new -feature, please report any bugs you run into implementing or using a new -DType. It is likely that downstream C code that works with dtypes will need to -be updated to work correctly with new DTypes. diff --git a/doc/release/upcoming_changes/25812.c_api.rst b/doc/release/upcoming_changes/25812.c_api.rst deleted file mode 100644 index 7aa00aad0d8b..000000000000 --- a/doc/release/upcoming_changes/25812.c_api.rst +++ /dev/null @@ -1,7 +0,0 @@ -* The ``->f`` slot has been removed from ``PyArray_Descr``. - If you use this slot, replace accessing it with - `PyDataType_GetArrFuncs` (see its documentation and the `numpy-2-migration-guide`_). - In some cases using other functions like ``PyArray_GETITEM`` may - be an alterantives. -* ``PyArray_GETITEM`` and ``PyArray_SETITEM`` now require the import of the - NumPy API table to be used and are no longer defined in ``ndarraytypes.h``. \ No newline at end of file diff --git a/doc/release/upcoming_changes/25816.c_api.rst b/doc/release/upcoming_changes/25816.c_api.rst deleted file mode 100644 index dda91811cbf9..000000000000 --- a/doc/release/upcoming_changes/25816.c_api.rst +++ /dev/null @@ -1,12 +0,0 @@ -* Due to runtime dependencies, the definition for functionality accessing - the dtype flags was moved from ``numpy/ndarraytypes.h`` and is only available - after including ``numpy/ndarrayobject.h`` as it requires ``import_array()``. - This includes ``PyDataType_FLAGCHK``, ``PyDataType_REFCHK`` and - ``NPY_BEGIN_THREADS_DESCR``. -* The dtype flags on ``PyArray_Descr`` must now be accessed through the - ``PyDataType_FLAGS`` inline function to be compatible with both 1.x and 2.x. - This function is defined in ``npy_2_compat.h`` to allow backporting. - Most or all users should use ``PyDataType_FLAGCHK`` which is available on - 1.x and does not require backporting. - *Cython* users should use Cython 3. Otherwise access will go through Python - unless they use ``PyDataType_FLAGCHK`` instead. diff --git a/doc/release/upcoming_changes/25816.change.rst b/doc/release/upcoming_changes/25816.change.rst deleted file mode 100644 index bb608516b31e..000000000000 --- a/doc/release/upcoming_changes/25816.change.rst +++ /dev/null @@ -1,6 +0,0 @@ -* The ``dtype.flags`` value was previously usually stored as a - signed integer. This means that the aligned dtype struct flag - lead to negative flags being set (-128 rather than ``128``). - This flag is now stored usigned (positive). - Code which checks flags manually may need to adapt. This - may include code compiled with Cython 2. diff --git a/doc/release/upcoming_changes/25866.c_api.rst b/doc/release/upcoming_changes/25866.c_api.rst deleted file mode 100644 index 0da08d3d5539..000000000000 --- a/doc/release/upcoming_changes/25866.c_api.rst +++ /dev/null @@ -1,14 +0,0 @@ -New C-API import functions --------------------------- -We have now added ``PyArray_ImportNumPyAPI`` and ``PyUFunc_ImportUFuncAPI`` -as static inline functions to import the NumPy C-API tables. -The new functions have two advantages over `import_array` and `import_ufunc`: - -- They check whether the import was already performed and are light-weight - if not, allowing to add them judiciously (although this is not preferable - in most cases). -- The old mechanisms were macros rather than functions which included a - ``return`` statement. - -The ``PyArray_ImportNumPyAPI()`` function is included in ``npy_2_compat.h`` -for simpler backporting. diff --git a/doc/source/reference/c-api/array.rst b/doc/source/reference/c-api/array.rst index 8a9661e17ac1..9721cbc274d9 100644 --- a/doc/source/reference/c-api/array.rst +++ b/doc/source/reference/c-api/array.rst @@ -3318,7 +3318,7 @@ Data Type Promotion and Inspection for a ``singleton`` first and only calls the ``default_descr`` function if necessary. -.. dtype-api_ +.. _dtype-api: Custom Data Types ----------------- diff --git a/doc/source/release/2.0.0-notes.rst b/doc/source/release/2.0.0-notes.rst index f9bf1f28f1d0..5487df0d7489 100644 --- a/doc/source/release/2.0.0-notes.rst +++ b/doc/source/release/2.0.0-notes.rst @@ -342,6 +342,31 @@ C API changes (`gh-25789 `__) +* The ``->f`` slot has been removed from ``PyArray_Descr``. + If you use this slot, replace accessing it with + ``PyDataType_GetArrFuncs`` (see its documentation and the + :ref:`numpy-2-migration-guide`). In some cases using other functions like + ``PyArray_GETITEM`` may be an alternatives. +* ``PyArray_GETITEM`` and ``PyArray_SETITEM`` now require the import of the + NumPy API table to be used and are no longer defined in ``ndarraytypes.h``. + + (`gh-25812 `__) + +* Due to runtime dependencies, the definition for functionality accessing + the dtype flags was moved from ``numpy/ndarraytypes.h`` and is only available + after including ``numpy/ndarrayobject.h`` as it requires ``import_array()``. + This includes ``PyDataType_FLAGCHK``, ``PyDataType_REFCHK`` and + ``NPY_BEGIN_THREADS_DESCR``. +* The dtype flags on ``PyArray_Descr`` must now be accessed through the + ``PyDataType_FLAGS`` inline function to be compatible with both 1.x and 2.x. + This function is defined in ``npy_2_compat.h`` to allow backporting. + Most or all users should use ``PyDataType_FLAGCHK`` which is available on + 1.x and does not require backporting. + Cython users should use Cython 3. Otherwise access will go through Python + unless they use ``PyDataType_FLAGCHK`` instead. + + (`gh-25816 `__) + Datetime functionality exposed in the C API and Cython bindings --------------------------------------------------------------- @@ -357,6 +382,7 @@ external libraries. Const correctness for the generalized ufunc C API ------------------------------------------------- + The NumPy C API's functions for constructing generalized ufuncs (``PyUFunc_FromFuncAndData``, ``PyUFunc_FromFuncAndDataAndSignature``, ``PyUFunc_FromFuncAndDataAndSignatureAndIdentity``) take ``types`` and ``data`` @@ -384,6 +410,7 @@ replaced with ``NPY_RAVEL_AXIS``. See also :ref:`migration_maxdims`. ``NPY_MAXARGS`` not constant and ``PyArrayMultiIterObject`` size change ----------------------------------------------------------------------- + Since ``NPY_MAXARGS`` was increased, it is now a runtime constant and not compile-time constant anymore. We expect almost no users to notice this. But if used for stack allocations @@ -398,14 +425,50 @@ to avoid issues with Cython. Required changes for custom legacy user dtypes ---------------------------------------------- + In order to improve our DTypes it is unfortunately necessary -to break with ABI, which requires some changes for dtypes registered -with `PyArray_RegisterDataType`. -Please see the documentation of `PyArray_RegisterDataType` for how +to break the ABI, which requires some changes for dtypes registered +with ``PyArray_RegisterDataType``. +Please see the documentation of ``PyArray_RegisterDataType`` for how to adapt your code and achieve compatibility with both 1.x and 2.x. (`gh-25792 `__) +New Public DType API +-------------------- + +The C implementation of the NEP 42 DType API is now public. While the DType API +has shipped in NumPy for a few versions, it was only usable in sessions with a +special environment variable set. It is now possible to write custom DTypes +outside of NumPy using the new DType API and the normal ``import_array()`` +mechanism for importing the numpy C API. + +See :ref:`dtype-api` for more details about the API. As always with a new +feature, please report any bugs you run into implementing or using a new +DType. It is likely that downstream C code that works with dtypes will need to +be updated to work correctly with new DTypes. + +(`gh-25754 `__) + +New C-API import functions +-------------------------- + +We have now added ``PyArray_ImportNumPyAPI`` and ``PyUFunc_ImportUFuncAPI`` +as static inline functions to import the NumPy C-API tables. +The new functions have two advantages over ``import_array`` and +``import_ufunc``: + +- They check whether the import was already performed and are light-weight + if not, allowing to add them judiciously (although this is not preferable + in most cases). +- The old mechanisms were macros rather than functions which included a + ``return`` statement. + +The ``PyArray_ImportNumPyAPI()`` function is included in ``npy_2_compat.h`` +for simpler backporting. + +(`gh-25866 `__) + NumPy 2.0 C API removals ======================== @@ -983,6 +1046,14 @@ Changes (`gh-25080 `__) +* The ``dtype.flags`` value was previously usually stored as a signed integer. + This means that the aligned dtype struct flag lead to negative flags being + set (-128 rather than 128). This flag is now stored unsigned (positive). Code + which checks flags manually may need to adapt. This may include code + compiled with Cython 0.29.x. + + (`gh-25816 `__) + Representation of NumPy scalars changed --------------------------------------- As per :ref:`NEP 51 `, the scalar representation has been @@ -1127,6 +1198,32 @@ Any out of bound axis value will now error, make sure to use (`gh-25149 `__) +New ``copy`` keyword meaning for `numpy.array` and `numpy.asarray` +------------------------------------------------------------------ +Now `numpy.array` and `numpy.asarray` support three values for ``copy`` parameter: + +* ``None`` - A copy will only be made if it is necessary. +* ``True`` - Always make a copy. +* ``False`` - Never make a copy. If a copy is required a ``ValueError`` is raised. + +The meaning of ``False`` changed as it now raises an exception if a copy is needed. + +(`gh-25168 `__) + +The ``__array__`` special method now takes a ``copy`` keyword argument. +----------------------------------------------------------------------- + +NumPy will pass ``copy`` to the ``__array__`` special method in situations where +it would be set to a non-default value (e.g. in a call to +``np.asarray(some_object, copy=False)``). Currently, if an +unexpected keyword argument error is raised after this, NumPy will print a +warning and re-try without the ``copy`` keyword argument. Implementations of +objects implementing the ``__array__`` protocol should accept a ``copy`` keyword +argument with the same meaning as when passed to `numpy.array` or +`numpy.asarray`. + +(`gh-25168 `__) + Cleanup of initialization of ``numpy.dtype`` with strings with commas --------------------------------------------------------------------- The interpretation of strings with commas is changed slightly, in that a From 5a2a29559193c89ec475c72a22d29111d54c29a8 Mon Sep 17 00:00:00 2001 From: Ralf Gommers Date: Sun, 3 Mar 2024 23:34:52 +0100 Subject: [PATCH 3/3] DOC: complete copy-edit of the 2.0.0 release notes Fixes textual and formatting issues, adds missing section headers, groups some entries that belonged together in one section, etc. [skip actions] [skip cirrus] [skip azp] --- doc/source/release/2.0.0-notes.rst | 534 +++++++++++++++-------------- 1 file changed, 279 insertions(+), 255 deletions(-) diff --git a/doc/source/release/2.0.0-notes.rst b/doc/source/release/2.0.0-notes.rst index 5487df0d7489..255d7037f8b4 100644 --- a/doc/source/release/2.0.0-notes.rst +++ b/doc/source/release/2.0.0-notes.rst @@ -71,7 +71,7 @@ NumPy 2.0 Python API removals * Alias ``np.mat`` has been removed. Use ``np.asmatrix`` instead. -* ``np.issubclass_`` has been removed. Use ``issubclass`` builtin instead. +* ``np.issubclass_`` has been removed. Use the ``issubclass`` builtin instead. * ``np.asfarray`` has been removed. Use ``np.asarray`` with a proper dtype instead. @@ -96,7 +96,8 @@ NumPy 2.0 Python API removals * ``np.find_common_type`` has been removed. Use ``numpy.promote_types`` or ``numpy.result_type`` instead. To achieve semantics for the ``scalar_types`` - argument, use ``numpy.result_type`` and pass the Pythonvalues ``0``, ``0.0``, or ``0j``. + argument, use ``numpy.result_type`` and pass ``0``, ``0.0``, or ``0j`` as a + Python scalar instead. * ``np.round_`` has been removed. Use ``np.round`` instead. @@ -116,7 +117,7 @@ NumPy 2.0 Python API removals (`gh-24587 `__) -* Seven data type aliases have been removed from ``np.dtype(alias)`` search: +* Support for seven data type string aliases has been removed from ``np.dtype``: ``int0``, ``uint0``, ``void0``, ``object0``, ``str0``, ``bytes0`` and ``bool8``. (`gh-24807 `__) @@ -130,17 +131,16 @@ NumPy 2.0 Python API removals ``__array_prepare__`` is removed -------------------------------- + UFuncs called ``__array_prepare__`` before running computations for normal ufunc calls (not generalized ufuncs, reductions, etc.). The function was also called instead of ``__array_wrap__`` on the results of some linear algebra functions. -It is now removed, if you use it (e.g. old unit implementations) -migrate to ``__array_ufunc__`` or rely on ``__array_wrap__`` -which is called with a context in all cases, although after the -result array is filled. -In those paths, ``__array_wrap__`` will now be passed a base -class, rather than a subclass array. +It is now removed. If you use it, migrate to ``__array_ufunc__`` or rely on +``__array_wrap__`` which is called with a context in all cases, although only +after the result array is filled. In those code paths, ``__array_wrap__`` will +now be passed a base class, rather than a subclass array. (`gh-25105 `__) @@ -169,35 +169,32 @@ Deprecations (`gh-24445 `__) * ``__array_wrap__`` is now passed ``arr, context, return_scalar`` and - implementations not accepting all three are deprecated. It's signature + support for implementations not accepting all three are deprecated. Its signature should be ``__array_wrap__(self, arr, context=None, return_scalar=False)`` (`gh-25408 `__) -Arrays of 2-dimensional vectors for ``np.cross`` have been deprecated. -Use arrays of 3-dimensional vectors instead. +* Arrays of 2-dimensional vectors for ``np.cross`` have been deprecated. Use + arrays of 3-dimensional vectors instead. -(`gh-24818 `__) + (`gh-24818 `__) -``np.dtype("a")`` alias for ``np.dtype(np.bytes_)`` was deprecated. -Use ``np.dtype("S")`` alias instead. +* ``np.dtype("a")`` alias for ``np.dtype(np.bytes_)`` was deprecated. Use + ``np.dtype("S")`` alias instead. -(`gh-24854 `__) + (`gh-24854 `__) -Use of keyword arguments ``x`` and ``y`` with functions -`numpy.testing.assert_array_equal` and -`numpy.testing.assert_array_almost_equal` -has been deprecated. Pass the first two arguments as positional arguments, -instead. +* Use of keyword arguments ``x`` and ``y`` with functions + ``assert_array_equal`` and ``assert_array_almost_equal`` has been deprecated. + Pass the first two arguments as positional arguments instead. -(`gh-24978 `__) + (`gh-24978 `__) -`numpy.fft` deprecations for n-D transforms with ``None`` values in arguments ------------------------------------------------------------------------------ +`numpy.fft` deprecations for n-D transforms with None values in arguments +------------------------------------------------------------------------- -Using `numpy.fft.fftn`, `numpy.fft.ifftn`, `numpy.fft.rfftn`, -`numpy.fft.irfftn`, `numpy.fft.fft2`, `numpy.fft.ifft2`, `numpy.fft.rfft2` or -`numpy.fft.irfft2` with the ``s`` parameter set to a value that is not +Using ``fftn``, ``ifftn``, ``rfftn``, ``irfftn``, ``fft2``, ``ifft2``, +``rfft2`` or ``irfft2`` with the ``s`` parameter set to a value that is not ``None`` and the ``axes`` parameter set to ``None`` has been deprecated, in line with the array API standard. To retain current behaviour, pass a sequence [0, ..., k-1] to ``axes`` for an array of dimension k. @@ -211,8 +208,9 @@ axis, the ``s`` argument can be omitted. (`gh-25495 `__) -``np.linalg.lstsq`` now defaults to new ``rcond`` value -------------------------------------------------------- +``np.linalg.lstsq`` now defaults to a new ``rcond`` value +--------------------------------------------------------- + `~numpy.linalg.lstsq` now uses the new rcond value of the machine precision times ``max(M, N)``. Previously, the machine precision was used but a FutureWarning was given to notify that this change will happen eventually. @@ -237,14 +235,14 @@ Expired deprecations * The deprecation of ``set_numeric_ops`` and the C functions ``PyArray_SetNumericOps`` and ``PyArray_GetNumericOps`` has - been expired and the functions removed. (Deprecated NumPy 1.16) + been expired and the functions removed. (Deprecated in NumPy 1.16) (`gh-23998 `__) * The ``fasttake``, ``fastclip``, and ``fastputmask`` ``ArrFuncs`` deprecation is now finalized. * The deprecated function ``fastCopyAndTranspose`` and its C counterpart - is now removed. + are now removed. * The deprecation of ``PyArray_ScalarFromObject`` is now finalized. (`gh-24312 `__) @@ -260,9 +258,10 @@ Expired deprecations (`gh-25761 `__) -* Assigning to the data attribute is disallowed and will raise +* Assigning to the ``.data`` attribute of an ndarray is disallowed and will + raise. -* ``np.binary_repr(a, width)`` will raise if width is too small +* ``np.binary_repr(a, width)`` will raise if width is too small. * Using ``NPY_CHAR`` in ``PyArray_DescrFromType()`` will raise, use ``NPY_STRING`` ``NPY_UNICODE``, or ``NPY_VSTRING`` instead. @@ -273,17 +272,21 @@ Expired deprecations Compatibility notes =================== -``loadtxt`` and ``genfromtxt`` default to ``encoding=None`` ------------------------------------------------------------ +``loadtxt`` and ``genfromtxt`` default encoding changed +------------------------------------------------------- + ``loadtxt`` and ``genfromtxt`` now both default to ``encoding=None`` -which may mainly modifies how ``converters`` work. -These will now be passed ``str`` rather than ``bytes``, pass the +which may mainly modify how ``converters`` work. +These will now be passed ``str`` rather than ``bytes``. Pass the encoding explicitly to always get the new or old behavior. For ``genfromtxt`` the change also means that returned values will now be unicode strings rather than bytes. (`gh-25158 `__) +``f2py`` compatibility notes +---------------------------- + ``f2py`` will no longer accept ambiguous ``-m`` and ``.pyf`` CLI combinations. When more than one ``.pyf`` file is passed, an error is raised. When both ``-m`` and a ``.pyf`` is passed, a warning is emitted and the ``-m`` provided name is @@ -326,10 +329,10 @@ C API changes (`gh-24258 `__) -* A C API for working with `numpy.dtypes.StringDType` arrays has been - exposed. This includes functions for acquiring and releasing mutexes locking - access to the string data as well as packing and unpacking UTF-8 bytestreams - from array entries. +* A C API for working with `numpy.dtypes.StringDType` arrays has been exposed. + This includes functions for acquiring and releasing mutexes which lock access + to the string data, as well as packing and unpacking UTF-8 bytestreams from + array entries. * ``NPY_NTYPES`` has been renamed to ``NPY_NTYPES_LEGACY`` as it does not include new NumPy built-in DTypes. In particular the new string DType will likely not work correctly with code that handles legacy DTypes. @@ -337,8 +340,8 @@ C API changes (`gh-25347 `__) * The C-API now only exports the static inline function versions - of the array accessors (previously this dependent on using "deprecated API"). - While we discourage it, you can still use the struct fields directly. + of the array accessors (previously this depended on using "deprecated API"). + While we discourage it, the struct fields can still be used directly. (`gh-25789 `__) @@ -402,8 +405,8 @@ Larger ``NPY_MAXDIMS`` and ``NPY_MAXARGS``, ``NPY_RAVEL_AXIS`` introduced used in a stack allocation, where the increase should be safe. However, we do encourage generally to remove any use of ``NPY_MAXDIMS`` and ``NPY_MAXARGS`` to eventually allow removing the constraint completely. -For the conversion helper and C-API functions mirrowing Python ones such as -``tale``, ``NPY_MAXDIMS`` was used to mean ``axis=None`` these must be +For the conversion helper and C-API functions mirroring Python ones such as +``take``, ``NPY_MAXDIMS`` was used to mean ``axis=None``. Such usage must be replaced with ``NPY_RAVEL_AXIS``. See also :ref:`migration_maxdims`. (`gh-25149 `__) @@ -417,7 +420,7 @@ We expect almost no users to notice this. But if used for stack allocations it now must be replaced with a custom constant using ``NPY_MAXARGS`` as an additional runtime check. -The ``sizeof(PyArrayMultiIterObject)`` does now not include the full size +The ``sizeof(PyArrayMultiIterObject)`` no longer includes the full size of the object. We expect nobody to notice this change. It was necessary to avoid issues with Cython. @@ -475,9 +478,9 @@ NumPy 2.0 C API removals * ``npy_interrupt.h`` and the corresponding macros like ``NPY_SIGINT_ON`` have been removed. We recommend querying ``PyErr_CheckSignals()`` or - ``PyOS_InterruptOccurred()`` periodically. (These do currently require + ``PyOS_InterruptOccurred()`` periodically (these do currently require holding the GIL though). -* The ``noprefix.h`` header has been removed, replace missing symbols with +* The ``noprefix.h`` header has been removed. Replace missing symbols with their prefixed counterparts (usually an added ``NPY_`` or ``npy_``). (`gh-23919 `__) @@ -485,15 +488,15 @@ NumPy 2.0 C API removals * ``PyUFunc_GetPyVals``, ``PyUFunc_handlefperr``, and ``PyUFunc_checkfperr`` have been removed. If needed, a new backwards compatible function to raise floating point errors - could be restored. (There are no known users and the functions would have made - ``with np.errstate()`` fixes much more difficult.) + could be restored. Reason for removal: there are no known users and the + functions would have made ``with np.errstate()`` fixes much more difficult). (`gh-23922 `__) * The ``numpy/old_defines.h`` which was part of the API deprecated since NumPy 1.7 has been removed. This removes macros of the form ``PyArray_CONSTANT``. - The script at https://github.com/numpy/numpy/blob/main/tools/replace_old_macros.sed - may be useful to convert them to the ``NPY_CONSTANT`` version. + The `replace_old_macros.sed `__ + script may be useful to convert them to the ``NPY_CONSTANT`` version. (`gh-24011 `__) @@ -511,14 +514,14 @@ NumPy 2.0 C API removals * The advanced indexing ``MapIter`` and related API has been removed. The (truly) public part of it was not well tested and had only one known user (Theano). Making it private will simplify improvements - to speed up ``ufunc.at`` and make advanced indexing more maintainable - and was important for allowing 64 dimensional arrays. - Please let us know if this API is important to you so we can find a + to speed up ``ufunc.at``, make advanced indexing more maintainable, + and was important for increasing the maximum number of dimensions of arrays + to 64. Please let us know if this API is important to you so we can find a solution together. (`gh-25138 `__) -* ``NPY_MAX_ELSIZE`` macro has been removed as it only ever reflected +* The ``NPY_MAX_ELSIZE`` macro has been removed, as it only ever reflected builtin numeric types and served no internal purpose. (`gh-25149 `__) @@ -529,7 +532,7 @@ NumPy 2.0 C API removals * ``PyArrayFlags_Type`` and ``PyArray_NewFlagsObject`` as well as ``PyArrayFlagsObject`` are private now. - There is no known use-case, use the Python API if needed. + There is no known use-case; use the Python API if needed. * ``PyArray_MoveInto``, ``PyArray_CastTo``, ``PyArray_CastAnyTo`` are removed use ``PyArray_CopyInto`` and if absolutely needed ``PyArray_CopyAnyInto`` (the latter does a flat copy). @@ -539,19 +542,19 @@ NumPy 2.0 C API removals * ``PyArray_CompareUCS4`` and ``PyArray_CompareString`` are removed. Use the standard C string comparison functions. * ``PyArray_ISPYTHON`` is removed as it is misleading, has no known - use-cases and easy to replace. -* ``PyArray_FieldNames`` is removed as it is unclear what it would + use-cases, and is easy to replace. +* ``PyArray_FieldNames`` is removed, as it is unclear what it would be useful for. It also has incorrect semantics in some possible use-cases. -* ``PyArray_TypestrConvert`` since it seems a misnomer and unlikely - to be used by anyone. If you know the size or are limited to - few types, just use it explicitly, otherwise go via Python - strings. +* ``PyArray_TypestrConvert`` is removed, since it seems a misnomer and unlikely + to be used by anyone. If you know the size or are limited to few types, just + use it explicitly, otherwise go via Python strings. (`gh-25292 `__) ``PyArray_GetCastFunc`` was removed ----------------------------------- + Note that custom legacy user dtypes can still provide a castfunc as their implementation, but any access to them is now removed. The reason for this is that NumPy never used these internally @@ -567,15 +570,15 @@ use old or new cast functions depending on the NumPy version. New Features ============ -* Extend ``np.add`` to work with ``unicode`` and ``bytes`` dtypes. +* ``np.add`` was extended to work with ``unicode`` and ``bytes`` dtypes. (`gh-24858 `__) -`np.bitwise_count` to compute the number of 1-bits in an integer array ----------------------------------------------------------------------- +A new ``bitwise_count`` function +-------------------------------- This new function counts the number of 1-bits in a number. -`np.bitwise_count` works on all the numpy integer types and +`~numpy.bitwise_count` works on all the numpy integer types and integer-like objects. .. code-block:: python @@ -587,87 +590,88 @@ integer-like objects. (`gh-19355 `__) +macOS Accelerate support, including the ILP64 +--------------------------------------------- + Support for the updated Accelerate BLAS/LAPACK library, including ILP64 (64-bit integer) support, in macOS 13.3 has been added. This brings arm64 support, and significant performance improvements of up to 10x for commonly used linear -algebra operations. When Accelerate is selected at build time, the 13.3+ -version will automatically be used if available. +algebra operations. When Accelerate is selected at build time, or if no +explicit BLAS library selection is done, the 13.3+ version will automatically +be used if available. (`gh-24053 `__) -``weights`` option for `quantile` and `percentile` ----------------------------------------------------- -The ``weights`` option is now available for `quantile`, `percentile`, -`nanquantile` and `nanpercentile`. Only ``method="inverted_cdf"`` supports -weights. +Binary wheels are also available. On macOS >=14.0, users who install NumPy from +PyPI will get wheels built against Accelerate rather than OpenBLAS. + +(`gh-25255 `__) + +Option to use weights for quantile and percentile functions +----------------------------------------------------------- + +A ``weights`` keyword is now available for `~numpy.quantile`, +`~numpy.percentile`, `~numpy.nanquantile` and `~numpy.nanpercentile`. Only +``method="inverted_cdf"`` supports weights. (`gh-24254 `__) Improved CPU optimization tracking ---------------------------------- -Introduces a tracer mechanism that enables tracking of the enabled targets -for each optimized function in the NumPy library. With this enhancement, -it becomes possible to precisely monitor the enabled CPU dispatch -targets for the dispatched functions. +A new tracer mechanism is available which enables tracking of the enabled +targets for each optimized function (i.e., that uses hardware-specific SIMD +instructions) in the NumPy library. With this enhancement, it becomes possible +to precisely monitor the enabled CPU dispatch targets for the dispatched +functions. -A new function named `opt_func_info` has been added to the new namespace `numpy.lib.introspect`, -offering this tracing capability. This function allows you to retrieve information -about the enabled targets based on function names and data type signatures. +A new function named ``opt_func_info`` has been added to the new namespace +`numpy.lib.introspect`, offering this tracing capability. This function allows +you to retrieve information about the enabled targets based on function names +and data type signatures. (`gh-24420 `__) -``meson`` backend for ``f2py`` ------------------------------- -``f2py`` in compile mode (i.e. ``f2py -c``) now accepts the ``--backend meson`` option. This is the default option -for Python ``3.12`` on-wards. Older versions will still default to ``--backend -distutils``. +A new Meson backend for ``f2py`` +-------------------------------- + +``f2py`` in compile mode (i.e. ``f2py -c``) now accepts the ``--backend meson`` +option. This is the default option for Python >=3.12. For older Python versions, +``f2py`` will still default to ``--backend distutils``. To support this in realistic use-cases, in compile mode ``f2py`` takes a ``--dep`` flag one or many times which maps to ``dependency()`` calls in the ``meson`` backend, and does nothing in the ``distutils`` backend. - There are no changes for users of ``f2py`` only as a code generator, i.e. without ``-c``. (`gh-24532 `__) ``bind(c)`` support for ``f2py`` -------------------------------- + Both functions and subroutines can be annotated with ``bind(c)``. ``f2py`` will handle both the correct type mapping, and preserve the unique label for other -``C`` interfaces. +C interfaces. **Note:** ``bind(c, name = 'routine_name_other_than_fortran_routine')`` is not - honored by the ``f2py`` bindings by design, since ``bind(c)`` with the ``name`` - is meant to guarantee only the same name in ``C`` and ``Fortran``, not in - ``Python`` and ``Fortran``. +honored by the ``f2py`` bindings by design, since ``bind(c)`` with the ``name`` +is meant to guarantee only the same name in C and Fortran, not in Python and +Fortran. (`gh-24555 `__) -``strict`` option for `testing.assert_allclose` ------------------------------------------------ -The ``strict`` option is now available for `testing.assert_allclose`. -Setting ``strict=True`` will disable the broadcasting behaviour for scalars -and ensure that input arrays have the same data type. - -(`gh-24680 `__) - -``strict`` option for `testing.assert_equal` --------------------------------------------- -The ``strict`` option is now available for `testing.assert_equal`. -Setting ``strict=True`` will disable the broadcasting behaviour for scalars -and ensure that input arrays have the same data type. - -(`gh-24770 `__) +A new ``strict`` option for several testing functions +----------------------------------------------------- -``strict`` option for `testing.assert_array_less` -------------------------------------------------- -The ``strict`` option is now available for `testing.assert_array_less`. +The ``strict`` keyword is now available for `~numpy.testing.assert_allclose`, +`~numpy.testing.assert_equal`, and `~numpy.testing.assert_array_less`. Setting ``strict=True`` will disable the broadcasting behaviour for scalars and ensure that input arrays have the same data type. -(`gh-24775 `__) +(`gh-24680 `__, +`gh-24770 `__, +`gh-24775 `__) Add ``np.core.umath.find`` and ``np.core.umath.rfind`` UFuncs ------------------------------------------------------------- @@ -681,18 +685,18 @@ and are used in ``np.char``. They operate similar to ``str.find`` and --------------------------------------------- `numpy.linalg.diagonal` and `numpy.linalg.trace` have been -added, which are Array API compatible variants of `numpy.diagonal` -and `numpy.trace`. They differ in the default axis selection -which define 2-D sub-arrays. +added, which are array API standard-compatible variants of `numpy.diagonal` and +`numpy.trace`. They differ in the default axis selection which define 2-D +sub-arrays. (`gh-24887 `__) -`numpy.long` and `numpy.ulong` ------------------------------- +New ``long`` and ``ulong`` dtypes +--------------------------------- `numpy.long` and `numpy.ulong` have been added as NumPy integers mapping -to C's ``long`` and ``unsigned long``. Prior to NumPy 1.24 `numpy.long` -was an alias to Python's ``int``. +to C's ``long`` and ``unsigned long``. Prior to NumPy 1.24, ``numpy.long`` was +an alias to Python's ``int``. (`gh-24922 `__) @@ -700,32 +704,32 @@ was an alias to Python's ``int``. ------------------------------ `numpy.linalg.svdvals` has been added. It computes singular values for -(stack of) matrices. Executing ``np.svdvals(x)`` is the same as calling +(a stack of) matrices. Executing ``np.svdvals(x)`` is the same as calling ``np.svd(x, compute_uv=False, hermitian=False)``. -This function is compatible with Array API. +This function is compatible with the array API standard. (`gh-24940 `__) -`numpy.isdtype` ---------------- +A new ``isdtype`` function +-------------------------- `numpy.isdtype` was added to provide a canonical way to classify NumPy's dtypes -in compliance with Array API and using names standardized there. +in compliance with the array API standard. (`gh-25054 `__) -`numpy.astype` --------------- +A new ``astype`` function +------------------------- -`numpy.astype` was added to provide an Array API compatible alternative to -`numpy.ndarray.astype` method. +`numpy.astype` was added to provide an array API standard-compatible +alternative to the `numpy.ndarray.astype` method. (`gh-25079 `__) Array API compatible functions' aliases --------------------------------------- -13 aliases for existing functions were added to improve compatibility with the Array API standard: +13 aliases for existing functions were added to improve compatibility with the array API standard: * Trigonometry: ``acos``, ``acosh``, ``asin``, ``asinh``, ``atan``, ``atanh``, ``atan2``. @@ -733,49 +737,37 @@ Array API compatible functions' aliases * Misc: ``concat``, ``permute_dims``, ``pow``. -* linalg: ``tensordot``, ``matmul``. +* In ``numpy.linalg``: ``tensordot``, ``matmul``. (`gh-25086 `__) -Array API set functions ------------------------ +New ``unique_*`` functions +-------------------------- -`numpy.unique_all`, `numpy.unique_counts`, `numpy.unique_inverse`, -and `numpy.unique_values` functions have been added for Array API compatibility. -They provide functionality of `numpy.unique` with different sets of flags. +The `~numpy.unique_all`, `~numpy.unique_counts`, `~numpy.unique_inverse`, +and `~numpy.unique_values` functions have been added. They provide +functionality of `~numpy.unique` with different sets of flags. They are array API +standard-compatible, and because the number of arrays they return does not +depend on the values of input arguments, they are easier to target for JIT +compilation. (`gh-25088 `__) Matrix transpose support for ndarrays ------------------------------------- -NumPy now offers support for calculating the matrix transpose of an array. The -matrix transpose is equivalent to swapping the last two axes of an array. Both -``np.ndarray`` and ``np.ma.MaskedArray`` now expose an ``.mT`` attribute. - -(`gh-23762 `__) - -``outer`` for `numpy.linalg` ----------------------------- - -`numpy.linalg.outer` has been added. It computes the outer product of two vectors. -It differs from `numpy.outer` by accepting one-dimensional arrays only. -This function is compatible with Array API. - -(`gh-25101 `__) -``cross`` for `numpy.linalg` ----------------------------- - -`numpy.linalg.cross` has been added. It computes the cross product of two -(arrays of) 3-dimensional vectors. It differs from `numpy.cross` by accepting -three-dimensional vectors only. This function is compatible with Array API. +NumPy now offers support for calculating the matrix transpose of an array (or +stack of arrays). The matrix transpose is equivalent to swapping the last two +axes of an array. Both ``np.ndarray`` and ``np.ma.MaskedArray`` now expose a +``.mT`` attribute, and there is a matching new `numpy.matrix_transpose` +function. -(`gh-25145 `__) +(`gh-23762 `__) Array API compatible functions for ``numpy.linalg`` --------------------------------------------------- -Four new functions and two aliases were added to improve compatibility with +Six new functions and two aliases were added to improve compatibility with the Array API standard for `numpy.linalg`: * `numpy.linalg.matrix_norm` - Computes the matrix norm of a matrix (or a stack of matrices). @@ -786,32 +778,42 @@ the Array API standard for `numpy.linalg`: * `numpy.linalg.vecdot` - An alias for `numpy.vecdot`. -* `numpy.matrix_transpose` - Transposes a matrix (or a stack of matrices). - * `numpy.linalg.matrix_transpose` - An alias for `numpy.matrix_transpose`. -(`gh-25155 `__) + (`gh-25155 `__) -``correction`` argument for `numpy.var` and `numpy.std` -------------------------------------------------------- +* `numpy.linalg.outer` has been added. It computes the outer product of two + vectors. It differs from `numpy.outer` by accepting one-dimensional arrays + only. This function is compatible with the array API standard. + + (`gh-25101 `__) + +* `numpy.linalg.cross` has been added. It computes the cross product of two + (arrays of) 3-dimensional vectors. It differs from `numpy.cross` by accepting + three-dimensional vectors only. This function is compatible with the array + API standard. + + (`gh-25145 `__) + +A ``correction`` argument for ``var`` and ``std`` +------------------------------------------------- -``correction`` argument was added to `numpy.var` and `numpy.std`, -which is an Array API compatible alias for ``ddof``. -As both arguments serve the same purpose only one of them can be -provided at the same time. +A ``correction`` argument was added to `~numpy.var` and `~numpy.std`, which is +an array API standard compatible alternative to ``ddof``. As both arguments +serve a similar purpose, only one of them can be provided at the same time. (`gh-25169 `__) ``ndarray.device`` and ``ndarray.to_device`` -------------------------------------------- -``ndarray.device`` attribute and ``ndarray.to_device`` method were -added to `numpy.ndarray` class for Array API compatibility. +An ``ndarray.device`` attribute and ``ndarray.to_device`` method were +added to ``numpy.ndarray`` for array API standard compatibility. Additionally, ``device`` keyword-only arguments were added to: -`numpy.asarray`, `numpy.arange`, `numpy.empty`, `numpy.empty_like`, -`numpy.eye`, `numpy.full`, `numpy.full_like`, `numpy.linspace`, -`numpy.ones`, `numpy.ones_like`, `numpy.zeros`, and `numpy.zeros_like`. +`~numpy.asarray`, `~numpy.arange`, `~numpy.empty`, `~numpy.empty_like`, +`~numpy.eye`, `~numpy.full`, `~numpy.full_like`, `~numpy.linspace`, +`~numpy.ones`, `~numpy.ones_like`, `~numpy.zeros`, and `~numpy.zeros_like`. For all these new arguments, only ``device="cpu"`` is supported. @@ -821,42 +823,41 @@ StringDType has been added to NumPy ----------------------------------- We have added a new variable-width UTF-8 encoded string data type, implementing -a "NumPy array of python strings", including support for a user-provided missing -data sentinel. It is intended as a drop-in replacement for arrays of python +a "NumPy array of Python strings", including support for a user-provided missing +data sentinel. It is intended as a drop-in replacement for arrays of Python strings and missing data sentinels using the object dtype. See `NEP 55 `_ and :ref:`the documentation ` for more details. (`gh-25347 `__) -`numpy.linalg.cholesky` and `numpy.linalg.pinv` new parameters --------------------------------------------------------------- +New keywords for ``cholesky`` and ``pinv`` +------------------------------------------ -The ``upper`` and ``rtol`` keyword parameters were added to -`numpy.linalg.cholesky` and `numpy.lingalg.pinv`, respectively, to -improve array API compatibility. +The ``upper`` and ``rtol`` keywords were added to `numpy.linalg.cholesky` and +`numpy.linalg.pinv`, respectively, to improve array API standard compatibility. -For `numpy.linalg.pinv` if neither ``rcond`` nor ``rtol`` is specified, -the ``rcond``'s default is used. It's planned to deprecate and remove -``rcond`` in the future. +For `~numpy.linalg.pinv`, if neither ``rcond`` nor ``rtol`` is specified, +the ``rcond``'s default is used. We plan to deprecate and remove ``rcond`` in +the future. (`gh-25388 `__) -`numpy.linalg.martrix_rank`, `numpy.sort` and `numpy.argsort` new parameters ----------------------------------------------------------------------------- +New keywords for ``sort``, ``argsort`` and ``linalg.matrix_rank`` +----------------------------------------------------------------- -New keyword parameters were added to improve array API compatibility: +New keyword parameters were added to improve array API standard compatibility: -* ``rtol`` keyword parameter was added to `numpy.linalg.martrix_rank`. +* ``rtol`` was added to `~numpy.linalg.matrix_rank`. -* ``stable`` keyword parameter was added to `numpy.sort` and `numpy.argsort`. +* ``stable`` was added to `~numpy.sort` and `~numpy.argsort`. (`gh-25437 `__) -``np.strings`` namespace for string ufuncs ------------------------------------------- +New ``numpy.strings`` namespace for string ufuncs +------------------------------------------------- -Numpy now implements some string operations as ufuncs. The old ``np.char`` +NumPy now implements some string operations as ufuncs. The old ``np.char`` namespace is still available, and where possible the string manipulation functions in that namespace have been updated to use the new ufuncs, substantially improving their performance. @@ -908,18 +909,20 @@ Improvements (`gh-25651 `__) -Integer sequences as the ``shape`` argument for `np.memmap` ------------------------------------------------------------ -`np.memmap` can now be created with any integer sequence as the ``shape`` +Integer sequences as the shape argument for ``memmap`` +------------------------------------------------------ + +`numpy.memmap` can now be created with any integer sequence as the ``shape`` argument, such as a list or numpy array of integers. Previously, only the types of tuple and int could be used without raising an error. (`gh-23729 `__) -``np.errstate()`` is now faster and context safe ------------------------------------------------- -The `np.errstate` context manager/decorator is now faster and -safer. Previously, it was not context safe and had (rarely) +``errstate`` is now faster and context safe +------------------------------------------- + +The `numpy.errstate` context manager/decorator is now faster and +safer. Previously, it was not context safe and had (rare) issues with thread-safety. (`gh-23936 `__) @@ -933,14 +936,14 @@ results. Extensions to other platforms will be done in the future. (`gh-24018 `__) -Complex types - Underlying type changes ---------------------------------------- +Complex types - underlying C type changes +----------------------------------------- -* The underlying C types for all of numpy's complex types have been changed to +* The underlying C types for all of NumPy's complex types have been changed to use C99 complex types. * While this change does not affect the memory layout of complex types, it - changes the API to be used, in order to directly retrieve or write the real or + changes the API to be used to directly retrieve or write the real or complex part of the complex number, since direct field access (as in ``c.real`` or ``c.imag``) is no longer an option. You can now use utilities provided in ``numpy/npy_math.h`` to do these operations, like this: @@ -961,33 +964,41 @@ Complex types - Underlying type changes (`gh-24085 `__) -``iso_c_binding`` support for ``f2py`` --------------------------------------- +``iso_c_binding`` support and improved common blocks for ``f2py`` +----------------------------------------------------------------- + Previously, users would have to define their own custom ``f2cmap`` file to use type mappings defined by the Fortran2003 ``iso_c_binding`` intrinsic module. These type maps are now natively supported by ``f2py`` (`gh-24555 `__) -Call ``str`` automatically on third argument to functions like `assert_equal` ------------------------------------------------------------------------------ +``f2py`` now handles ``common`` blocks which have ``kind`` specifications from +modules. This further expands the usability of intrinsics like +``iso_fortran_env`` and ``iso_c_binding``. + +(`gh-25186 `__) + +Call ``str`` automatically on third argument to functions like ``assert_equal`` +------------------------------------------------------------------------------- -The third argument to functions like `assert_equal` now has ``str`` called on -it automatically. This way it mimics the built-in ``assert`` statement, where -``assert_equal(a, b, obj)`` works like ``assert a == b, obj``. +The third argument to functions like `~numpy.testing.assert_equal` now has +``str`` called on it automatically. This way it mimics the built-in ``assert`` +statement, where ``assert_equal(a, b, obj)`` works like ``assert a == b, obj``. (`gh-24877 `__) -Support for array ``atol`` and ``rtol`` in ``np.isclose`` and ``np.allclose`` ------------------------------------------------------------------------------ -The keywords ``atol`` and ``rtol`` in ``np.isclose`` and ``np.allclose`` +Support for array-like ``atol``/``rtol`` in ``isclose``, ``allclose`` +--------------------------------------------------------------------- + +The keywords ``atol`` and ``rtol`` in `~numpy.isclose` and `~numpy.allclose` now accept both scalars and arrays. An array, if given, must broadcast -to the shapes of the arguments `a` and `b`. +to the shapes of the first two array arguments. (`gh-24878 `__) -Consistent failure messages in `numpy.testing` ----------------------------------------------- +Consistent failure messages in test functions +--------------------------------------------- Previously, some `numpy.testing` assertions printed messages that referred to the actual and desired results as ``x`` and ``y``. @@ -996,17 +1007,13 @@ Now, these values are consistently referred to as ``ACTUAL`` and (`gh-24931 `__) -``f2py`` now handles ``common`` blocks which have ``kind`` specifications from modules. This further expands the usability of intrinsics like ``iso_fortran_env`` and ``iso_c_binding``. - -(`gh-25186 `__) - -`numpy.fft` n-D transforms allow ``s[i] == -1`` ------------------------------------------------ +n-D FFT transforms allow ``s[i] == -1`` +--------------------------------------- -`numpy.fft.fftn`, `numpy.fft.ifftn`, `numpy.fft.rfftn`, `numpy.fft.irfftn`, -`numpy.fft.fft2`, `numpy.fft.ifft2`, `numpy.fft.rfft2` and `numpy.fft.irfft2` -now use the whole input array along the axis ``i`` if ``s[i] == -1``, -in line with the array API specification. +The `~numpy.fft.fftn`, `~numpy.fft.ifftn`, `~numpy.fft.rfftn`, +`~numpy.fft.irfftn`, `~numpy.fft.fft2`, `~numpy.fft.ifft2`, `~numpy.fft.rfft2` +and `~numpy.fft.irfft2` functions now use the whole input array along the axis +``i`` if ``s[i] == -1``, in line with the array API standard. (`gh-25495 `__) @@ -1030,23 +1037,25 @@ Changes * Being fully context and thread-safe, ``np.errstate`` can only be entered once now. -* ``np.setbufsize`` is now tied to ``np.errstate()``: Leaving an +* ``np.setbufsize`` is now tied to ``np.errstate()``: leaving an ``np.errstate`` context will also reset the ``bufsize``. (`gh-23936 `__) -* ``np.lib.array_utils`` public module has been introduced and in its initial version - it hosts three functions: ``byte_bounds`` (moved from ``np.lib.utils``), - ``normalize_axis_tuple`` and ``normalize_axis_index`` +* A new public ``np.lib.array_utils`` submodule has been introduced and it + currently contains three functions: ``byte_bounds`` (moved from + ``np.lib.utils``), ``normalize_axis_tuple`` and ``normalize_axis_index``. (`gh-24540 `__) -* Redefine `numpy.bool` as an alias for `numpy.bool_` (as opposed to the `bool` - it was until NumPy 1.24) for Array API compatibility. +* Introduce `numpy.bool` as the new canonical name for NumPy's boolean dtype, + and make `numpy.bool_` an alias to it. Note that until NumPy 1.24, + ``np.bool`` was an alias to Python's builtin ``bool``. The new name helps + with array API standard compatibility and is a more intuitive name. (`gh-25080 `__) -* The ``dtype.flags`` value was previously usually stored as a signed integer. +* The ``dtype.flags`` value was previously stored as a signed integer. This means that the aligned dtype struct flag lead to negative flags being set (-128 rather than 128). This flag is now stored unsigned (positive). Code which checks flags manually may need to adapt. This may include code @@ -1056,17 +1065,19 @@ Changes Representation of NumPy scalars changed --------------------------------------- + As per :ref:`NEP 51 `, the scalar representation has been updated to include the type information to avoid confusion with Python scalars. -The are now printed as ``np.float64(3.0)`` rather than just ``3.0``. + +Scalars are now printed as ``np.float64(3.0)`` rather than just ``3.0``. This may disrupt workflows that store representations of numbers -(e.g. to files) making it harder to read them. They should be stored as +(e.g., to files) making it harder to read them. They should be stored as explicit strings, for example by using ``str()`` or ``f"{scalar!s}"``. For the time being, affected users can use ``np.set_printoptions(legacy="1.25")`` to get the old behavior (with possibly a few exceptions). Documentation of downstream projects may require larger updates, -if code snippets are tested. We are working on tooling for: +if code snippets are tested. We are working on tooling for `doctest-plus `__ to facilitate updates. @@ -1074,6 +1085,7 @@ to facilitate updates. Truthiness of NumPy strings changed ----------------------------------- + NumPy strings previously were inconsistent about how they defined if the string is ``True`` or ``False`` and the definition did not match the one used by Python. @@ -1101,31 +1113,34 @@ The change does affect ``np.fromregex`` as it uses direct assignments. (`gh-23871 `__) -Add mean keyword to var and std function ----------------------------------------- +A ``mean`` keyword was added to var and std function +---------------------------------------------------- + Often when the standard deviation is needed the mean is also needed. The same holds for the variance and the mean. Until now the mean is then calculated twice, -the change introduced here for the var and std functions allows for passing in a -precalculated mean as an keyword argument. See the doc-strings for details and an -example illustrating the speed-up. +the change introduced here for the `~numpy.var` and `~numpy.std` functions +allows for passing in a precalculated mean as an keyword argument. See the +docstrings for details and an example illustrating the speed-up. (`gh-24126 `__) Remove datetime64 deprecation warning when constructing with timezone --------------------------------------------------------------------- -The ``np.datetime64`` method now issues a User Warning rather than a -Deprecation Warning whenever a timezone is included in the datetime + +The `numpy.datetime64` method now issues a UserWarning rather than a +DeprecationWarning whenever a timezone is included in the datetime string that is provided. (`gh-24193 `__) -Default integer now 64bit on 64bit windows ------------------------------------------- -The default NumPy integer is now 64bit on all 64bit systems as the -historic 32bit default on windows was a common source of issues. -Most users should not notice this, the main issues may occur -with code interfacing with libraries written in a compiled language -like C. For more information see :ref:`migration_windows_int64`. +Default integer dtype is now 64-bit on 64-bit Windows +----------------------------------------------------- + +The default NumPy integer is now 64-bit on all 64-bit systems as the historic +32-bit default on Windows was a common source of issues. Most users should not +notice this. The main issues may occur with code interfacing with libraries +written in a compiled language like C. For more information see +:ref:`migration_windows_int64`. (`gh-24224 `__) @@ -1145,12 +1160,13 @@ if you think a mistake was made and something needs to be made public. The "relaxed strides" debug build option, which was previously enabled through the ``NPY_RELAXED_STRIDES_DEBUG`` environment variable or the -``-Drelaxed-strides-debug`` config-settings flag, has been removed. +``-Drelaxed-strides-debug`` config-settings flag has been removed. (`gh-24717 `__) Redefinition of ``np.intp``/``np.uintp`` (almost never a change) ---------------------------------------------------------------- + Due to the actual use of these types almost always matching the use of ``size_t``/``Py_ssize_t`` this is now the definition in C. Previously, it matched ``intptr_t`` and ``uintptr_t`` which would often @@ -1198,8 +1214,9 @@ Any out of bound axis value will now error, make sure to use (`gh-25149 `__) -New ``copy`` keyword meaning for `numpy.array` and `numpy.asarray` ------------------------------------------------------------------- +New ``copy`` keyword meaning for ``array`` and ``asarray`` constructors +----------------------------------------------------------------------- + Now `numpy.array` and `numpy.asarray` support three values for ``copy`` parameter: * ``None`` - A copy will only be made if it is necessary. @@ -1226,6 +1243,7 @@ argument with the same meaning as when passed to `numpy.array` or Cleanup of initialization of ``numpy.dtype`` with strings with commas --------------------------------------------------------------------- + The interpretation of strings with commas is changed slightly, in that a trailing comma will now always create a structured dtype. E.g., where previously ``np.dtype("i")`` and ``np.dtype("i,")`` were treated as identical, @@ -1244,7 +1262,8 @@ case for initializations without a comma, like ``np.dtype("(2)i")``. Change in how complex sign is calculated ---------------------------------------- -Following the API Array standard, the complex sign is now calculated as + +Following the array API standard, the complex sign is now calculated as ``z / |z|`` (instead of the rather less logical case where the sign of the real part was taken, unless the real part was zero, in which case the sign of the imaginary part was returned). Like for real numbers, @@ -1252,26 +1271,31 @@ zero is returned if ``z==0``. (`gh-25441 `__) +Return types of functions that returned a list of arrays +-------------------------------------------------------- + Functions that returned a list of ndarrays have been changed to return a tuple of ndarrays instead. Returning tuples consistently whenever a sequence of arrays is returned makes it easier for JIT compilers like Numba, as well as for static type checkers in some cases, to support these functions. Changed -functions are: ``atleast_1d``, ``atleast_2d``, ``atleast_3d``, ``broadcast_arrays``, -``meshgrid``, ``ogrid``, ``histogramdd``. +functions are: `~numpy.atleast_1d`, `~numpy.atleast_2d`, `~numpy.atleast_3d`, +`~numpy.broadcast_arrays`, `~numpy.meshgrid`, `~numpy.ogrid`, +`~numpy.histogramdd`. ``np.unique`` ``return_inverse`` shape for multi-dimensional inputs ------------------------------------------------------------------- + When multi-dimensional inputs are passed to ``np.unique`` with ``return_inverse=True``, the ``unique_inverse`` output is now shaped such that the input can be reconstructed -directly using ``np.take(unique, unique_inverse)`` when ``axis = None``, and +directly using ``np.take(unique, unique_inverse)`` when ``axis=None``, and ``np.take_along_axis(unique, unique_inverse, axis=axis)`` otherwise. -(`gh-25553 `__) - -(`gh-25570 `__) +(`gh-25553 `__, +`gh-25570 `__) ``any`` and ``all`` return booleans for object arrays ----------------------------------------------------- + The ``any`` and ``all`` functions and methods now return booleans also for object arrays. Previously, they did a reduction which behaved like the Python ``or`` and