diff options
Diffstat (limited to 'doc/release/upcoming_changes')
| -rw-r--r-- | doc/release/upcoming_changes/22539.change.rst | 19 | ||||
| -rw-r--r-- | doc/release/upcoming_changes/22539.deprecation.rst | 29 |
2 files changed, 48 insertions, 0 deletions
diff --git a/doc/release/upcoming_changes/22539.change.rst b/doc/release/upcoming_changes/22539.change.rst new file mode 100644 index 000000000..9df62be30 --- /dev/null +++ b/doc/release/upcoming_changes/22539.change.rst @@ -0,0 +1,19 @@ +``np.r_[]`` and ``np.c_[]`` with certain scalar values +------------------------------------------------------ +In rare cases, using mainly ``np.r_`` with scalars can lead to different +results. The main potential changes are highlighted by the following:: + + >>> np.r_[np.arange(5, dtype=np.uint8), -1].dtype + int16 # rather than the default integer (int64 or int32) + >>> np.r_[np.arange(5, dtype=np.int8), 255] + array([ 0, 1, 2, 3, 4, 255], dtype=int16) + +Where the second example returned:: + + array([ 0, 1, 2, 3, 4, -1], dtype=int8) + +The first one is due to a signed integer scalar with an unsigned integer +array, while the second is due to ``255`` not fitting into ``int8`` and +NumPy currently inspecting values to make this work. +(Note that the second example is expected to change in the future due to +:ref:`NEP 50 <NEP50>`; it will then raise an error.) diff --git a/doc/release/upcoming_changes/22539.deprecation.rst b/doc/release/upcoming_changes/22539.deprecation.rst new file mode 100644 index 000000000..a30434b7e --- /dev/null +++ b/doc/release/upcoming_changes/22539.deprecation.rst @@ -0,0 +1,29 @@ +``np.find_common_type`` is deprecated +------------------------------------- +`numpy.find_common_type` is now deprecated and its use should be replaced +with either `numpy.result_type` or `numpy.promote_types`. +Most users leave the second ``scalar_types`` argument to ``find_common_type`` +as ``[]`` in which case ``np.result_type`` and ``np.promote_types`` are both +faster and more robust. +When not using ``scalar_types`` the main difference is that the replacement +intentionally converts non-native byte-order to native byte order. +Further, ``find_common_type`` returns ``object`` dtype rather than failing +promotion. This leads to differences when the inputs are not all numeric. +Importantly, this also happens for e.g. timedelta/datetime for which NumPy +promotion rules are currently sometimes surprising. + +When the ``scalar_types`` argument is not ``[]`` things are more complicated. +In most cases, using ``np.result_type`` and passing the Python values +``0``, ``0.0``, or ``0j`` has the same result as using ``int``, ``float``, +or ``complex`` in `scalar_types`. + +When ``scalar_types`` is constructed, ``np.result_type`` is the +correct replacement and it may be passed scalar values like ``np.float32(0.0)``. +Passing values other than 0, may lead to value-inspecting behavior +(which ``np.find_common_type`` never used and NEP 50 may change in the future). +The main possible change in behavior in this case, is when the array types +are signed integers and scalar types are unsigned. + +If you are unsure about how to replace a use of ``scalar_types`` or when +non-numeric dtypes are likely, please do not hesitate to open a NumPy issue +to ask for help. |