Skip to content

Commit cee14ff

Browse files
jorenhamcharris
jorenham
and
charris
authored
DOC: prefer passing scalar types to dtype= in examples (#30394)
* DOC: prefer scalar types for ``dtype=`` * DOC: revert doc change in `mtrand.pyx` Co-authored-by: Charles Harris <charlesr.harris@gmail.com> --------- Co-authored-by: Charles Harris <charlesr.harris@gmail.com>
1 parent e113b65 commit cee14ff

39 files changed

Lines changed: 194 additions & 196 deletions

‎doc/neps/nep-0050-scalar-promotion.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -509,9 +509,9 @@ will be ignored. This means, that operations will never silently use the
509509
The user will have to write one of::
510510

511511
np.array([3]) + np.array(2**100)
512-
np.array([3]) + np.array(2**100, dtype=object)
512+
np.array([3]) + np.array(2**100, dtype=np.object_)
513513

514-
As such implicit conversion to ``object`` should be rare and the work-around
514+
As such implicit conversion to ``object_`` should be rare and the work-around
515515
is clear, we expect that the backwards compatibility concerns are fairly small.
516516

517517

‎doc/neps/nep-0055-string_dtype.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -224,7 +224,7 @@ to fixed-width unicode arrays::
224224

225225
In [3]: data = [str(i) * 10 for i in range(100_000)]
226226

227-
In [4]: %timeit arr_object = np.array(data, dtype=object)
227+
In [4]: %timeit arr_object = np.array(data, dtype=np.object_)
228228
3.15 ms ± 74.4 µs per loop (mean ± std. dev. of 7 runs, 100 loops each)
229229

230230
In [5]: %timeit arr_stringdtype = np.array(data, dtype=StringDType())
@@ -242,7 +242,7 @@ for strings, the string loading performance of ``StringDType`` should improve.
242242

243243
String operations have similar performance::
244244

245-
In [7]: %timeit np.array([s.capitalize() for s in data], dtype=object)
245+
In [7]: %timeit np.array([s.capitalize() for s in data], dtype=np.object_)
246246
31.6 ms ± 728 µs per loop (mean ± std. dev. of 7 runs, 10 loops each)
247247

248248
In [8]: %timeit np.char.capitalize(arr_stringdtype)

‎doc/source/reference/arrays.classes.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -479,16 +479,16 @@ Example:
479479

480480
>>> import numpy as np
481481

482-
>>> a = np.memmap('newfile.dat', dtype=float, mode='w+', shape=1000)
482+
>>> a = np.memmap('newfile.dat', dtype=np.float64, mode='w+', shape=1000)
483483
>>> a[10] = 10.0
484484
>>> a[30] = 30.0
485485
>>> del a
486486

487-
>>> b = np.fromfile('newfile.dat', dtype=float)
487+
>>> b = np.fromfile('newfile.dat', dtype=np.float64)
488488
>>> print(b[10], b[30])
489489
10.0 30.0
490490

491-
>>> a = np.memmap('newfile.dat', dtype=float)
491+
>>> a = np.memmap('newfile.dat', dtype=np.float64)
492492
>>> print(a[10], a[30])
493493
10.0 30.0
494494

‎doc/source/reference/arrays.datetime.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,10 +124,10 @@ datetime type with generic units.
124124

125125
>>> import numpy as np
126126

127-
>>> np.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64')
127+
>>> np.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype=np.datetime64)
128128
array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64[D]')
129129

130-
>>> np.array(['2001-01-01T12:00', '2002-02-03T13:56:03.172'], dtype='datetime64')
130+
>>> np.array(['2001-01-01T12:00', '2002-02-03T13:56:03.172'], dtype=np.datetime64)
131131
array(['2001-01-01T12:00:00.000', '2002-02-03T13:56:03.172'],
132132
dtype='datetime64[ms]')
133133

‎doc/source/reference/arrays.dtypes.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -561,7 +561,7 @@ This equivalence can only be handled through ``==``, not through ``is``.
561561

