Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/numpy/core/numerictypes.py : 68%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1"""
2numerictypes: Define the numeric type objects
4This module is designed so "from numerictypes import \\*" is safe.
5Exported symbols include:
7 Dictionary with all registered number types (including aliases):
8 typeDict
10 Type objects (not all will be available, depends on platform):
11 see variable sctypes for which ones you have
13 Bit-width names
15 int8 int16 int32 int64 int128
16 uint8 uint16 uint32 uint64 uint128
17 float16 float32 float64 float96 float128 float256
18 complex32 complex64 complex128 complex192 complex256 complex512
19 datetime64 timedelta64
21 c-based names
23 bool_
25 object_
27 void, str_, unicode_
29 byte, ubyte,
30 short, ushort
31 intc, uintc,
32 intp, uintp,
33 int_, uint,
34 longlong, ulonglong,
36 single, csingle,
37 float_, complex_,
38 longfloat, clongfloat,
40 As part of the type-hierarchy: xx -- is bit-width
42 generic
43 +-> bool_ (kind=b)
44 +-> number
45 | +-> integer
46 | | +-> signedinteger (intxx) (kind=i)
47 | | | byte
48 | | | short
49 | | | intc
50 | | | intp int0
51 | | | int_
52 | | | longlong
53 | | \\-> unsignedinteger (uintxx) (kind=u)
54 | | ubyte
55 | | ushort
56 | | uintc
57 | | uintp uint0
58 | | uint_
59 | | ulonglong
60 | +-> inexact
61 | +-> floating (floatxx) (kind=f)
62 | | half
63 | | single
64 | | float_ (double)
65 | | longfloat
66 | \\-> complexfloating (complexxx) (kind=c)
67 | csingle (singlecomplex)
68 | complex_ (cfloat, cdouble)
69 | clongfloat (longcomplex)
70 +-> flexible
71 | +-> character
72 | | str_ (string_, bytes_) (kind=S) [Python 2]
73 | | unicode_ (kind=U) [Python 2]
74 | |
75 | | bytes_ (string_) (kind=S) [Python 3]
76 | | str_ (unicode_) (kind=U) [Python 3]
77 | |
78 | \\-> void (kind=V)
79 \\-> object_ (not used much) (kind=O)
81"""
82import types as _types
83import numbers
84import warnings
86from numpy.core.multiarray import (
87 typeinfo, ndarray, array, empty, dtype, datetime_data,
88 datetime_as_string, busday_offset, busday_count, is_busday,
89 busdaycalendar
90 )
91from numpy.core.overrides import set_module
93# we add more at the bottom
94__all__ = ['sctypeDict', 'sctypeNA', 'typeDict', 'typeNA', 'sctypes',
95 'ScalarType', 'obj2sctype', 'cast', 'nbytes', 'sctype2char',
96 'maximum_sctype', 'issctype', 'typecodes', 'find_common_type',
97 'issubdtype', 'datetime_data', 'datetime_as_string',
98 'busday_offset', 'busday_count', 'is_busday', 'busdaycalendar',
99 ]
101# we don't need all these imports, but we need to keep them for compatibility
102# for users using np.core.numerictypes.UPPER_TABLE
103from ._string_helpers import (
104 english_lower, english_upper, english_capitalize, LOWER_TABLE, UPPER_TABLE
105)
107from ._type_aliases import (
108 sctypeDict,
109 sctypeNA,
110 allTypes,
111 bitname,
112 sctypes,
113 _concrete_types,
114 _concrete_typeinfo,
115 _bits_of,
116)
117from ._dtype import _kind_name
119# we don't export these for import *, but we do want them accessible
120# as numerictypes.bool, etc.
121from builtins import bool, int, float, complex, object, str, bytes
122from numpy.compat import long, unicode
125# We use this later
126generic = allTypes['generic']
128genericTypeRank = ['bool', 'int8', 'uint8', 'int16', 'uint16',
129 'int32', 'uint32', 'int64', 'uint64', 'int128',
130 'uint128', 'float16',
131 'float32', 'float64', 'float80', 'float96', 'float128',
132 'float256',
133 'complex32', 'complex64', 'complex128', 'complex160',
134 'complex192', 'complex256', 'complex512', 'object']
136@set_module('numpy')
137def maximum_sctype(t):
138 """
139 Return the scalar type of highest precision of the same kind as the input.
141 Parameters
142 ----------
143 t : dtype or dtype specifier
144 The input data type. This can be a `dtype` object or an object that
145 is convertible to a `dtype`.
147 Returns
148 -------
149 out : dtype
150 The highest precision data type of the same kind (`dtype.kind`) as `t`.
152 See Also
153 --------
154 obj2sctype, mintypecode, sctype2char
155 dtype
157 Examples
158 --------
159 >>> np.maximum_sctype(int)
160 <class 'numpy.int64'>
161 >>> np.maximum_sctype(np.uint8)
162 <class 'numpy.uint64'>
163 >>> np.maximum_sctype(complex)
164 <class 'numpy.complex256'> # may vary
166 >>> np.maximum_sctype(str)
167 <class 'numpy.str_'>
169 >>> np.maximum_sctype('i2')
170 <class 'numpy.int64'>
171 >>> np.maximum_sctype('f4')
172 <class 'numpy.float128'> # may vary
174 """
175 g = obj2sctype(t)
176 if g is None:
177 return t
178 t = g
179 base = _kind_name(dtype(t))
180 if base in sctypes:
181 return sctypes[base][-1]
182 else:
183 return t
186@set_module('numpy')
187def issctype(rep):
188 """
189 Determines whether the given object represents a scalar data-type.
191 Parameters
192 ----------
193 rep : any
194 If `rep` is an instance of a scalar dtype, True is returned. If not,
195 False is returned.
197 Returns
198 -------
199 out : bool
200 Boolean result of check whether `rep` is a scalar dtype.
202 See Also
203 --------
204 issubsctype, issubdtype, obj2sctype, sctype2char
206 Examples
207 --------
208 >>> np.issctype(np.int32)
209 True
210 >>> np.issctype(list)
211 False
212 >>> np.issctype(1.1)
213 False
215 Strings are also a scalar type:
217 >>> np.issctype(np.dtype('str'))
218 True
220 """
221 if not isinstance(rep, (type, dtype)):
222 return False
223 try:
224 res = obj2sctype(rep)
225 if res and res != object_:
226 return True
227 return False
228 except Exception:
229 return False
232@set_module('numpy')
233def obj2sctype(rep, default=None):
234 """
235 Return the scalar dtype or NumPy equivalent of Python type of an object.
237 Parameters
238 ----------
239 rep : any
240 The object of which the type is returned.
241 default : any, optional
242 If given, this is returned for objects whose types can not be
243 determined. If not given, None is returned for those objects.
245 Returns
246 -------
247 dtype : dtype or Python type
248 The data type of `rep`.
250 See Also
251 --------
252 sctype2char, issctype, issubsctype, issubdtype, maximum_sctype
254 Examples
255 --------
256 >>> np.obj2sctype(np.int32)
257 <class 'numpy.int32'>
258 >>> np.obj2sctype(np.array([1., 2.]))
259 <class 'numpy.float64'>
260 >>> np.obj2sctype(np.array([1.j]))
261 <class 'numpy.complex128'>
263 >>> np.obj2sctype(dict)
264 <class 'numpy.object_'>
265 >>> np.obj2sctype('string')
267 >>> np.obj2sctype(1, default=list)
268 <class 'list'>
270 """
271 # prevent abstract classes being upcast
272 if isinstance(rep, type) and issubclass(rep, generic):
273 return rep
274 # extract dtype from arrays
275 if isinstance(rep, ndarray):
276 return rep.dtype.type
277 # fall back on dtype to convert
278 try:
279 res = dtype(rep)
280 except Exception:
281 return default
282 else:
283 return res.type
286@set_module('numpy')
287def issubclass_(arg1, arg2):
288 """
289 Determine if a class is a subclass of a second class.
291 `issubclass_` is equivalent to the Python built-in ``issubclass``,
292 except that it returns False instead of raising a TypeError if one
293 of the arguments is not a class.
295 Parameters
296 ----------
297 arg1 : class
298 Input class. True is returned if `arg1` is a subclass of `arg2`.
299 arg2 : class or tuple of classes.
300 Input class. If a tuple of classes, True is returned if `arg1` is a
301 subclass of any of the tuple elements.
303 Returns
304 -------
305 out : bool
306 Whether `arg1` is a subclass of `arg2` or not.
308 See Also
309 --------
310 issubsctype, issubdtype, issctype
312 Examples
313 --------
314 >>> np.issubclass_(np.int32, int)
315 False
316 >>> np.issubclass_(np.int32, float)
317 False
318 >>> np.issubclass_(np.float64, float)
319 True
321 """
322 try:
323 return issubclass(arg1, arg2)
324 except TypeError:
325 return False
328@set_module('numpy')
329def issubsctype(arg1, arg2):
330 """
331 Determine if the first argument is a subclass of the second argument.
333 Parameters
334 ----------
335 arg1, arg2 : dtype or dtype specifier
336 Data-types.
338 Returns
339 -------
340 out : bool
341 The result.
343 See Also
344 --------
345 issctype, issubdtype, obj2sctype
347 Examples
348 --------
349 >>> np.issubsctype('S8', str)
350 False
351 >>> np.issubsctype(np.array([1]), int)
352 True
353 >>> np.issubsctype(np.array([1]), float)
354 False
356 """
357 return issubclass(obj2sctype(arg1), obj2sctype(arg2))
360@set_module('numpy')
361def issubdtype(arg1, arg2):
362 """
363 Returns True if first argument is a typecode lower/equal in type hierarchy.
365 Parameters
366 ----------
367 arg1, arg2 : dtype_like
368 dtype or string representing a typecode.
370 Returns
371 -------
372 out : bool
374 See Also
375 --------
376 issubsctype, issubclass_
377 numpy.core.numerictypes : Overview of numpy type hierarchy.
379 Examples
380 --------
381 >>> np.issubdtype('S1', np.string_)
382 True
383 >>> np.issubdtype(np.float64, np.float32)
384 False
386 """
387 if not issubclass_(arg1, generic):
388 arg1 = dtype(arg1).type
389 if not issubclass_(arg2, generic):
390 arg2 = dtype(arg2).type
392 return issubclass(arg1, arg2)
395# This dictionary allows look up based on any alias for an array data-type
396class _typedict(dict):
397 """
398 Base object for a dictionary for look-up with any alias for an array dtype.
400 Instances of `_typedict` can not be used as dictionaries directly,
401 first they have to be populated.
403 """
405 def __getitem__(self, obj):
406 return dict.__getitem__(self, obj2sctype(obj))
408nbytes = _typedict()
409_alignment = _typedict()
410_maxvals = _typedict()
411_minvals = _typedict()
412def _construct_lookups():
413 for name, info in _concrete_typeinfo.items():
414 obj = info.type
415 nbytes[obj] = info.bits // 8
416 _alignment[obj] = info.alignment
417 if len(info) > 5:
418 _maxvals[obj] = info.max
419 _minvals[obj] = info.min
420 else:
421 _maxvals[obj] = None
422 _minvals[obj] = None
424_construct_lookups()
427@set_module('numpy')
428def sctype2char(sctype):
429 """
430 Return the string representation of a scalar dtype.
432 Parameters
433 ----------
434 sctype : scalar dtype or object
435 If a scalar dtype, the corresponding string character is
436 returned. If an object, `sctype2char` tries to infer its scalar type
437 and then return the corresponding string character.
439 Returns
440 -------
441 typechar : str
442 The string character corresponding to the scalar type.
444 Raises
445 ------
446 ValueError
447 If `sctype` is an object for which the type can not be inferred.
449 See Also
450 --------
451 obj2sctype, issctype, issubsctype, mintypecode
453 Examples
454 --------
455 >>> for sctype in [np.int32, np.double, np.complex_, np.string_, np.ndarray]:
456 ... print(np.sctype2char(sctype))
457 l # may vary
458 d
459 D
460 S
461 O
463 >>> x = np.array([1., 2-1.j])
464 >>> np.sctype2char(x)
465 'D'
466 >>> np.sctype2char(list)
467 'O'
469 """
470 sctype = obj2sctype(sctype)
471 if sctype is None:
472 raise ValueError("unrecognized type")
473 if sctype not in _concrete_types:
474 # for compatibility
475 raise KeyError(sctype)
476 return dtype(sctype).char
478# Create dictionary of casting functions that wrap sequences
479# indexed by type or type character
480cast = _typedict()
481for key in _concrete_types:
482 cast[key] = lambda x, k=key: array(x, copy=False).astype(k)
484try:
485 ScalarType = [_types.IntType, _types.FloatType, _types.ComplexType,
486 _types.LongType, _types.BooleanType,
487 _types.StringType, _types.UnicodeType, _types.BufferType]
488except AttributeError:
489 # Py3K
490 ScalarType = [int, float, complex, int, bool, bytes, str, memoryview]
492ScalarType.extend(_concrete_types)
493ScalarType = tuple(ScalarType)
496# Now add the types we've determined to this module
497for key in allTypes:
498 globals()[key] = allTypes[key]
499 __all__.append(key)
501del key
503typecodes = {'Character':'c',
504 'Integer':'bhilqp',
505 'UnsignedInteger':'BHILQP',
506 'Float':'efdg',
507 'Complex':'FDG',
508 'AllInteger':'bBhHiIlLqQpP',
509 'AllFloat':'efdgFDG',
510 'Datetime': 'Mm',
511 'All':'?bhilqpBHILQPefdgFDGSUVOMm'}
513# backwards compatibility --- deprecated name
514typeDict = sctypeDict
515typeNA = sctypeNA
517# b -> boolean
518# u -> unsigned integer
519# i -> signed integer
520# f -> floating point
521# c -> complex
522# M -> datetime
523# m -> timedelta
524# S -> string
525# U -> Unicode string
526# V -> record
527# O -> Python object
528_kind_list = ['b', 'u', 'i', 'f', 'c', 'S', 'U', 'V', 'O', 'M', 'm']
530__test_types = '?'+typecodes['AllInteger'][:-2]+typecodes['AllFloat']+'O'
531__len_test_types = len(__test_types)
533# Keep incrementing until a common type both can be coerced to
534# is found. Otherwise, return None
535def _find_common_coerce(a, b):
536 if a > b:
537 return a
538 try:
539 thisind = __test_types.index(a.char)
540 except ValueError:
541 return None
542 return _can_coerce_all([a, b], start=thisind)
544# Find a data-type that all data-types in a list can be coerced to
545def _can_coerce_all(dtypelist, start=0):
546 N = len(dtypelist)
547 if N == 0:
548 return None
549 if N == 1:
550 return dtypelist[0]
551 thisind = start
552 while thisind < __len_test_types:
553 newdtype = dtype(__test_types[thisind])
554 numcoerce = len([x for x in dtypelist if newdtype >= x])
555 if numcoerce == N:
556 return newdtype
557 thisind += 1
558 return None
560def _register_types():
561 numbers.Integral.register(integer)
562 numbers.Complex.register(inexact)
563 numbers.Real.register(floating)
564 numbers.Number.register(number)
566_register_types()
569@set_module('numpy')
570def find_common_type(array_types, scalar_types):
571 """
572 Determine common type following standard coercion rules.
574 Parameters
575 ----------
576 array_types : sequence
577 A list of dtypes or dtype convertible objects representing arrays.
578 scalar_types : sequence
579 A list of dtypes or dtype convertible objects representing scalars.
581 Returns
582 -------
583 datatype : dtype
584 The common data type, which is the maximum of `array_types` ignoring
585 `scalar_types`, unless the maximum of `scalar_types` is of a
586 different kind (`dtype.kind`). If the kind is not understood, then
587 None is returned.
589 See Also
590 --------
591 dtype, common_type, can_cast, mintypecode
593 Examples
594 --------
595 >>> np.find_common_type([], [np.int64, np.float32, complex])
596 dtype('complex128')
597 >>> np.find_common_type([np.int64, np.float32], [])
598 dtype('float64')
600 The standard casting rules ensure that a scalar cannot up-cast an
601 array unless the scalar is of a fundamentally different kind of data
602 (i.e. under a different hierarchy in the data type hierarchy) then
603 the array:
605 >>> np.find_common_type([np.float32], [np.int64, np.float64])
606 dtype('float32')
608 Complex is of a different type, so it up-casts the float in the
609 `array_types` argument:
611 >>> np.find_common_type([np.float32], [complex])
612 dtype('complex128')
614 Type specifier strings are convertible to dtypes and can therefore
615 be used instead of dtypes:
617 >>> np.find_common_type(['f4', 'f4', 'i4'], ['c8'])
618 dtype('complex128')
620 """
621 array_types = [dtype(x) for x in array_types]
622 scalar_types = [dtype(x) for x in scalar_types]
624 maxa = _can_coerce_all(array_types)
625 maxsc = _can_coerce_all(scalar_types)
627 if maxa is None:
628 return maxsc
630 if maxsc is None:
631 return maxa
633 try:
634 index_a = _kind_list.index(maxa.kind)
635 index_sc = _kind_list.index(maxsc.kind)
636 except ValueError:
637 return None
639 if index_sc > index_a:
640 return _find_common_coerce(maxsc, maxa)
641 else:
642 return maxa