API: Move back to original semantics for np.astype

mtsokol · mtsokol · commit 9a4b7a2cd12c · 2023-12-15T13:44:15.000+01:00
diff --git a/benchmarks/benchmarks/bench_array_coercion.py b/benchmarks/benchmarks/bench_array_coercion.py
@@ -23,13 +23,13 @@ def time_array_dtype_not_kwargs(self, array_like):
         np.array(array_like, self.int64)
 
     def time_array_no_copy(self, array_like):
-        np.array(array_like, copy=False)
+        np.array(array_like, copy=None)
 
     def time_array_subok(self, array_like):
         np.array(array_like, subok=True)
 
     def time_array_all_kwargs(self, array_like):
-        np.array(array_like, dtype=self.int64, copy=False, order="F",
+        np.array(array_like, dtype=self.int64, copy=None, order="F",
                  subok=False, ndmin=2)
 
     def time_asarray(self, array_like):
diff --git a/doc/release/upcoming_changes/25168.change.rst b/doc/release/upcoming_changes/25168.change.rst
@@ -0,0 +1,8 @@
+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.
diff --git a/numpy/_core/_add_newdocs.py b/numpy/_core/_add_newdocs.py
@@ -807,7 +807,7 @@
         a default ``dtype`` that can represent the values (by applying promotion
         rules when necessary.)
     copy : bool, optional
-        If ``True`` (default), then the object is copied. If ``False``, a copy
+        If ``True`` (default), then the object is copied. If ``None``, a copy
         will only be made if ``__array__`` returns a copy, if obj is a nested
         sequence, or if a copy is needed to satisfy any of the other
         requirements (``dtype``, ``order``, etc.). For ``False`` it raises
diff --git a/numpy/_core/function_base.py b/numpy/_core/function_base.py
@@ -181,9 +181,9 @@ def linspace(start, stop, num=50, endpoint=True, retstep=False, dtype=None,
         _nx.floor(y, out=y)
 
     if retstep:
-        return y.astype(dtype, copy=None), step
+        return y.astype(dtype, copy=False), step
     else:
-        return y.astype(dtype, copy=None)
+        return y.astype(dtype, copy=False)
 
 
 def _logspace_dispatcher(start, stop, num=None, endpoint=None, base=None,
@@ -300,7 +300,7 @@ def logspace(start, stop, num=50, endpoint=True, base=10.0, dtype=None,
     base = np.expand_dims(base, axis=axis)
     if dtype is None:
         return _nx.power(base, y)
-    return _nx.power(base, y).astype(dtype, copy=None)
+    return _nx.power(base, y).astype(dtype, copy=False)
 
 
 def _geomspace_dispatcher(start, stop, num=None, endpoint=None, dtype=None,
@@ -463,7 +463,7 @@ def geomspace(start, stop, num=50, endpoint=True, dtype=None, axis=0):
     if axis != 0:
         result = _nx.moveaxis(result, 0, axis)
 
-    return result.astype(dtype, copy=None)
+    return result.astype(dtype, copy=False)
 
 
 def _needs_add_docstring(obj):
diff --git a/numpy/_core/numeric.py b/numpy/_core/numeric.py
@@ -478,7 +478,7 @@ def count_nonzero(a, axis=None, *, keepdims=False):
     if np.issubdtype(a.dtype, np.character):
         a_bool = a != a.dtype.type()
     else:
-        a_bool = a.astype(np.bool, copy=None)
+        a_bool = a.astype(np.bool, copy=False)
 
     return a_bool.sum(axis=axis, dtype=np.intp, keepdims=keepdims)
 
diff --git a/numpy/_core/src/multiarray/conversion_utils.c b/numpy/_core/src/multiarray/conversion_utils.c
@@ -260,6 +260,31 @@ PyArray_CopyConverter(PyObject *obj, NPY_COPYMODE *copymode) {
     return NPY_SUCCEED;
 }
 
+NPY_NO_EXPORT int
+PyArray_AsTypeCopyConverter(PyObject *obj, NPY_ASTYPECOPYMODE *copymode)
+{
+    int int_copymode;
+    static PyObject* numpy_CopyMode = NULL;
+    npy_cache_import("numpy", "_CopyMode", &numpy_CopyMode);
+
+    if (numpy_CopyMode != NULL && (PyObject *)Py_TYPE(obj) == numpy_CopyMode) {
+        PyErr_SetString(PyExc_ValueError,
+                        "_CopyMode enum is not allowed for astype function. "
+                        "Use true/false instead.");
+        return NPY_FAIL;
+    }
+    else {
+        npy_bool bool_copymode;
+        if (!PyArray_BoolConverter(obj, &bool_copymode)) {
+            return NPY_FAIL;
+        }
+        int_copymode = (int)bool_copymode;
+    }
+
+    *copymode = (NPY_ASTYPECOPYMODE)int_copymode;
+    return NPY_SUCCEED;
+}
+
 /*NUMPY_API
  * Get buffer chunk from object
  *
diff --git a/numpy/_core/src/multiarray/conversion_utils.h b/numpy/_core/src/multiarray/conversion_utils.h
@@ -18,9 +18,17 @@ typedef enum {
     NPY_COPY_IF_NEEDED = 2,
 } NPY_COPYMODE;
 
+typedef enum {
+    NPY_AS_TYPE_COPY_IF_NEEDED = 0,
+    NPY_AS_TYPE_COPY_ALWAYS = 1,
+} NPY_ASTYPECOPYMODE;
+
 NPY_NO_EXPORT int
 PyArray_CopyConverter(PyObject *obj, NPY_COPYMODE *copyflag);
 
+NPY_NO_EXPORT int
+PyArray_AsTypeCopyConverter(PyObject *obj, NPY_ASTYPECOPYMODE *copyflag);
+
 NPY_NO_EXPORT int
 PyArray_BufferConverter(PyObject *obj, PyArray_Chunk *buf);
 
diff --git a/numpy/_core/src/multiarray/methods.c b/numpy/_core/src/multiarray/methods.c
@@ -782,7 +782,7 @@ array_astype(PyArrayObject *self,
     npy_dtype_info dt_info = {NULL, NULL};
     NPY_CASTING casting = NPY_UNSAFE_CASTING;
     NPY_ORDER order = NPY_KEEPORDER;
-    NPY_COPYMODE forcecopy = 1;
+    NPY_ASTYPECOPYMODE forcecopy = 1;
     int subok = 1;
 
     NPY_PREPARE_ARGPARSER;
@@ -791,7 +791,7 @@ array_astype(PyArrayObject *self,
             "|order", &PyArray_OrderConverter, &order,
             "|casting", &PyArray_CastingConverter, &casting,
             "|subok", &PyArray_PythonPyIntFromInt, &subok,
-            "|copy", &PyArray_CopyConverter, &forcecopy,
+            "|copy", &PyArray_AsTypeCopyConverter, &forcecopy,
             NULL, NULL, NULL) < 0) {
         Py_XDECREF(dt_info.descr);
         Py_XDECREF(dt_info.dtype);
@@ -813,7 +813,7 @@ array_astype(PyArrayObject *self,
      * and it's not a subtype if subok is False, then we
      * can skip the copy.
      */
-    if (forcecopy != NPY_COPY_ALWAYS &&
+    if (forcecopy != NPY_AS_TYPE_COPY_ALWAYS &&
                     (order == NPY_KEEPORDER ||
                     (order == NPY_ANYORDER &&
                         (PyArray_IS_C_CONTIGUOUS(self) ||
@@ -829,14 +829,6 @@ array_astype(PyArrayObject *self,
         return (PyObject *)self;
     }
 
-    if (forcecopy == NPY_COPY_NEVER) {
-        PyErr_SetString(PyExc_ValueError,
-                "Unable to avoid copy while casting in never copy mode. "
-                "Use copy=None to copy only if necessary.");
-        Py_DECREF(dtype);
-        return NULL;
-    }
-
     if (!PyArray_CanCastArrayTo(self, dtype, casting)) {
         PyErr_Clear();
         npy_set_invalid_cast_error(
diff --git a/numpy/_core/tests/test_api.py b/numpy/_core/tests/test_api.py
@@ -183,12 +183,12 @@ def test_array_astype():
 
     # order parameter allows overriding of the memory layout,
     # forcing a copy if the layout is wrong
-    b = a.astype('f4', order='F', copy=None)
+    b = a.astype('f4', order='F', copy=False)
     assert_equal(a, b)
     assert_(not (a is b))
     assert_(b.flags.f_contiguous)
 
-    b = a.astype('f4', order='C', copy=None)
+    b = a.astype('f4', order='C', copy=False)
     assert_equal(a, b)
     assert_(a is b)
     assert_(b.flags.c_contiguous)
@@ -214,12 +214,12 @@ class MyNDArray(np.ndarray):
     assert_(a is b)
 
     # subok=True is default, and creates a subtype on a cast
-    b = a.astype('i4', copy=None)
+    b = a.astype('i4', copy=False)
     assert_equal(a, b)
     assert_equal(type(b), MyNDArray)
 
     # subok=False never returns a subclass
-    b = a.astype('f4', subok=False, copy=None)
+    b = a.astype('f4', subok=False, copy=False)
     assert_equal(a, b)
     assert_(not (a is b))
     assert_(type(b) is not MyNDArray)
@@ -570,22 +570,14 @@ def test_astype_copyflag():
     arr = np.arange(10, dtype=np.intp)
 
     res_true = arr.astype(np.intp, copy=True)
-    assert not np.may_share_memory(arr, res_true)
-    res_always = arr.astype(np.intp, copy=np._CopyMode.ALWAYS)
-    assert not np.may_share_memory(arr, res_always)
+    assert not np.shares_memory(arr, res_true)
 
     res_false = arr.astype(np.intp, copy=False)
-    # `res_false is arr` currently, but check `may_share_memory`.
-    assert np.may_share_memory(arr, res_false)
-    res_if_needed = arr.astype(np.intp, copy=None)
-    # `res_if_needed is arr` currently, but check `may_share_memory`.
-    assert np.may_share_memory(arr, res_if_needed)
-
-    res_never = arr.astype(np.intp, copy=np._CopyMode.NEVER)
-    assert np.may_share_memory(arr, res_never)
-
-    # Simple tests for when a copy is necessary:
-    res_if_needed = arr.astype(np.float64, copy=None)
-    assert_array_equal(res_if_needed, arr)
+    assert np.shares_memory(arr, res_false)
+
+    res_false_float = arr.astype(np.float64, copy=False)
+    assert not np.shares_memory(arr, res_false_float)
+
+    # _CopyMode enum isn't allowed
     assert_raises(ValueError, arr.astype, np.float64,
-                  copy=False)
+                  copy=np._CopyMode.NEVER)
diff --git a/numpy/fft/tests/test_pocketfft.py b/numpy/fft/tests/test_pocketfft.py
@@ -241,7 +241,7 @@ def test_fft_with_order(dtype, order, fft):
     # Check that FFT/IFFT produces identical results for C, Fortran and
     # non contiguous arrays
     rng = np.random.RandomState(42)
-    X = rng.rand(8, 7, 13).astype(dtype, copy=None)
+    X = rng.rand(8, 7, 13).astype(dtype, copy=False)
     # See discussion in pull/14178
     _tol = 8.0 * np.sqrt(np.log2(X.size)) * np.finfo(X.dtype).eps
     if order == 'F':
diff --git a/numpy/lib/_arraypad_impl.py b/numpy/lib/_arraypad_impl.py
@@ -490,7 +490,7 @@ def _as_pairs(x, ndim, as_index=False):
 
     x = np.array(x)
     if as_index:
-        x = np.round(x).astype(np.intp, copy=None)
+        x = np.round(x).astype(np.intp, copy=False)
 
     if x.ndim < 3:
         # Optimization: Possibly use faster paths for cases where `x` has
diff --git a/numpy/lib/_histograms_impl.py b/numpy/lib/_histograms_impl.py
@@ -838,7 +838,7 @@ def histogram(a, bins=10, range=None, density=None, weights=None):
             # This cast ensures no type promotions occur below, which gh-10322
             # make unpredictable. Getting it wrong leads to precision errors
             # like gh-8123.
-            tmp_a = tmp_a.astype(bin_edges.dtype, copy=None)
+            tmp_a = tmp_a.astype(bin_edges.dtype, copy=False)
 
             # Compute the bin indices, and for values that lie exactly on
             # last_edge we need to subtract one
diff --git a/numpy/lib/_twodim_base_impl.py b/numpy/lib/_twodim_base_impl.py
@@ -415,7 +415,7 @@ def tri(N, M=None, k=0, dtype=float, *, like=None):
                             arange(-k, M-k, dtype=_min_int(-k, M - k)))
 
     # Avoid making a copy if the requested type is already bool
-    m = m.astype(dtype, copy=None)
+    m = m.astype(dtype, copy=False)
 
     return m
 
diff --git a/numpy/lib/recfunctions.py b/numpy/lib/recfunctions.py
@@ -828,7 +828,7 @@ def repack_fields(a, align=False, recurse=False):
     """
     if not isinstance(a, np.dtype):
         dt = repack_fields(a.dtype, align=align, recurse=recurse)
-        return a.astype(dt, copy=None)
+        return a.astype(dt, copy=False)
 
     if a.names is None:
         return a
@@ -936,7 +936,7 @@ def _structured_to_unstructured_dispatcher(arr, dtype=None, copy=None,
     return (arr,)
 
 @array_function_dispatch(_structured_to_unstructured_dispatcher)
-def structured_to_unstructured(arr, dtype=None, copy=None, casting='unsafe'):
+def structured_to_unstructured(arr, dtype=None, copy=False, casting='unsafe'):
     """
     Converts an n-D structured array into an (n+1)-D unstructured array.
 
@@ -955,11 +955,10 @@ def structured_to_unstructured(arr, dtype=None, copy=None, casting='unsafe'):
     dtype : dtype, optional
        The dtype of the output unstructured array.
     copy : bool, optional
-        If True, always return a copy. If None, a view is returned if
+        If true, always return a copy. If false, a view is returned if
         possible, such as when the `dtype` and strides of the fields are
         suitable and the array subtype is one of `numpy.ndarray`,
-        `numpy.recarray` or `numpy.memmap`. For False it raises a ValueError
-        if a copy cannot be avoided.
+        `numpy.recarray` or `numpy.memmap`.
 
         .. versionchanged:: 1.25.0
             A view can now be returned if the fields are separated by a
@@ -1072,7 +1071,7 @@ def _unstructured_to_structured_dispatcher(arr, dtype=None, names=None,
 
 @array_function_dispatch(_unstructured_to_structured_dispatcher)
 def unstructured_to_structured(arr, dtype=None, names=None, align=False,
-                               copy=None, casting='unsafe'):
+                               copy=False, casting='unsafe'):
     """
     Converts an n-D unstructured array into an (n-1)-D structured array.
 
diff --git a/numpy/linalg/_linalg.py b/numpy/linalg/_linalg.py
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
diff --git a/numpy/ma/tests/test_core.py b/numpy/ma/tests/test_core.py
diff --git a/numpy/ma/testutils.py b/numpy/ma/testutils.py
diff --git a/numpy/matrixlib/tests/test_interaction.py b/numpy/matrixlib/tests/test_interaction.py