562562
>>> import numpy as np
563563

564-
>>> a = np.array([1, 2], dtype=float)
564+
>>> a = np.array([1, 2], dtype=np.float64)
565565
>>> a.dtype == np.dtype(np.float64)
566566
True
567567
>>> a.dtype == np.float64

‎doc/source/reference/arrays.promotion.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,10 +79,10 @@ their precision when determining the result dtype. This is often convenient.
7979
For instance, when working with arrays of a low precision dtype, it is usually
8080
desirable for simple operations with Python scalars to preserve the dtype.
8181

82-
>>> arr_float32 = np.array([1, 2.5, 2.1], dtype="float32")
82+
>>> arr_float32 = np.array([1, 2.5, 2.1], dtype=np.float32)
8383
>>> arr_float32 + 10.0 # undesirable to promote to float64
8484
array([11. , 12.5, 12.1], dtype=float32)
85-
>>> arr_int16 = np.array([3, 5, 7], dtype="int16")
85+
>>> arr_int16 = np.array([3, 5, 7], dtype=np.int16)
8686
>>> arr_int16 + 10 # undesirable to promote to int64
8787
array([13, 15, 17], dtype=int16)
8888

@@ -130,7 +130,7 @@ overflows:
130130
... RuntimeWarning: overflow encountered in scalar add
131131

132132
Note that NumPy warns when overflows occur for scalars, but not for arrays;
133-
e.g., ``np.array(100, dtype="uint8") + 100`` will *not* warn.
133+
e.g., ``np.array(100, dtype=np.uint8) + 100`` will *not* warn.
134134

135135
Numerical promotion
136136
-------------------

‎doc/source/reference/c-api/array.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1786,9 +1786,9 @@ the functions that must be implemented for each slot.
17861786
- ``0.0`` is the default for ``sum([])``. But ``-0.0`` is the correct
17871787
identity otherwise as it preserves the sign for ``sum([-0.0])``.
17881788
- We use no identity for object, but return the default of ``0`` and
1789-
``1`` for the empty ``sum([], dtype=object)`` and
1790-
``prod([], dtype=object)``.
1791-
This allows ``np.sum(np.array(["a", "b"], dtype=object))`` to work.
1789+
``1`` for the empty ``sum([], dtype=np.object_)`` and
1790+
``prod([], dtype=np.object_)``.
1791+
This allows ``np.sum(np.array(["a", "b"], dtype=np.object_))`` to work.
17921792
- ``-inf`` or ``INT_MIN`` for ``max`` is an identity, but at least
17931793
``INT_MIN`` not a good *default* when there are no items.
17941794

‎doc/source/reference/thread_safety.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,8 @@ locking if you need to mutation and multithreading.
2929

3030
Note that operations that *do not* release the GIL will see no performance gains
3131
from use of the `threading` module, and instead might be better served with
32-
`multiprocessing`. In particular, operations on arrays with ``dtype=object`` do
33-
not release the GIL.
32+
`multiprocessing`. In particular, operations on arrays with ``dtype=np.object_``
33+
do not release the GIL.
3434

3535
Free-threaded Python
3636
--------------------
@@ -47,5 +47,5 @@ Because free-threaded Python does not have a global interpreter lock to
4747
serialize access to Python objects, there are more opportunities for threads to
4848
mutate shared state and create thread safety issues. In addition to the
4949
limitations about locking of the ndarray object noted above, this also means
50-
that arrays with ``dtype=object`` are not protected by the GIL, creating data
50+
that arrays with ``dtype=np.object_`` are not protected by the GIL, creating data
5151
races for python objects that are not possible outside free-threaded python.

‎doc/source/user/absolute_beginners.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -779,7 +779,7 @@ You can add the arrays together with the plus sign.
779779
::
780780

781781
>>> data = np.array([1, 2])
782-
>>> ones = np.ones(2, dtype=int)
782+
>>> ones = np.ones(2, dtype=np.int_)
783783
>>> data + ones
784784
array([2, 3])
785785

