DOC: Update __array__ copy keyword docs

Author: mtsokol

doc/source/numpy_2_0_migration_guide.rst

@@ -412,20 +412,23 @@ 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. If ``copy`` keyword is considered in
-   the ``__array__`` method implementation, then for ``copy=True`` always
-   return a new copy.
-
+* 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.
+* 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.
+* For any ``__array__`` method on a non-NumPy array-like object, ``dtype=None``
+  and ``copy=None`` keywords must be added to the signature - this will work with older
+  NumPy versions as well (although older numpy versions will never pass in ``copy`` keyword).
+  If the keywords are actually used in the ``__array__`` method implementation, then for:
+
+  * ``copy=True`` and any ``dtype`` value always return a new copy,
+  * ``copy=None`` create a copy if required (for example by ``dtype``),
+  * ``copy=False`` a copy must never be made. If a copy is needed to return a numpy array
+    or satisfy ``dtype``, then raise an exception (``ValueError``).
 
 Writing numpy-version-dependent code
 ------------------------------------

doc/source/user/basics.dispatch.rst

@@ -23,6 +23,10 @@ example that has rather narrow utility but illustrates the concepts involved.
 ...     def __repr__(self):
 ...         return f"{self.__class__.__name__}(N={self._N}, value={self._i})"
 ...     def __array__(self, dtype=None, copy=None):
+...         if copy is False:
+...             raise ValueError(
+...                 "`copy=False` isn't supported. A copy is always created."
+...             )
 ...         return self._i * np.eye(self._N, dtype=dtype)
 
 Our custom array can be instantiated like:
@@ -85,6 +89,10 @@ For this example we will only handle the method ``__call__``
 ...     def __repr__(self):
 ...         return f"{self.__class__.__name__}(N={self._N}, value={self._i})"
 ...     def __array__(self, dtype=None, copy=None):
+...         if copy is False:
+...             raise ValueError(
+...                 "`copy=False` isn't supported. A copy is always created."
+...             )
 ...         return self._i * np.eye(self._N, dtype=dtype)
 ...     def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
 ...         if method == '__call__':
@@ -136,6 +144,10 @@ conveniently by inheriting from the mixin
 ...     def __repr__(self):
 ...         return f"{self.__class__.__name__}(N={self._N}, value={self._i})"
 ...     def __array__(self, dtype=None, copy=None):
+...         if copy is False:
+...             raise ValueError(
+...                 "`copy=False` isn't supported. A copy is always created."
+...             )
 ...         return self._i * np.eye(self._N, dtype=dtype)
 ...     def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
 ...         if method == '__call__':
@@ -174,6 +186,10 @@ functions to our custom variants.
 ...     def __repr__(self):
 ...         return f"{self.__class__.__name__}(N={self._N}, value={self._i})"
 ...     def __array__(self, dtype=None, copy=None):
+...         if copy is False:
+...             raise ValueError(
+...                 "`copy=False` isn't supported. A copy is always created."
+...             )
 ...         return self._i * np.eye(self._N, dtype=dtype)
 ...     def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
 ...         if method == '__call__':

numpy/_core/_add_newdocs.py

@@ -2943,10 +2943,11 @@
 
 add_newdoc('numpy._core.multiarray', 'ndarray', ('__array__',
     """
-    a.__array__([dtype], /, *, copy=None)
+    a.__array__([dtype], *, copy=None)
 
-    For ``dtype`` parameter it returns either a new reference to self if
-    ``dtype`` is not given or a new array of provided data type if ``dtype``
+    For ``dtype`` parameter it returns a new reference to self if
+    ``dtype`` is not given or it matches array's data type.
+    A new array of provided data type is returned if ``dtype``
     is different from the current data type of the array.
     For ``copy`` parameter it returns a new reference to self if
     ``copy=False`` or ``copy=None`` and copying isn't enforced by ``dtype``

numpy/_core/src/multiarray/ctors.c

@@ -2459,8 +2459,9 @@ check_or_clear_and_warn_error_if_due_to_copy_kwarg(PyObject *kwnames)
         Py_DECREF(type);
         Py_DECREF(value);
         Py_XDECREF(traceback);
-        if (DEPRECATE("__array__ should implement the 'dtype' and "
-                      "'copy' keyword argument") < 0) {
+        if (DEPRECATE("__array__ implementation doesn't accept a copy keyword, "
+                      "so passing copy=False failed. __array__ must implement "
+                      "'dtype' and 'copy' keyword arguments.") < 0) {
             return -1;
         }
         return 0;