Merge pull request numpy#25937 from rgommers/2.0-highlights

DOC: 2.0 release highlights and compat notes changes

Author: mattip

doc/release/upcoming_changes/21760.compatibility.rst

@@ -175,6 +175,8 @@ alongside other, newer packages
     `here for SciPy <https://github.com/MacPython/scipy-wheels>`__.
 
 
+.. _numpy-2-abi-handling:
+
 NumPy 2.0-specific advice
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/dev/depending_on_numpy.rst

@@ -5,7 +5,33 @@ NumPy 2.0 migration guide
 *************************
 
 This document contains a set of instructions on how to update your code to
-work with Numpy 2.0.
+work with NumPy 2.0. It covers changes in NumPy's Python and C APIs.
+
+.. note::
+
+   Note that NumPy 2.0 also breaks binary compatibility - if you are
+   distributing binaries for a Python package that depends on NumPy's C API,
+   please see :ref:`numpy-2-abi-handling`.
+
+
+
+Ruff plugin
+===========
+
+Many of the changes covered in the 2.0 release notes and in this migration
+guide can be automatically adapted to in downstream code with a dedicated
+`Ruff <https://docs.astral.sh/ruff/>`__ rule, namely rule
+`NPY201 <https://docs.astral.sh/ruff/rules/numpy2-deprecation/>`__.
+
+You should install ``ruff>=0.2.0`` and add the ``NPY201`` rule to your
+``pyproject.toml``::
+
+    [tool.ruff.lint]
+    select = ["NPY201"]
+
+You can also apply the NumPy 2.0 rule directly from the command line::
+
+    $ ruff check path/to/code/ --select NPY201
 
 
 .. _migration_promotion_changes:
@@ -189,8 +215,8 @@ The underlying type remains a struct under C++ (all of the above still remains
 valid).
 
 
-Namespace changes
-=================
+Changes to namespaces
+=====================
 
 In NumPy 2.0 certain functions, modules, and constants were moved or removed
 to make the NumPy namespace more user-friendly by removing unnecessary or
@@ -299,8 +325,8 @@ downstream libraries we don't provide any information on how to replace them:
 ``MAY_SHARE_BOUNDS``]
 
 
-Lib namespace
--------------
+numpy.lib namespace
+-------------------
 
 Most of the functions available within ``np.lib`` are also present in the main
 namespace, which is their primary location. To make it unambiguous how to access each
@@ -322,10 +348,10 @@ the main namespace, then you're using a private member. You should either use th
 API or, in case it's infeasible, reach out to us with a request to restore the removed entry.
 
 
-Core namespace
---------------
+numpy.core namespace
+--------------------
 
-``np.core`` namespace is now officially private and has been renamed to ``np._core``.
+The ``np.core`` namespace is now officially private and has been renamed to ``np._core``.
 The user should never fetch members from the ``_core`` directly - instead the main 
 namespace should be used to access the attribute in question. The layout of the ``_core``
 module might change in the future without notice, contrary to public modules which adhere 
@@ -334,8 +360,8 @@ then you should either use the existing API or, in case it's infeasible, reach o
 with a request to restore the removed entry.
 
 
-ndarray and scalar namespace
-----------------------------
+ndarray and scalar methods
+--------------------------
 
 A few methods from ``np.ndarray`` and ``np.generic`` scalar classes have been removed.
 The table below provides replacements for the removed members:
@@ -350,32 +376,18 @@ setitem                 Use ``arr[index] = value`` instead.
 ======================  ========================================================
 
 
-Strings namespace
------------------
+numpy.strings namespace
+-----------------------
 
-A new ``np.strings`` namespace has been created, where most of the string
-operations are implemented as ufuncs. The old ``np.char`` namespace still is
+A new `numpy.strings` namespace has been created, where most of the string
+operations are implemented as ufuncs. The old `numpy.char` namespace still is
 available, and, wherever possible, uses the new ufuncs for greater performance.
-We recommend using the ``np.strings`` methods going forward. The ``np.char``
-namespace may be deprecated in the future.
-
-
-Ruff plugin
------------
+We recommend using the `~numpy.strings` functions going forward. The
+`~numpy.char` namespace may be deprecated in the future.
 
-All the changes that we covered in the previous sections can be automatically applied
-to the codebase with the dedicated Ruff rule,
-`NPY201 <https://docs.astral.sh/ruff/rules/numpy2-deprecation/>`_.
 
-You should install Ruff, version ``0.2.0`` or above, and add the ``NPY201`` rule to
-your ``pyproject.toml``::
-
-    [tool.ruff.lint]
-    select = ["NPY201"]
-
-You can run NumPy 2.0 rule also directly from the command line::
-
-    $ ruff check path/to/code/ --select NPY201
+Other changes
+=============
 
 
 Note about pickled files
@@ -384,3 +396,23 @@ Note about pickled files
 NumPy 2.0 is designed to load pickle files created with NumPy 1.26,
 and vice versa. For versions 1.25 and earlier loading NumPy 2.0
 pickle file will throw an exception.
+
+
+Adapting to changes in the ``copy`` keyword
+-------------------------------------------
+
+The :ref:`copy keyword behavior changes <copy-keyword-changes-2.0>` in
+`~numpy.asarray`, `~numpy.array` and `ndarray.__array__
+<numpy.ndarray.__array__>` may require these changes:
+
+1. Code using ``np.array(..., copy=False)`` can in most cases be changed to
+   ``np.asarray(...)``. Older code tended to use ``np.array`` like this because
+   it had less overhead than the default ``np.asarray`` copy-if-needed
+   behavior. This is no longer true, and ``np.asarray`` is the preferred function.
+2. For code that explicitly needs to pass ``None``/``False`` meaning "copy if
+   needed" in a way that's compatible with NumPy 1.x and 2.x, see
+   `scipy#20172 <https://github.com/scipy/scipy/pull/20172>`__ for an example
+   of how to do so.
+3. For any ``__array__`` method on a non-NumPy array-like object, a
+   ``copy=None`` keyword can be added to the signature - this will work with
+   older NumPy versions as well.

doc/source/numpy_2_0_migration_guide.rst

@@ -1,3 +1,5 @@
+.. _module-structure:
+
 ************************
 NumPy's module structure
 ************************

doc/source/reference/module_structure.rst

@@ -57,6 +57,7 @@ Matrix and vector products
    linalg.multi_dot
    vdot
    vecdot
+   linalg.vecdot
    inner
    outer
    matmul