‎doc/source/user/basics.creation.rst‎

Lines changed: 24 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ There are 6 general mechanisms for creating arrays:
2020
6) Use of special library functions (e.g., random)
2121

2222
You can use these methods to create ndarrays or :ref:`structured_arrays`.
23-
This document will cover general methods for ndarray creation.
23+
This document will cover general methods for ndarray creation.
2424

2525
1) Converting Python sequences to NumPy arrays
2626
==============================================
@@ -29,8 +29,8 @@ NumPy arrays can be defined using Python sequences such as lists and
2929
tuples. Lists and tuples are defined using ``[...]`` and ``(...)``,
3030
respectively. Lists and tuples can define ndarray creation:
3131

32-
* a list of numbers will create a 1D array,
33-
* a list of lists will create a 2D array,
32+
* a list of numbers will create a 1D array,
33+
* a list of lists will create a 2D array,
3434
* further nested lists will create higher-dimensional arrays. In general, any array object is called an **ndarray** in NumPy.
3535

3636
::
@@ -72,7 +72,7 @@ results, for example::
7272

7373
Notice when you perform operations with two arrays of the same
7474
``dtype``: ``uint32``, the resulting array is the same type. When you
75-
perform operations with different ``dtype``, NumPy will
75+
perform operations with different ``dtype``, NumPy will
7676
assign a new type that satisfies all of the array elements involved in
7777
the computation, here ``uint32`` and ``int32`` can both be represented in
7878
as ``int64``.
@@ -88,7 +88,7 @@ you create the array.
8888

8989
..
9090
40 functions seems like a small number, but the routines.array-creation
91-
has ~47. I'm sure there are more.
91+
has ~47. I'm sure there are more.
9292
9393
NumPy has over 40 built-in functions for creating arrays as laid
9494
out in the :ref:`Array creation routines <routines.array-creation>`.
@@ -104,7 +104,7 @@ dimension of the array they create:
104104

105105
The 1D array creation functions e.g. :func:`numpy.linspace` and
106106
:func:`numpy.arange` generally need at least two inputs, ``start`` and
107-
``stop``.
107+
``stop``.
108108

109109
:func:`numpy.arange` creates arrays with regularly incrementing values.
110110
Check the documentation for complete information and examples. A few
@@ -113,16 +113,16 @@ examples are shown::
113113
>>> import numpy as np
114114
>>> np.arange(10)
115115
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
116-
>>> np.arange(2, 10, dtype=float)
116+
>>> np.arange(2, 10, dtype=np.float64)
117117
array([2., 3., 4., 5., 6., 7., 8., 9.])
118118
>>> np.arange(2, 3, 0.1)
119119
array([2. , 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8, 2.9])
120120

121121
Note: best practice for :func:`numpy.arange` is to use integer start, end, and
122122
step values. There are some subtleties regarding ``dtype``. In the second
123123
example, the ``dtype`` is defined. In the third example, the array is
124-
``dtype=float`` to accommodate the step size of ``0.1``. Due to roundoff error,
125-
the ``stop`` value is sometimes included.
124+
``dtype=np.float64`` to accommodate the step size of ``0.1``. Due to roundoff error,
125+
the ``stop`` value is sometimes included.
126126

127127
:func:`numpy.linspace` will create arrays with a specified number of elements, and
128128
spaced equally between the specified beginning and end values. For
@@ -140,7 +140,7 @@ number of elements and the starting and end point. The previous
140140
-------------------------------
141141

142142
The 2D array creation functions e.g. :func:`numpy.eye`, :func:`numpy.diag`, and :func:`numpy.vander`
143-
define properties of special matrices represented as 2D arrays.
143+
define properties of special matrices represented as 2D arrays.
144144

