DOC: Add release notes for array-coercion changes

1 files changed, 58 insertions, 0 deletions

diff --git a/doc/release/upcoming_changes/16200.compatibility.rst b/doc/release/upcoming_changes/16200.compatibility.rst
new file mode 100644
index 000000000..c95165af7
--- /dev/null
+++ b/doc/release/upcoming_changes/16200.compatibility.rst
@@ -0,0 +1,58 @@
+NumPy Scalars are cast when assigned to arrays
+----------------------------------------------
+
+When creating or assigning to arrays, in all relevant cases NumPy
+scalars will now be cast identically to NumPy arrays.  In particular
+this changes the behaviour in some cases which previously raised an
+error::
+
+    np.array([np.float64(np.nan)], dtype=np.int64)
+
+will succeed at this time (this may change) and return an undefined result
+(usually the smallest possible integer).  This also affects assignments::
+
+    arr[0] = np.float64(np.nan)
+
+Note, this already happened for ``np.array(np.float64(np.nan), dtype=np.int64)``
+and that the behaviour is unchanged for ``np.nan`` itself which is a Python
+float.
+
+
+Array coercion changes when Strings and other types are mixed
+-------------------------------------------------------------
+
+When stringss and other types are mixed, such as::
+
+    np.array(["string", np.float64(3.)], dtype="S")
+
+The results will change, which may lead to string dtypes with longer strings
+in some cases.  In particularly, if ``dtype="S"`` is not provided any numerical
+value will lead to a string results long enough to hold all possible numerical
+values. (e.g. "S32" for floats).  Note that you should always provide
+``dtype="S"`` when converting non-strings to strings.
+
+If ``dtype="S"`` is provided the results will be largely identical to before,
+but NumPy scalars (not a Python float like ``1.0``), will still enforce
+a uniform string length::
+
+    np.array([np.float64(3.)], dtype="S")  # gives "S32"
+    np.array([3.0], dtype="S")  # gives "S3"
+
+while previously the fist version gave the same result as the second.
+
+
+Array coercion restructure
+--------------------------
+
+Array coercion has been restructured.  In general, this should not affect
+users.  In extremely rare corner cases where array-likes are nested::
+
+    np.array([array_like1])
+
+things will now be more consistent with::
+
+    np.array([np.array(array_like1)])
+
+which could potentially change output subtly for badly defined array-likes.
+We are not aware of any such case where the results were not clearly
+incorrect previously.