Merge pull request #17596 from seberg/subarray-dtype-futurewarning

DEP,BUG: Coercion/cast of array to a subarray dtype will be fixed

2 files changed, 30 insertions, 24 deletions

diff --git a/doc/release/upcoming_changes/17419.deprecation.rst b/doc/release/upcoming_changes/17419.deprecation.rst
deleted file mode 100644
index fcab3a8ad..000000000
--- a/doc/release/upcoming_changes/17419.deprecation.rst
+++ /dev/null
@@ -1,24 +0,0 @@
-Arrays cannot be using subarray dtypes
---------------------------------------
-Array creation and casting using ``np.array(obj, dtype)``
-and ``arr.astype(dtype)`` will not support ``dtype``
-to be a subarray dtype such as ``np.dtype("(2)i,")``.
-
-For such a ``dtype`` the following behaviour occurs currently::
-
-    res = np.array(obj, dtype)
-
-    res.dtype is not dtype
-    res.dtype is dtype.base
-    res.shape[-dtype.ndim:] == dtype.shape
-
-The shape of the dtype is included into the array.
-This leads to inconsistencies when ``obj`` is:
-
-* a scalar, such as ``np.array(1, dtype="(2)i")``
-* an array, such as ``np.array(np.array([1]), dtype="(2)i")``
-
-In most cases the work-around is to pass the output dtype directly
-and possibly check ``res.shape[-dtype.ndim:] == dtype.shape``.
-If this is insufficient, please open an issue on the NumPy issue
-tracker.
diff --git a/doc/release/upcoming_changes/17596.future.rst b/doc/release/upcoming_changes/17596.future.rst
new file mode 100644
index 000000000..6e697c8d1
--- /dev/null
+++ b/doc/release/upcoming_changes/17596.future.rst
@@ -0,0 +1,30 @@
+Arrays cannot be using subarray dtypes
+--------------------------------------
+Array creation and casting using ``np.array(arr, dtype)``
+and ``arr.astype(dtype)`` will use different logic when ``dtype``
+is a subarray dtype such as ``np.dtype("(2)i,")``.
+
+For such a ``dtype`` the following behaviour is true::
+
+    res = np.array(arr, dtype)
+
+    res.dtype is not dtype
+    res.dtype is dtype.base
+    res.shape == arr.shape + dtype.shape
+
+But ``res`` is filled using the logic:
+
+    res = np.empty(arr.shape + dtype.shape, dtype=dtype.base)
+    res[...] = arr
+
+which uses incorrect broadcasting (and often leads to an error).
+In the future, this will instead cast each element individually,
+leading to the same result as::
+
+    res = np.array(arr, dtype=np.dtype(["f", dtype]))["f"]
+
+Which can normally be used to opt-in to the new behaviour.
+
+This change does not affect ``np.array(list, dtype="(2)i,")`` unless the
+``list`` itself includes at least one array.  In particular, the behaviour
+is unchanged for a list of tuples.