145145
``np.eye(n, m)`` defines a 2D identity matrix. The elements where i=j (row index and column index are equal) are 1
146146
and the rest are 0, as such::
@@ -159,7 +159,7 @@ and the rest are 0, as such::
159159
the diagonal *or* if given a 2D array returns a 1D array that is
160160
only the diagonal elements. The two array creation functions can be helpful while
161161
doing linear algebra, as such::
162-
162+
163163
>>> import numpy as np
164164
>>> np.diag([1, 2, 3])
165165
array([[1, 0, 0],
@@ -197,28 +197,28 @@ routine is helpful in generating linear least squares models, as such::
197197
[ 8, 4, 2, 1],
198198
[27, 9, 3, 1],
199199
[64, 16, 4, 1]])
200-
200+
201201
3 - general ndarray creation functions
202202
--------------------------------------
203203

204204
The ndarray creation functions e.g. :func:`numpy.ones`,
205205
:func:`numpy.zeros`, and :meth:`~numpy.random.Generator.random` define
206206
arrays based upon the desired shape. The ndarray creation functions
207207
can create arrays with any dimension by specifying how many dimensions
208-
and length along that dimension in a tuple or list.
208+
and length along that dimension in a tuple or list.
209209

210210
:func:`numpy.zeros` will create an array filled with 0 values with the
211211
specified shape. The default dtype is ``float64``::
212212

213213
>>> import numpy as np
214214
>>> np.zeros((2, 3))
215-
array([[0., 0., 0.],
215+
array([[0., 0., 0.],
216216
[0., 0., 0.]])
217217
>>> np.zeros((2, 3, 2))
218218
array([[[0., 0.],
219219
[0., 0.],
220220
[0., 0.]],
221-
<BLANKLINE>
221+
<BLANKLINE>
222222
[[0., 0.],
223223
[0., 0.],
224224
[0., 0.]]])
@@ -228,7 +228,7 @@ specified shape. The default dtype is ``float64``::
228228

229229
>>> import numpy as np
230230
>>> np.ones((2, 3))
231-
array([[1., 1., 1.],
231+
array([[1., 1., 1.],
232232
[1., 1., 1.]])
233233
>>> np.ones((2, 3, 2))
234234
array([[[1., 1.],
@@ -265,11 +265,11 @@ dimension::
265265

266266
>>> import numpy as np
267267
>>> np.indices((3,3))
268-
array([[[0, 0, 0],
269-
[1, 1, 1],
270-
[2, 2, 2]],
271-
[[0, 1, 2],
272-
[0, 1, 2],
268+
array([[[0, 0, 0],
269+
[1, 1, 1],
270+
[2, 2, 2]],
271+
[[0, 1, 2],
272+
[0, 1, 2],
273273
[0, 1, 2]]])
274274

275275
This is particularly useful for evaluating functions of multiple dimensions on
@@ -322,15 +322,15 @@ arrays into a 4-by-4 array using ``block``::
322322
[ 0., 0., 0., -4.]])
323323

324324
Other routines use similar syntax to join ndarrays. Check the
325-
routine's documentation for further examples and syntax.
325+
routine's documentation for further examples and syntax.
326326

327327
4) Reading arrays from disk, either from standard or custom formats
328328
===================================================================
329329

330330
This is the most common case of large array creation. The details depend
331331
greatly on the format of data on disk. This section gives general pointers on
332332
how to handle various formats. For more detailed examples of IO look at
333-
:ref:`How to Read and Write files <how-to-io>`.
333+
:ref:`How to Read and Write files <how-to-io>`.
334334

335335
Standard binary formats
336336
-----------------------
@@ -397,4 +397,4 @@ knowledge to interface with C or C++.
397397
NumPy is the fundamental library for array containers in the Python Scientific Computing
398398
stack. Many Python libraries, including SciPy, Pandas, and OpenCV, use NumPy ndarrays
399399
as the common format for data exchange, These libraries can create,
400-
operate on, and work with NumPy arrays.
400+
operate on, and work with NumPy arrays.

0 commit comments

Comments
 (0)