summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorM. Eric Irrgang <ericirrgang@gmail.com>2022-07-17 13:12:31 -0500
committerM. Eric Irrgang <ericirrgang@gmail.com>2022-07-17 13:12:31 -0500
commitb1a8ff8fa73b744416e12cdd4bb70594717b5336 (patch)
tree53e0a5c12add122b1ea7ac2996dcee091ec4240d /doc
parent01438a848b029b4fb3d3509c7fd313bc0588bd38 (diff)
downloadnumpy-b1a8ff8fa73b744416e12cdd4bb70594717b5336.tar.gz
Add release note and further clarify tests.
Diffstat (limited to 'doc')
-rw-r--r--doc/release/upcoming_changes/21995.compatibility.rst46
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/release/upcoming_changes/21995.compatibility.rst b/doc/release/upcoming_changes/21995.compatibility.rst
new file mode 100644
index 000000000..cc00b50b3
--- /dev/null
+++ b/doc/release/upcoming_changes/21995.compatibility.rst
@@ -0,0 +1,46 @@
+Returned arrays respect uniqueness of dtype kwarg objects
+---------------------------------------------------------
+When ``dtype`` keyword argument is used with :py:func:`np.array()`
+or :py:func:`asarray()`, the dtype of the returned array has
+the same dtype *instance* as provided by the caller.
+
+If the provided dtype is compatible, but not identically the same
+:py:class:`dtype` object, a new array handle is always created with
+a reference to the user-provided dtype instance.
+If the data type is compatible, and copying is not required, the new
+`ndarray` uses the original array as its
+`base <https://numpy.org/doc/stable/reference/generated/numpy.ndarray.base.html>`__.
+
+Before this change, for two equivalent but non-identical dtypes,
+
+ assert isinstance(typeA, np.dtype) and isinstance(typeB, np.dtype)
+ assert typeA == typeB
+ assert typeA is not typeB
+ if my_array.dtype is typeA:
+ assert my_array is np.asarray(my_array, dtype=typeB)
+ assert np.asarray(my_array, dtype=typeB).dtype is not typeB
+
+This change allows programs to be able to reliably get the exact dtype
+representation they request, regardless of possibly aliased types on the
+calling platform.
+
+However, identity semantics for array results and their
+dtype members may require minor updates to calling code.
+
+After this change, on a system where C ``int`` and C ``long`` are the same
+precision, ``np.dtype('i') == np.dtype('l')``,
+but ``np.dtype('i') is not np.dtype('l')``.
+
+ assert int_array.dtype is np.dtype('i')
+ long_int_array = np.asarray(int_array, dtype='l')
+ assert long_int_array is not int_array
+ if np.dtype('i') == np.dtype('l'):
+ assert int_array is long_int_array.base
+
+New array views are created with each call to `asarray` with non-identical
+dtype kwarg, but the underlying data is the same.
+
+ assert int_array.dtype is np.dtype('i')
+ long_int_array = np.asarray(int_array, dtype='l')
+ assert long_int_array is not np.asarray(int_array, dtype='l')
+ assert long_int_array.base is np.asarray(int_array, dtype='l').base