Hide keyboard shortcuts

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 

3 

4This module is designed so "from numerictypes import \\*" is safe. 

5Exported symbols include: 

6 

7 Dictionary with all registered number types (including aliases): 

8 typeDict 

9 

10 Type objects (not all will be available, depends on platform): 

11 see variable sctypes for which ones you have 

12 

13 Bit-width names 

14 

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 

20 

21 c-based names 

22 

23 bool_ 

24 

25 object_ 

26 

27 void, str_, unicode_ 

28 

29 byte, ubyte, 

30 short, ushort 

31 intc, uintc, 

32 intp, uintp, 

33 int_, uint, 

34 longlong, ulonglong, 

35 

36 single, csingle, 

37 float_, complex_, 

38 longfloat, clongfloat, 

39 

40 As part of the type-hierarchy: xx -- is bit-width 

41 

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) 

80 

81""" 

82import types as _types 

83import numbers 

84import warnings 

85 

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 

92 

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 ] 

100 

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) 

106 

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 

118 

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 

123 

124 

125# We use this later 

126generic = allTypes['generic'] 

127 

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'] 

135 

136@set_module('numpy') 

137def maximum_sctype(t): 

138 """ 

139 Return the scalar type of highest precision of the same kind as the input. 

140 

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`. 

146 

147 Returns 

148 ------- 

149 out : dtype 

150 The highest precision data type of the same kind (`dtype.kind`) as `t`. 

151 

152 See Also 

153 -------- 

154 obj2sctype, mintypecode, sctype2char 

155 dtype 

156 

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 

165 

166 >>> np.maximum_sctype(str) 

167 <class 'numpy.str_'> 

168 

169 >>> np.maximum_sctype('i2') 

170 <class 'numpy.int64'> 

171 >>> np.maximum_sctype('f4') 

172 <class 'numpy.float128'> # may vary 

173 

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 

184 

185 

186@set_module('numpy') 

187def issctype(rep): 

188 """ 

189 Determines whether the given object represents a scalar data-type. 

190 

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. 

196 

197 Returns 

198 ------- 

199 out : bool 

200 Boolean result of check whether `rep` is a scalar dtype. 

201 

202 See Also 

203 -------- 

204 issubsctype, issubdtype, obj2sctype, sctype2char 

205 

206 Examples 

207 -------- 

208 >>> np.issctype(np.int32) 

209 True 

210 >>> np.issctype(list) 

211 False 

212 >>> np.issctype(1.1) 

213 False 

214 

215 Strings are also a scalar type: 

216 

217 >>> np.issctype(np.dtype('str')) 

218 True 

219 

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 

230 

231 

232@set_module('numpy') 

233def obj2sctype(rep, default=None): 

234 """ 

235 Return the scalar dtype or NumPy equivalent of Python type of an object. 

236 

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. 

244 

245 Returns 

246 ------- 

247 dtype : dtype or Python type 

248 The data type of `rep`. 

249 

250 See Also 

251 -------- 

252 sctype2char, issctype, issubsctype, issubdtype, maximum_sctype 

253 

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'> 

262 

263 >>> np.obj2sctype(dict) 

264 <class 'numpy.object_'> 

265 >>> np.obj2sctype('string') 

266 

267 >>> np.obj2sctype(1, default=list) 

268 <class 'list'> 

269 

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 

284 

285 

286@set_module('numpy') 

287def issubclass_(arg1, arg2): 

288 """ 

289 Determine if a class is a subclass of a second class. 

290 

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. 

294 

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. 

302 

303 Returns 

304 ------- 

305 out : bool 

306 Whether `arg1` is a subclass of `arg2` or not. 

307 

308 See Also 

309 -------- 

310 issubsctype, issubdtype, issctype 

311 

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 

320 

321 """ 

322 try: 

323 return issubclass(arg1, arg2) 

324 except TypeError: 

325 return False 

326 

327 

328@set_module('numpy') 

329def issubsctype(arg1, arg2): 

330 """ 

331 Determine if the first argument is a subclass of the second argument. 

332 

333 Parameters 

334 ---------- 

335 arg1, arg2 : dtype or dtype specifier 

336 Data-types. 

337 

338 Returns 

339 ------- 

340 out : bool 

341 The result. 

342 

343 See Also 

344 -------- 

345 issctype, issubdtype, obj2sctype 

346 

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 

355 

356 """ 

357 return issubclass(obj2sctype(arg1), obj2sctype(arg2)) 

358 

359 

360@set_module('numpy') 

361def issubdtype(arg1, arg2): 

362 """ 

363 Returns True if first argument is a typecode lower/equal in type hierarchy. 

364 

365 Parameters 

366 ---------- 

367 arg1, arg2 : dtype_like 

368 dtype or string representing a typecode. 

369 

370 Returns 

371 ------- 

372 out : bool 

373 

374 See Also 

375 -------- 

376 issubsctype, issubclass_ 

377 numpy.core.numerictypes : Overview of numpy type hierarchy. 

378 

379 Examples 

380 -------- 

381 >>> np.issubdtype('S1', np.string_) 

382 True 

383 >>> np.issubdtype(np.float64, np.float32) 

384 False 

385 

386 """ 

387 if not issubclass_(arg1, generic): 

388 arg1 = dtype(arg1).type 

389 if not issubclass_(arg2, generic): 

390 arg2 = dtype(arg2).type 

391 

392 return issubclass(arg1, arg2) 

393 

394 

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. 

399 

400 Instances of `_typedict` can not be used as dictionaries directly, 

401 first they have to be populated. 

402 

403 """ 

404 

405 def __getitem__(self, obj): 

406 return dict.__getitem__(self, obj2sctype(obj)) 

407 

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 

423 

424_construct_lookups() 

425 

426 

427@set_module('numpy') 

428def sctype2char(sctype): 

429 """ 

430 Return the string representation of a scalar dtype. 

431 

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. 

438 

439 Returns 

440 ------- 

441 typechar : str 

442 The string character corresponding to the scalar type. 

443 

444 Raises 

445 ------ 

446 ValueError 

447 If `sctype` is an object for which the type can not be inferred. 

448 

449 See Also 

450 -------- 

451 obj2sctype, issctype, issubsctype, mintypecode 

452 

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 

462 

463 >>> x = np.array([1., 2-1.j]) 

464 >>> np.sctype2char(x) 

465 'D' 

466 >>> np.sctype2char(list) 

467 'O' 

468 

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 

477 

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) 

483 

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] 

491 

492ScalarType.extend(_concrete_types) 

493ScalarType = tuple(ScalarType) 

494 

495 

496# Now add the types we've determined to this module 

497for key in allTypes: 

498 globals()[key] = allTypes[key] 

499 __all__.append(key) 

500 

501del key 

502 

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'} 

512 

513# backwards compatibility --- deprecated name 

514typeDict = sctypeDict 

515typeNA = sctypeNA 

516 

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'] 

529 

530__test_types = '?'+typecodes['AllInteger'][:-2]+typecodes['AllFloat']+'O' 

531__len_test_types = len(__test_types) 

532 

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) 

543 

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 

559 

560def _register_types(): 

561 numbers.Integral.register(integer) 

562 numbers.Complex.register(inexact) 

563 numbers.Real.register(floating) 

564 numbers.Number.register(number) 

565 

566_register_types() 

567 

568 

569@set_module('numpy') 

570def find_common_type(array_types, scalar_types): 

571 """ 

572 Determine common type following standard coercion rules. 

573 

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. 

580 

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. 

588 

589 See Also 

590 -------- 

591 dtype, common_type, can_cast, mintypecode 

592 

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') 

599 

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: 

604 

605 >>> np.find_common_type([np.float32], [np.int64, np.float64]) 

606 dtype('float32') 

607 

608 Complex is of a different type, so it up-casts the float in the 

609 `array_types` argument: 

610 

611 >>> np.find_common_type([np.float32], [complex]) 

612 dtype('complex128') 

613 

614 Type specifier strings are convertible to dtypes and can therefore 

615 be used instead of dtypes: 

616 

617 >>> np.find_common_type(['f4', 'f4', 'i4'], ['c8']) 

618 dtype('complex128') 

619 

620 """ 

621 array_types = [dtype(x) for x in array_types] 

622 scalar_types = [dtype(x) for x in scalar_types] 

623 

624 maxa = _can_coerce_all(array_types) 

625 maxsc = _can_coerce_all(scalar_types) 

626 

627 if maxa is None: 

628 return maxsc 

629 

630 if maxsc is None: 

631 return maxa 

632 

633 try: 

634 index_a = _kind_list.index(maxa.kind) 

635 index_sc = _kind_list.index(maxsc.kind) 

636 except ValueError: 

637 return None 

638 

639 if index_sc > index_a: 

640 return _find_common_coerce(maxsc, maxa) 

641 else: 

642 return maxa