diff options
Diffstat (limited to 'doc/source')
| -rw-r--r-- | doc/source/release/1.20.0-notes.rst | 74 | ||||
| -rw-r--r-- | doc/source/user/basics.dispatch.rst | 18 | ||||
| -rw-r--r-- | doc/source/user/basics.types.rst | 2 |
3 files changed, 61 insertions, 33 deletions
diff --git a/doc/source/release/1.20.0-notes.rst b/doc/source/release/1.20.0-notes.rst index e26aa0d40..b8b7a0c79 100644 --- a/doc/source/release/1.20.0-notes.rst +++ b/doc/source/release/1.20.0-notes.rst @@ -3,8 +3,8 @@ ========================== NumPy 1.20.0 Release Notes ========================== -This NumPy release is the largest so made to date, some 648 PRs contributed by -182 people have been merged. See the list of highlights below for more details. +This NumPy release is the largest so made to date, some 684 PRs contributed by +184 people have been merged. See the list of highlights below for more details. The Python versions supported for this release are 3.7-3.9, support for Python 3.6 has been dropped. Highlights are @@ -75,32 +75,60 @@ Using the aliases of builtin types like ``np.int`` is deprecated ---------------------------------------------------------------- For a long time, ``np.int`` has been an alias of the builtin ``int``. This is -repeatedly a cause of confusion for newcomers, and is also simply not useful. +repeatedly a cause of confusion for newcomers, and existed mainly for historic +reasons. These aliases have been deprecated. The table below shows the full list of deprecated aliases, along with their exact meaning. Replacing uses of items in the first column with the contents of the second column will work identically and silence the deprecation warning. -In many cases, it may have been intended to use the types from the third column. -Be aware that use of these types may result in subtle but desirable behavior -changes. - -================== ================================= ================================================================== -Deprecated name Identical to Possibly intended numpy type -================== ================================= ================================================================== -``numpy.bool`` ``bool`` `numpy.bool_` -``numpy.int`` ``int`` `numpy.int_` (default int dtype), `numpy.cint` (C ``int``) -``numpy.float`` ``float`` `numpy.float_`, `numpy.double` (equivalent) -``numpy.complex`` ``complex`` `numpy.complex_`, `numpy.cdouble` (equivalent) -``numpy.object`` ``object`` `numpy.object_` -``numpy.str`` ``str`` `numpy.str_` -``numpy.long`` ``int`` (``long`` on Python 2) `numpy.int_` (C ``long``), `numpy.longlong` (largest integer type) -``numpy.unicode`` ``str`` (``unicode`` on Python 2) `numpy.unicode_` -================== ================================= ================================================================== - -Note that for technical reasons these deprecation warnings will only be emitted -on Python 3.7 and above. +The third column lists alternative NumPy names which may occasionally be +preferential. See also :ref:`basics.types` for additional details. + +================= ============ ================================================================== +Deprecated name Identical to NumPy scalar type names +================= ============ ================================================================== +``numpy.bool`` ``bool`` `numpy.bool_` +``numpy.int`` ``int`` `numpy.int_` (default), ``numpy.int64``, or ``numpy.int32`` +``numpy.float`` ``float`` `numpy.float64`, `numpy.float_`, `numpy.double` (equivalent) +``numpy.complex`` ``complex`` `numpy.complex128`, `numpy.complex_`, `numpy.cdouble` (equivalent) +``numpy.object`` ``object`` `numpy.object_` +``numpy.str`` ``str`` `numpy.str_` +``numpy.long`` ``int`` `numpy.int_` (C ``long``), `numpy.longlong` (largest integer type) +``numpy.unicode`` ``str`` `numpy.unicode_` +================= ============ ================================================================== + +To give a clear guideline for the vast majority of cases, for the types +``bool``, ``object``, ``str`` (and ``unicode``) using the plain version +is shorter and clear, and generally a good replacement. +For ``float`` and ``complex`` you can use ``float64`` and ``complex128`` +if you wish to be more explicit about the precision. + +For ``np.int`` a direct replacement with ``np.int_`` or ``int`` is also +good and will not change behavior, but the precision will continue to depend +on the computer and operating system. +If you want to be more explicit and review the current use, you have the +following alternatives: + +* ``np.int64`` or ``np.int32`` to specify the precision exactly. + This ensures that results cannot depend on the computer or operating system. +* ``np.int_`` or ``int`` (the default), but be aware that it depends on + the computer and operating system. +* The C types: ``np.cint`` (int), ``np.int_`` (long), ``np.longlong``. +* ``np.intp`` which is 32bit on 32bit machines 64bit on 64bit machines. + This can be the best type to use for indexing. + +When used with ``np.dtype(...)`` or ``dtype=...`` changing it to the +NumPy name as mentioned above will have no effect on the output. +If used as a scalar with:: + + np.float(123) + +changing it can subtly change the result. In this case, the Python version +``float(123)`` or ``int(12.)`` is normally preferable, although the NumPy +version may be useful for consistency with NumPy arrays (for example, +NumPy behaves differently for things like division by zero). (`gh-14882 <https://github.com/numpy/numpy/pull/14882>`__) @@ -972,5 +1000,3 @@ The former result can still be obtained with:: (`gh-16841 <https://github.com/numpy/numpy/pull/16841>`__) - - diff --git a/doc/source/user/basics.dispatch.rst b/doc/source/user/basics.dispatch.rst index c0e1cf9ba..089a7df17 100644 --- a/doc/source/user/basics.dispatch.rst +++ b/doc/source/user/basics.dispatch.rst @@ -22,8 +22,8 @@ example that has rather narrow utility but illustrates the concepts involved. ... self._i = value ... def __repr__(self): ... return f"{self.__class__.__name__}(N={self._N}, value={self._i})" -... def __array__(self): -... return self._i * np.eye(self._N) +... def __array__(self, dtype=None): +... return self._i * np.eye(self._N, dtype=dtype) Our custom array can be instantiated like: @@ -56,7 +56,7 @@ array([[2., 0., 0., 0., 0.], Notice that the return type is a standard ``numpy.ndarray``. ->>> type(arr) +>>> type(np.multiply(arr, 2)) numpy.ndarray How can we pass our custom array type through this function? Numpy allows a @@ -84,8 +84,8 @@ For this example we will only handle the method ``__call__`` ... self._i = value ... def __repr__(self): ... return f"{self.__class__.__name__}(N={self._N}, value={self._i})" -... def __array__(self): -... return self._i * np.eye(self._N) +... def __array__(self, dtype=None): +... return self._i * np.eye(self._N, dtype=dtype) ... def __array_ufunc__(self, ufunc, method, *inputs, **kwargs): ... if method == '__call__': ... N = None @@ -133,8 +133,8 @@ conveniently by inheriting from the mixin ... self._i = value ... def __repr__(self): ... return f"{self.__class__.__name__}(N={self._N}, value={self._i})" -... def __array__(self): -... return self._i * np.eye(self._N) +... def __array__(self, dtype=None): +... return self._i * np.eye(self._N, dtype=dtype) ... def __array_ufunc__(self, ufunc, method, *inputs, **kwargs): ... if method == '__call__': ... N = None @@ -171,8 +171,8 @@ functions to our custom variants. ... self._i = value ... def __repr__(self): ... return f"{self.__class__.__name__}(N={self._N}, value={self._i})" -... def __array__(self): -... return self._i * np.eye(self._N) +... def __array__(self, dtype=None): +... return self._i * np.eye(self._N, dtype=dtype) ... def __array_ufunc__(self, ufunc, method, *inputs, **kwargs): ... if method == '__call__': ... N = None diff --git a/doc/source/user/basics.types.rst b/doc/source/user/basics.types.rst index 781dd66e5..64b6dcf50 100644 --- a/doc/source/user/basics.types.rst +++ b/doc/source/user/basics.types.rst @@ -1,3 +1,5 @@ +.. _basics.types: + ********** Data types ********** |