Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2This file is separate from ``_add_newdocs.py`` so that it can be mocked out by
3our sphinx ``conf.py`` during doc builds, where we want to avoid showing
4platform-dependent information.
5"""
6import sys
7import os
8from numpy.core import dtype
9from numpy.core import numerictypes as _numerictypes
10from numpy.core.function_base import add_newdoc
12##############################################################################
13#
14# Documentation for concrete scalar classes
15#
16##############################################################################
18def numeric_type_aliases(aliases):
19 def type_aliases_gen():
20 for alias, doc in aliases:
21 try:
22 alias_type = getattr(_numerictypes, alias)
23 except AttributeError:
24 # The set of aliases that actually exist varies between platforms
25 pass
26 else:
27 yield (alias_type, alias, doc)
28 return list(type_aliases_gen())
31possible_aliases = numeric_type_aliases([
32 ('int8', '8-bit signed integer (``-128`` to ``127``)'),
33 ('int16', '16-bit signed integer (``-32_768`` to ``32_767``)'),
34 ('int32', '32-bit signed integer (``-2_147_483_648`` to ``2_147_483_647``)'),
35 ('int64', '64-bit signed integer (``-9_223_372_036_854_775_808`` to ``9_223_372_036_854_775_807``)'),
36 ('intp', 'Signed integer large enough to fit pointer, compatible with C ``intptr_t``'),
37 ('uint8', '8-bit unsigned integer (``0`` to ``255``)'),
38 ('uint16', '16-bit unsigned integer (``0`` to ``65_535``)'),
39 ('uint32', '32-bit unsigned integer (``0`` to ``4_294_967_295``)'),
40 ('uint64', '64-bit unsigned integer (``0`` to ``18_446_744_073_709_551_615``)'),
41 ('uintp', 'Unsigned integer large enough to fit pointer, compatible with C ``uintptr_t``'),
42 ('float16', '16-bit-precision floating-point number type: sign bit, 5 bits exponent, 10 bits mantissa'),
43 ('float32', '32-bit-precision floating-point number type: sign bit, 8 bits exponent, 23 bits mantissa'),
44 ('float64', '64-bit precision floating-point number type: sign bit, 11 bits exponent, 52 bits mantissa'),
45 ('float96', '96-bit extended-precision floating-point number type'),
46 ('float128', '128-bit extended-precision floating-point number type'),
47 ('complex64', 'Complex number type composed of 2 32-bit-precision floating-point numbers'),
48 ('complex128', 'Complex number type composed of 2 64-bit-precision floating-point numbers'),
49 ('complex192', 'Complex number type composed of 2 96-bit extended-precision floating-point numbers'),
50 ('complex256', 'Complex number type composed of 2 128-bit extended-precision floating-point numbers'),
51 ])
54def _get_platform_and_machine():
55 try:
56 system, _, _, _, machine = os.uname()
57 except AttributeError:
58 system = sys.platform
59 if system == 'win32':
60 machine = os.environ.get('PROCESSOR_ARCHITEW6432', '') \
61 or os.environ.get('PROCESSOR_ARCHITECTURE', '')
62 else:
63 machine = 'unknown'
64 return system, machine
67_system, _machine = _get_platform_and_machine()
68_doc_alias_string = f":Alias on this platform ({_system} {_machine}):"
71def add_newdoc_for_scalar_type(obj, fixed_aliases, doc):
72 # note: `:field: value` is rST syntax which renders as field lists.
73 o = getattr(_numerictypes, obj)
75 character_code = dtype(o).char
76 canonical_name_doc = "" if obj == o.__name__ else \
77 f":Canonical name: `numpy.{obj}`\n "
78 if fixed_aliases:
79 alias_doc = ''.join(f":Alias: `numpy.{alias}`\n "
80 for alias in fixed_aliases)
81 else:
82 alias_doc = ''
83 alias_doc += ''.join(f"{_doc_alias_string} `numpy.{alias}`: {doc}.\n "
84 for (alias_type, alias, doc) in possible_aliases if alias_type is o)
86 docstring = f"""
87 {doc.strip()}
89 :Character code: ``'{character_code}'``
90 {canonical_name_doc}{alias_doc}
91 """
93 add_newdoc('numpy.core.numerictypes', obj, docstring)
96add_newdoc_for_scalar_type('bool_', [],
97 """
98 Boolean type (True or False), stored as a byte.
100 .. warning::
102 The :class:`bool_` type is not a subclass of the :class:`int_` type
103 (the :class:`bool_` is not even a number type). This is different
104 than Python's default implementation of :class:`bool` as a
105 sub-class of :class:`int`.
106 """)
108add_newdoc_for_scalar_type('byte', [],
109 """
110 Signed integer type, compatible with C ``char``.
111 """)
113add_newdoc_for_scalar_type('short', [],
114 """
115 Signed integer type, compatible with C ``short``.
116 """)
118add_newdoc_for_scalar_type('intc', [],
119 """
120 Signed integer type, compatible with C ``int``.
121 """)
123add_newdoc_for_scalar_type('int_', [],
124 """
125 Signed integer type, compatible with Python `int` and C ``long``.
126 """)
128add_newdoc_for_scalar_type('longlong', [],
129 """
130 Signed integer type, compatible with C ``long long``.
131 """)
133add_newdoc_for_scalar_type('ubyte', [],
134 """
135 Unsigned integer type, compatible with C ``unsigned char``.
136 """)
138add_newdoc_for_scalar_type('ushort', [],
139 """
140 Unsigned integer type, compatible with C ``unsigned short``.
141 """)
143add_newdoc_for_scalar_type('uintc', [],
144 """
145 Unsigned integer type, compatible with C ``unsigned int``.
146 """)
148add_newdoc_for_scalar_type('uint', [],
149 """
150 Unsigned integer type, compatible with C ``unsigned long``.
151 """)
153add_newdoc_for_scalar_type('ulonglong', [],
154 """
155 Signed integer type, compatible with C ``unsigned long long``.
156 """)
158add_newdoc_for_scalar_type('half', [],
159 """
160 Half-precision floating-point number type.
161 """)
163add_newdoc_for_scalar_type('single', [],
164 """
165 Single-precision floating-point number type, compatible with C ``float``.
166 """)
168add_newdoc_for_scalar_type('double', ['float_'],
169 """
170 Double-precision floating-point number type, compatible with Python `float`
171 and C ``double``.
172 """)
174add_newdoc_for_scalar_type('longdouble', ['longfloat'],
175 """
176 Extended-precision floating-point number type, compatible with C
177 ``long double`` but not necessarily with IEEE 754 quadruple-precision.
178 """)
180add_newdoc_for_scalar_type('csingle', ['singlecomplex'],
181 """
182 Complex number type composed of two single-precision floating-point
183 numbers.
184 """)
186add_newdoc_for_scalar_type('cdouble', ['cfloat', 'complex_'],
187 """
188 Complex number type composed of two double-precision floating-point
189 numbers, compatible with Python `complex`.
190 """)
192add_newdoc_for_scalar_type('clongdouble', ['clongfloat', 'longcomplex'],
193 """
194 Complex number type composed of two extended-precision floating-point
195 numbers.
196 """)
198add_newdoc_for_scalar_type('object_', [],
199 """
200 Any Python object.
201 """)
203add_newdoc_for_scalar_type('str_', ['unicode_'],
204 r"""
205 A unicode string.
207 This type strips trailing null codepoints.
209 >>> s = np.str_("abc\x00")
210 >>> s
211 'abc'
213 Unlike the builtin `str`, this supports the :ref:`python:bufferobjects`, exposing its
214 contents as UCS4:
216 >>> m = memoryview(np.str_("abc"))
217 >>> m.format
218 '3w'
219 >>> m.tobytes()
220 b'a\x00\x00\x00b\x00\x00\x00c\x00\x00\x00'
221 """)
223add_newdoc_for_scalar_type('bytes_', ['string_'],
224 r"""
225 A byte string.
227 When used in arrays, this type strips trailing null bytes.
228 """)
230add_newdoc_for_scalar_type('void', [],
231 r"""
232 np.void(length_or_data, /, dtype=None)
234 Create a new structured or unstructured void scalar.
236 Parameters
237 ----------
238 length_or_data : int, array-like, bytes-like, object
239 One of multiple meanings (see notes). The length or
240 bytes data of an unstructured void. Or alternatively,
241 the data to be stored in the new scalar when `dtype`
242 is provided.
243 This can be an array-like, in which case an array may
244 be returned.
245 dtype : dtype, optional
246 If provided the dtype of the new scalar. This dtype must
247 be "void" dtype (i.e. a structured or unstructured void,
248 see also :ref:`defining-structured-types`).
250 ..versionadded:: 1.24
252 Notes
253 -----
254 For historical reasons and because void scalars can represent both
255 arbitrary byte data and structured dtypes, the void constructor
256 has three calling conventions:
258 1. ``np.void(5)`` creates a ``dtype="V5"`` scalar filled with five
259 ``\0`` bytes. The 5 can be a Python or NumPy integer.
260 2. ``np.void(b"bytes-like")`` creates a void scalar from the byte string.
261 The dtype itemsize will match the byte string length, here ``"V10"``.
262 3. When a ``dtype=`` is passed the call is roughly the same as an
263 array creation. However, a void scalar rather than array is returned.
265 Please see the examples which show all three different conventions.
267 Examples
268 --------
269 >>> np.void(5)
270 void(b'\x00\x00\x00\x00\x00')
271 >>> np.void(b'abcd')
272 void(b'\x61\x62\x63\x64')
273 >>> np.void((5, 3.2, "eggs"), dtype="i,d,S5")
274 (5, 3.2, b'eggs') # looks like a tuple, but is `np.void`
275 >>> np.void(3, dtype=[('x', np.int8), ('y', np.int8)])
276 (3, 3) # looks like a tuple, but is `np.void`
278 """)
280add_newdoc_for_scalar_type('datetime64', [],
281 """
282 If created from a 64-bit integer, it represents an offset from
283 ``1970-01-01T00:00:00``.
284 If created from string, the string can be in ISO 8601 date
285 or datetime format.
287 >>> np.datetime64(10, 'Y')
288 numpy.datetime64('1980')
289 >>> np.datetime64('1980', 'Y')
290 numpy.datetime64('1980')
291 >>> np.datetime64(10, 'D')
292 numpy.datetime64('1970-01-11')
294 See :ref:`arrays.datetime` for more information.
295 """)
297add_newdoc_for_scalar_type('timedelta64', [],
298 """
299 A timedelta stored as a 64-bit integer.
301 See :ref:`arrays.datetime` for more information.
302 """)
304add_newdoc('numpy.core.numerictypes', "integer", ('is_integer',
305 """
306 integer.is_integer() -> bool
308 Return ``True`` if the number is finite with integral value.
310 .. versionadded:: 1.22
312 Examples
313 --------
314 >>> np.int64(-2).is_integer()
315 True
316 >>> np.uint32(5).is_integer()
317 True
318 """))
320# TODO: work out how to put this on the base class, np.floating
321for float_name in ('half', 'single', 'double', 'longdouble'):
322 add_newdoc('numpy.core.numerictypes', float_name, ('as_integer_ratio',
323 """
324 {ftype}.as_integer_ratio() -> (int, int)
326 Return a pair of integers, whose ratio is exactly equal to the original
327 floating point number, and with a positive denominator.
328 Raise `OverflowError` on infinities and a `ValueError` on NaNs.
330 >>> np.{ftype}(10.0).as_integer_ratio()
331 (10, 1)
332 >>> np.{ftype}(0.0).as_integer_ratio()
333 (0, 1)
334 >>> np.{ftype}(-.25).as_integer_ratio()
335 (-1, 4)
336 """.format(ftype=float_name)))
338 add_newdoc('numpy.core.numerictypes', float_name, ('is_integer',
339 f"""
340 {float_name}.is_integer() -> bool
342 Return ``True`` if the floating point number is finite with integral
343 value, and ``False`` otherwise.
345 .. versionadded:: 1.22
347 Examples
348 --------
349 >>> np.{float_name}(-2.0).is_integer()
350 True
351 >>> np.{float_name}(3.2).is_integer()
352 False
353 """))
355for int_name in ('int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32',
356 'int64', 'uint64', 'int64', 'uint64', 'int64', 'uint64'):
357 # Add negative examples for signed cases by checking typecode
358 add_newdoc('numpy.core.numerictypes', int_name, ('bit_count',
359 f"""
360 {int_name}.bit_count() -> int
362 Computes the number of 1-bits in the absolute value of the input.
363 Analogous to the builtin `int.bit_count` or ``popcount`` in C++.
365 Examples
366 --------
367 >>> np.{int_name}(127).bit_count()
368 7""" +
369 (f"""
370 >>> np.{int_name}(-127).bit_count()
371 7
372 """ if dtype(int_name).char.islower() else "")))