codekingpro/portable-devtools
115k
1"""
2Array API Inspection namespace
3
4This is the namespace for inspection functions as defined by the array API
5standard. See
6https://data-apis.org/array-api/latest/API_specification/inspection.html for
7more details.
8
9"""
10from numpy._core import (
11 bool,
12 complex64,
13 complex128,
14 dtype,
15 float32,
16 float64,
17 int8,
18 int16,
19 int32,
20 int64,
21 intp,
22 uint8,
23 uint16,
24 uint32,
25 uint64,
26)
27from numpy._utils import set_module
28
29
30@set_module('numpy')
31class __array_namespace_info__:
32 """
33 Get the array API inspection namespace for NumPy.
34
35 The array API inspection namespace defines the following functions:
36
37 - capabilities()
38 - default_device()
39 - default_dtypes()
40 - dtypes()
41 - devices()
42
43 See
44 https://data-apis.org/array-api/latest/API_specification/inspection.html
45 for more details.
46
47 Returns
48 -------
49 info : ModuleType
50 The array API inspection namespace for NumPy.
51
52 Examples
53 --------
54 >>> info = np.__array_namespace_info__()
55 >>> info.default_dtypes()
56 {'real floating': numpy.float64,
57 'complex floating': numpy.complex128,
58 'integral': numpy.int64,
59 'indexing': numpy.int64}
60
61 """
62
63 def capabilities(self):
64 """
65 Return a dictionary of array API library capabilities.
66
67 The resulting dictionary has the following keys:
68
69 - **"boolean indexing"**: boolean indicating whether an array library
70 supports boolean indexing. Always ``True`` for NumPy.
71
72 - **"data-dependent shapes"**: boolean indicating whether an array
73 library supports data-dependent output shapes. Always ``True`` for
74 NumPy.
75
76 See
77 https://data-apis.org/array-api/latest/API_specification/generated/array_api.info.capabilities.html
78 for more details.
79
80 See Also
81 --------
82 __array_namespace_info__.default_device,
83 __array_namespace_info__.default_dtypes,
84 __array_namespace_info__.dtypes,
85 __array_namespace_info__.devices
86
87 Returns
88 -------
89 capabilities : dict
90 A dictionary of array API library capabilities.
91
92 Examples
93 --------
94 >>> info = np.__array_namespace_info__()
95 >>> info.capabilities()
96 {'boolean indexing': True,
97 'data-dependent shapes': True,
98 'max dimensions': 64}
99
100 """
101 return {
102 "boolean indexing": True,
103 "data-dependent shapes": True,
104 "max dimensions": 64,
105 }
106
107 def default_device(self):
108 """
109 The default device used for new NumPy arrays.
110
111 For NumPy, this always returns ``'cpu'``.
112
113 See Also
114 --------
115 __array_namespace_info__.capabilities,
116 __array_namespace_info__.default_dtypes,
117 __array_namespace_info__.dtypes,
118 __array_namespace_info__.devices
119
120 Returns
121 -------
122 device : str
123 The default device used for new NumPy arrays.
124
125 Examples
126 --------
127 >>> info = np.__array_namespace_info__()
128 >>> info.default_device()
129 'cpu'
130
131 """
132 return "cpu"
133
134 def default_dtypes(self, *, device=None):
135 """
136 The default data types used for new NumPy arrays.
137
138 For NumPy, this always returns the following dictionary:
139
140 - **"real floating"**: ``numpy.float64``
141 - **"complex floating"**: ``numpy.complex128``
142 - **"integral"**: ``numpy.intp``
143 - **"indexing"**: ``numpy.intp``
144
145 Parameters
146 ----------
147 device : str, optional
148 The device to get the default data types for. For NumPy, only
149 ``'cpu'`` is allowed.
150
151 Returns
152 -------
153 dtypes : dict
154 A dictionary describing the default data types used for new NumPy
155 arrays.
156
157 See Also
158 --------
159 __array_namespace_info__.capabilities,
160 __array_namespace_info__.default_device,
161 __array_namespace_info__.dtypes,
162 __array_namespace_info__.devices
163
164 Examples
165 --------
166 >>> info = np.__array_namespace_info__()
167 >>> info.default_dtypes()
168 {'real floating': numpy.float64,
169 'complex floating': numpy.complex128,
170 'integral': numpy.int64,
171 'indexing': numpy.int64}
172
173 """
174 if device not in ["cpu", None]:
175 raise ValueError(
176 'Device not understood. Only "cpu" is allowed, but received:'
177 f' {device}'
178 )
179 return {
180 "real floating": dtype(float64),
181 "complex floating": dtype(complex128),
182 "integral": dtype(intp),
183 "indexing": dtype(intp),
184 }
185
186 def dtypes(self, *, device=None, kind=None):
187 """
188 The array API data types supported by NumPy.
189
190 Note that this function only returns data types that are defined by
191 the array API.
192
193 Parameters
194 ----------
195 device : str, optional
196 The device to get the data types for. For NumPy, only ``'cpu'`` is
197 allowed.
198 kind : str or tuple of str, optional
199 The kind of data types to return. If ``None``, all data types are
200 returned. If a string, only data types of that kind are returned.
201 If a tuple, a dictionary containing the union of the given kinds
202 is returned. The following kinds are supported:
203
204 - ``'bool'``: boolean data types (i.e., ``bool``).
205 - ``'signed integer'``: signed integer data types (i.e., ``int8``,
206 ``int16``, ``int32``, ``int64``).
207 - ``'unsigned integer'``: unsigned integer data types (i.e.,
208 ``uint8``, ``uint16``, ``uint32``, ``uint64``).
209 - ``'integral'``: integer data types. Shorthand for ``('signed
210 integer', 'unsigned integer')``.
211 - ``'real floating'``: real-valued floating-point data types
212 (i.e., ``float32``, ``float64``).
213 - ``'complex floating'``: complex floating-point data types (i.e.,
214 ``complex64``, ``complex128``).
215 - ``'numeric'``: numeric data types. Shorthand for ``('integral',
216 'real floating', 'complex floating')``.
217
218 Returns
219 -------
220 dtypes : dict
221 A dictionary mapping the names of data types to the corresponding
222 NumPy data types.
223
224 See Also
225 --------
226 __array_namespace_info__.capabilities,
227 __array_namespace_info__.default_device,
228 __array_namespace_info__.default_dtypes,
229 __array_namespace_info__.devices
230
231 Examples
232 --------
233 >>> info = np.__array_namespace_info__()
234 >>> info.dtypes(kind='signed integer')
235 {'int8': numpy.int8,
236 'int16': numpy.int16,
237 'int32': numpy.int32,
238 'int64': numpy.int64}
239
240 """
241 if device not in ["cpu", None]:
242 raise ValueError(
243 'Device not understood. Only "cpu" is allowed, but received:'
244 f' {device}'
245 )
246 if kind is None:
247 return {
248 "bool": dtype(bool),
249 "int8": dtype(int8),
250 "int16": dtype(int16),
251 "int32": dtype(int32),
252 "int64": dtype(int64),
253 "uint8": dtype(uint8),
254 "uint16": dtype(uint16),
255 "uint32": dtype(uint32),
256 "uint64": dtype(uint64),
257 "float32": dtype(float32),
258 "float64": dtype(float64),
259 "complex64": dtype(complex64),
260 "complex128": dtype(complex128),
261 }
262 if kind == "bool":
263 return {"bool": bool}
264 if kind == "signed integer":
265 return {
266 "int8": dtype(int8),
267 "int16": dtype(int16),
268 "int32": dtype(int32),
269 "int64": dtype(int64),
270 }
271 if kind == "unsigned integer":
272 return {
273 "uint8": dtype(uint8),
274 "uint16": dtype(uint16),
275 "uint32": dtype(uint32),
276 "uint64": dtype(uint64),
277 }
278 if kind == "integral":
279 return {
280 "int8": dtype(int8),
281 "int16": dtype(int16),
282 "int32": dtype(int32),
283 "int64": dtype(int64),
284 "uint8": dtype(uint8),
285 "uint16": dtype(uint16),
286 "uint32": dtype(uint32),
287 "uint64": dtype(uint64),
288 }
289 if kind == "real floating":
290 return {
291 "float32": dtype(float32),
292 "float64": dtype(float64),
293 }
294 if kind == "complex floating":
295 return {
296 "complex64": dtype(complex64),
297 "complex128": dtype(complex128),
298 }
299 if kind == "numeric":
300 return {
301 "int8": dtype(int8),
302 "int16": dtype(int16),
303 "int32": dtype(int32),
304 "int64": dtype(int64),
305 "uint8": dtype(uint8),
306 "uint16": dtype(uint16),
307 "uint32": dtype(uint32),
308 "uint64": dtype(uint64),
309 "float32": dtype(float32),
310 "float64": dtype(float64),
311 "complex64": dtype(complex64),
312 "complex128": dtype(complex128),
313 }
314 if isinstance(kind, tuple):
315 res = {}
316 for k in kind:
317 res.update(self.dtypes(kind=k))
318 return res
319 raise ValueError(f"unsupported kind: {kind!r}")
320
321 def devices(self):
322 """
323 The devices supported by NumPy.
324
325 For NumPy, this always returns ``['cpu']``.
326
327 Returns
328 -------
329 devices : list of str
330 The devices supported by NumPy.
331
332 See Also
333 --------
334 __array_namespace_info__.capabilities,
335 __array_namespace_info__.default_device,
336 __array_namespace_info__.default_dtypes,
337 __array_namespace_info__.dtypes
338
339 Examples
340 --------
341 >>> info = np.__array_namespace_info__()
342 >>> info.devices()
343 ['cpu']
344
345 """
346 return ["cpu"]
347