diff options
author | M. Eric Irrgang <ericirrgang@gmail.com> | 2022-07-17 13:12:31 -0500 |
---|---|---|
committer | M. Eric Irrgang <ericirrgang@gmail.com> | 2022-07-17 13:12:31 -0500 |
commit | b1a8ff8fa73b744416e12cdd4bb70594717b5336 (patch) | |
tree | 53e0a5c12add122b1ea7ac2996dcee091ec4240d /doc | |
parent | 01438a848b029b4fb3d3509c7fd313bc0588bd38 (diff) | |
download | numpy-b1a8ff8fa73b744416e12cdd4bb70594717b5336.tar.gz |
Add release note and further clarify tests.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/release/upcoming_changes/21995.compatibility.rst | 46 |
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 |