DEP: Deprecate setting the dtype of an numpy.ndarray (#29575)

eendebakpt · seberg · web-flow · commit 3b024185c3dc · 2026-04-07T10:16:45.000+02:00
Co-authored-by: Sebastian Berg &lt;sebastian@sipsolutions.net&gt;
diff --git a/doc/release/upcoming_changes/29244.deprecation.rst b/doc/release/upcoming_changes/29244.deprecation.rst
@@ -0,0 +1,6 @@
+Setting the ``dtype`` attribute is deprecated
+---------------------------------------------
+Setting the dtype attribute is now deprecated since mutating
+an array is unsafe if an array is shared, especially by multiple
+threads.  As an alternative, you can create a view with a new dtype
+via `array.view(dtype=new_dtype)`.
diff --git a/numpy/_core/records.py b/numpy/_core/records.py
@@ -455,7 +455,11 @@ def __setattr__(self, attr, val):
 
         newattr = attr not in self.__dict__
         try:
-            ret = object.__setattr__(self, attr, val)
+            if attr == 'dtype':
+                # gh-29244
+                ret = self._set_dtype(val)
+            else:
+                ret = object.__setattr__(self, attr, val)
         except Exception:
             fielddict = ndarray.__getattribute__(self, 'dtype').fields or {}
             if attr not in fielddict:
diff --git a/numpy/_core/src/multiarray/getset.c b/numpy/_core/src/multiarray/getset.c
@@ -341,16 +341,11 @@ array_nbytes_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
  * (contiguous or fortran) with compatible dimensions The shape and strides
  * will be adjusted in that case as well.
  */
-static int
-array_descr_set(PyArrayObject *self, PyObject *arg, void *NPY_UNUSED(ignored))
+NPY_NO_EXPORT int
+array_descr_set_internal(PyArrayObject *self, PyObject *arg)
 {
     PyArray_Descr *newtype = NULL;
-
-    if (arg == NULL) {
-        PyErr_SetString(PyExc_AttributeError,
-                "Cannot delete array dtype");
-        return -1;
-    }
+    assert(arg);
 
     if (!(PyArray_DescrConverter(arg, &newtype)) ||
         newtype == NULL) {
@@ -496,6 +491,43 @@ array_descr_set(PyArrayObject *self, PyObject *arg, void *NPY_UNUSED(ignored))
     return -1;
 }
 
+static int
+non_unique_reference(PyObject *lhs)
+{
+    // Return 1 if we have a guaranteed non-unique reference
+    // When 0 is returned, the object can be unique or non-unique
+#if defined(PYPY_VERSION)
+    // on pypy we cannot use reference counting
+    return 0;
+#endif
+    return Py_REFCNT(lhs) > 1;
+}
+
+static int
+array_descr_set(PyArrayObject *self, PyObject *arg)
+{
+    if (arg == NULL) {
+        PyErr_SetString(PyExc_AttributeError,
+                "Cannot delete array dtype");
+        return -1;
+    }
+
+    if (non_unique_reference((PyObject *)self)) {
+         // this will not emit deprecation warnings for all cases, but for most it will
+         // we skip unique references, so that we will not get a deprecation warning
+         // when array.view(new_dtype) is called
+         /* DEPRECATED 2026-02-06, NumPy 2.5 */
+         int ret = PyErr_WarnEx(PyExc_DeprecationWarning,
+                    "Setting the dtype on a NumPy array has been deprecated in NumPy 2.4.\n"
+                    "Instead of changing the dtype on an array x, create a new array with x.view(new_dtype)",
+                    1);
+        if (ret) {
+            return -1;
+        }
+    }
+    return array_descr_set_internal(self, arg);
+}
+
 static PyObject *
 array_struct_get(PyArrayObject *self, void *NPY_UNUSED(ignored))
 {
diff --git a/numpy/_core/src/multiarray/getset.h b/numpy/_core/src/multiarray/getset.h
@@ -3,6 +3,7 @@
 
 extern NPY_NO_EXPORT PyGetSetDef array_getsetlist[];
 
+NPY_NO_EXPORT int array_descr_set_internal(PyArrayObject *self, PyObject *arg);
 NPY_NO_EXPORT int array_shape_set_internal(PyArrayObject *self, PyObject *val);
 
 #endif  /* NUMPY_CORE_SRC_MULTIARRAY_GETSET_H_ */
diff --git a/numpy/_core/src/multiarray/methods.c b/numpy/_core/src/multiarray/methods.c
@@ -2556,6 +2556,15 @@ array_trace(PyArrayObject *self,
 
 #undef _CHKTYPENUM
 
+static PyObject* array__set_dtype(PyObject *self, PyObject *args)
+{
+    int r = array_descr_set_internal((PyArrayObject *)self, args);
+
+    if (r < 0) {
+        return NULL;
+    }
+    Py_RETURN_NONE;
+}
 
 static PyObject *
 array_clip(PyArrayObject *self,
@@ -3057,6 +3066,9 @@ NPY_NO_EXPORT PyMethodDef array_methods[] = {
     {"to_device",
         (PyCFunction)array_to_device,
         METH_VARARGS | METH_KEYWORDS, NULL},
-
+    // For deprecation of ndarray setters
+    {"_set_dtype",
+        (PyCFunction)array__set_dtype,
+        METH_O, NULL},
     {NULL, NULL, 0, NULL}           /* sentinel */
 };
diff --git a/numpy/_core/tests/test_deprecations.py b/numpy/_core/tests/test_deprecations.py
@@ -11,7 +11,7 @@
 
 import numpy as np
 from numpy._core._multiarray_tests import fromstring_null_term_c_api  # noqa: F401
-from numpy.testing import assert_raises
+from numpy.testing import IS_PYPY, assert_raises
 
 
 class _DeprecationTestCase:
@@ -250,6 +250,11 @@ def test_deprecated_strides_set(self):
         x = np.eye(2)
         self.assert_deprecated(setattr, args=(x, 'strides', x.strides))
 
+    @pytest.mark.skipif(IS_PYPY, reason="PyPy handles refcounts differently")
+    def test_deprecated_dtype_set(self):
+        x = np.eye(2)
+        self.assert_deprecated(setattr, args=(x, "dtype", int))
+
     def test_deprecated_shape_set(self):
         x = np.eye(2)
         self.assert_deprecated(setattr, args=(x, "shape", (4, 1)))
diff --git a/numpy/_core/tests/test_dtype.py b/numpy/_core/tests/test_dtype.py
@@ -6,6 +6,7 @@
 import pickle
 import sys
 import types
+import warnings
 from itertools import permutations
 from typing import Any
 
@@ -1116,7 +1117,10 @@ def test_zero_stride(self):
         arr = np.broadcast_to(arr, 10)
         assert arr.strides == (0,)
         with pytest.raises(ValueError):
-            arr.dtype = "i1"
+            with warnings.catch_warnings():  # gh-28901
+                warnings.filterwarnings(action="ignore",
+                                        category=DeprecationWarning)
+                arr.dtype = "i1"
 
 class TestDTypeMakeCanonical:
     def check_canonical(self, dtype, canonical):
diff --git a/numpy/_core/tests/test_numerictypes.py b/numpy/_core/tests/test_numerictypes.py
@@ -335,7 +335,7 @@ class TestReadValuesNestedMultiple(ReadValuesNested):
 class TestEmptyField:
     def test_assign(self):
         a = np.arange(10, dtype=np.float32)
-        a.dtype = [("int",   "<0i4"), ("float", "<2f4")]
+        a = a.view(dtype=[("int", "<0i4"), ("float", "<2f4")])
         assert_(a['int'].shape == (5, 0))
         assert_(a['float'].shape == (5, 2))
 
diff --git a/numpy/lib/_stride_tricks_impl.py b/numpy/lib/_stride_tricks_impl.py
@@ -140,7 +140,7 @@ def as_strided(
     array = np.asarray(DummyArray(interface, base=base))
     # The route via `__interface__` does not preserve structured
     # dtypes. Since dtype should remain unchanged, we set it explicitly.
-    array.dtype = base.dtype
+    array._set_dtype(base.dtype)
 
     view = _maybe_view_as_subclass(base, array)
 
diff --git a/numpy/ma/core.py b/numpy/ma/core.py
@@ -3495,7 +3495,7 @@ def dtype(self):
 
     @dtype.setter
     def dtype(self, dtype):
-        super(MaskedArray, type(self)).dtype.__set__(self, dtype)
+        self._set_dtype(dtype)
         if self._mask is not nomask:
             self._mask = self._mask.view(make_mask_descr(dtype), ndarray)
             # Try to reset the shape of the mask (if we don't have a void).
diff --git a/numpy/tests/test_warnings.py b/numpy/tests/test_warnings.py
@@ -34,7 +34,7 @@ def visit_Call(self, node):
         ast.NodeVisitor.generic_visit(self, node)
 
         if p.ls[-1] == 'simplefilter' or p.ls[-1] == 'filterwarnings':
-            if getattr(node.args[0], "value", None) == "ignore":
+            if node.args and getattr(node.args[0], "value", None) == "ignore":
                 if not self.__filename.name.startswith("test_"):
                     raise AssertionError(
                         "ignore filters should only be used in tests; "
diff --git a/numpy/typing/__init__.py b/numpy/typing/__init__.py
@@ -64,14 +64,7 @@
 ndarray
 ~~~~~~~
 
-It's possible to mutate the dtype of an array at runtime. For example,
-the following code is valid:
-
-.. code-block:: python
-
-    >>> x = np.array([1, 2])
-    >>> x.dtype = np.bool
-
+It's possible (but deprecated) to mutate the dtype of an array at runtime.
 This sort of mutation is not allowed by the types. Users who want to
 write statically typed code should instead use the `numpy.ndarray.view`
 method to create a view of the array with a different dtype.
