diff options
author | Sebastian Berg <sebastian@sipsolutions.net> | 2022-09-03 18:19:03 +0200 |
---|---|---|
committer | Sebastian Berg <sebastian@sipsolutions.net> | 2022-09-03 18:19:03 +0200 |
commit | 235b75e939b8233f29a073175d93070fcfc5e8d1 (patch) | |
tree | be5d66f92659dd691cdbcc497661bddc4df91db4 /doc | |
parent | b1a8ff8fa73b744416e12cdd4bb70594717b5336 (diff) | |
download | numpy-235b75e939b8233f29a073175d93070fcfc5e8d1.tar.gz |
DOC: Take a stab at shortening the release note
Diffstat (limited to 'doc')
-rw-r--r-- | doc/release/upcoming_changes/21995.compatibility.rst | 63 |
1 files changed, 19 insertions, 44 deletions
diff --git a/doc/release/upcoming_changes/21995.compatibility.rst b/doc/release/upcoming_changes/21995.compatibility.rst index cc00b50b3..d3ff9c1bd 100644 --- a/doc/release/upcoming_changes/21995.compatibility.rst +++ b/doc/release/upcoming_changes/21995.compatibility.rst @@ -1,46 +1,21 @@ 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 +When the ``dtype`` keyword argument is used with :py:func:`np.array()` +or :py:func:`asarray()`, the dtype of the returned array now +always exactly matches the dtype provided by the caller. + +In some cases this change means that a *view* rather than the +input array is returned. +The following is an example for this on 64bit Linux where ``long`` +and ``longlong`` are the same precision:: + + >>> arr = np.array([1, 2, 3], dtype="long") + >>> new_dtype = np.dtype("longlong") + >>> new = np.asarray(arr, dtype=new_dtype) + >>> new.dtype is dtype + True + >>> new is arr + False + +Before the change, the ``dtype`` did not match because ``new is arr`` +was true. |