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""" common type operations """ 

2from typing import Any, Callable, Union 

3import warnings 

4 

5import numpy as np 

6 

7from pandas._libs import algos, lib 

8from pandas._libs.tslibs import conversion 

9from pandas._typing import ArrayLike 

10 

11from pandas.core.dtypes.dtypes import ( 

12 CategoricalDtype, 

13 DatetimeTZDtype, 

14 ExtensionDtype, 

15 IntervalDtype, 

16 PeriodDtype, 

17 registry, 

18) 

19from pandas.core.dtypes.generic import ( 

20 ABCCategorical, 

21 ABCDatetimeIndex, 

22 ABCIndexClass, 

23 ABCPeriodArray, 

24 ABCPeriodIndex, 

25 ABCSeries, 

26) 

27from pandas.core.dtypes.inference import ( # noqa:F401 

28 is_array_like, 

29 is_bool, 

30 is_complex, 

31 is_decimal, 

32 is_dict_like, 

33 is_file_like, 

34 is_float, 

35 is_hashable, 

36 is_integer, 

37 is_interval, 

38 is_iterator, 

39 is_list_like, 

40 is_named_tuple, 

41 is_nested_list_like, 

42 is_number, 

43 is_re, 

44 is_re_compilable, 

45 is_scalar, 

46 is_sequence, 

47) 

48 

49_POSSIBLY_CAST_DTYPES = { 

50 np.dtype(t).name 

51 for t in [ 

52 "O", 

53 "int8", 

54 "uint8", 

55 "int16", 

56 "uint16", 

57 "int32", 

58 "uint32", 

59 "int64", 

60 "uint64", 

61 ] 

62} 

63 

64_NS_DTYPE = conversion.NS_DTYPE 

65_TD_DTYPE = conversion.TD_DTYPE 

66_INT64_DTYPE = np.dtype(np.int64) 

67 

68# oh the troubles to reduce import time 

69_is_scipy_sparse = None 

70 

71ensure_float64 = algos.ensure_float64 

72ensure_float32 = algos.ensure_float32 

73 

74_ensure_datetime64ns = conversion.ensure_datetime64ns 

75_ensure_timedelta64ns = conversion.ensure_timedelta64ns 

76 

77 

78def ensure_float(arr): 

79 """ 

80 Ensure that an array object has a float dtype if possible. 

81 

82 Parameters 

83 ---------- 

84 arr : array-like 

85 The array whose data type we want to enforce as float. 

86 

87 Returns 

88 ------- 

89 float_arr : The original array cast to the float dtype if 

90 possible. Otherwise, the original array is returned. 

91 """ 

92 

93 if issubclass(arr.dtype.type, (np.integer, np.bool_)): 

94 arr = arr.astype(float) 

95 return arr 

96 

97 

98ensure_uint64 = algos.ensure_uint64 

99ensure_int64 = algos.ensure_int64 

100ensure_int32 = algos.ensure_int32 

101ensure_int16 = algos.ensure_int16 

102ensure_int8 = algos.ensure_int8 

103ensure_platform_int = algos.ensure_platform_int 

104ensure_object = algos.ensure_object 

105 

106 

107def ensure_str(value: Union[bytes, Any]) -> str: 

108 """ 

109 Ensure that bytes and non-strings get converted into ``str`` objects. 

110 """ 

111 if isinstance(value, bytes): 

112 value = value.decode("utf-8") 

113 elif not isinstance(value, str): 

114 value = str(value) 

115 return value 

116 

117 

118def ensure_categorical(arr): 

119 """ 

120 Ensure that an array-like object is a Categorical (if not already). 

121 

122 Parameters 

123 ---------- 

124 arr : array-like 

125 The array that we want to convert into a Categorical. 

126 

127 Returns 

128 ------- 

129 cat_arr : The original array cast as a Categorical. If it already 

130 is a Categorical, we return as is. 

131 """ 

132 

133 if not is_categorical(arr): 

134 from pandas import Categorical 

135 

136 arr = Categorical(arr) 

137 return arr 

138 

139 

140def ensure_int_or_float(arr: ArrayLike, copy: bool = False) -> np.array: 

141 """ 

142 Ensure that an dtype array of some integer dtype 

143 has an int64 dtype if possible. 

144 If it's not possible, potentially because of overflow, 

145 convert the array to float64 instead. 

146 

147 Parameters 

148 ---------- 

149 arr : array-like 

150 The array whose data type we want to enforce. 

151 copy: bool 

152 Whether to copy the original array or reuse 

153 it in place, if possible. 

154 

155 Returns 

156 ------- 

157 out_arr : The input array cast as int64 if 

158 possible without overflow. 

159 Otherwise the input array cast to float64. 

160 

161 Notes 

162 ----- 

163 If the array is explicitly of type uint64 the type 

164 will remain unchanged. 

165 """ 

166 # TODO: GH27506 potential bug with ExtensionArrays 

167 try: 

168 return arr.astype("int64", copy=copy, casting="safe") # type: ignore 

169 except TypeError: 

170 pass 

171 try: 

172 return arr.astype("uint64", copy=copy, casting="safe") # type: ignore 

173 except TypeError: 

174 if is_extension_array_dtype(arr.dtype): 

175 return arr.to_numpy(dtype="float64", na_value=np.nan) 

176 return arr.astype("float64", copy=copy) 

177 

178 

179def ensure_python_int(value: Union[int, np.integer]) -> int: 

180 """ 

181 Ensure that a value is a python int. 

182 

183 Parameters 

184 ---------- 

185 value: int or numpy.integer 

186 

187 Returns 

188 ------- 

189 int 

190 

191 Raises 

192 ------ 

193 TypeError: if the value isn't an int or can't be converted to one. 

194 """ 

195 if not is_scalar(value): 

196 raise TypeError(f"Value needs to be a scalar value, was type {type(value)}") 

197 msg = "Wrong type {} for value {}" 

198 try: 

199 new_value = int(value) 

200 assert new_value == value 

201 except (TypeError, ValueError, AssertionError): 

202 raise TypeError(msg.format(type(value), value)) 

203 return new_value 

204 

205 

206def classes(*klasses) -> Callable: 

207 """ evaluate if the tipo is a subclass of the klasses """ 

208 return lambda tipo: issubclass(tipo, klasses) 

209 

210 

211def classes_and_not_datetimelike(*klasses) -> Callable: 

212 """ 

213 evaluate if the tipo is a subclass of the klasses 

214 and not a datetimelike 

215 """ 

216 return lambda tipo: ( 

217 issubclass(tipo, klasses) 

218 and not issubclass(tipo, (np.datetime64, np.timedelta64)) 

219 ) 

220 

221 

222def is_object_dtype(arr_or_dtype) -> bool: 

223 """ 

224 Check whether an array-like or dtype is of the object dtype. 

225 

226 Parameters 

227 ---------- 

228 arr_or_dtype : array-like 

229 The array-like or dtype to check. 

230 

231 Returns 

232 ------- 

233 boolean 

234 Whether or not the array-like or dtype is of the object dtype. 

235 

236 Examples 

237 -------- 

238 >>> is_object_dtype(object) 

239 True 

240 >>> is_object_dtype(int) 

241 False 

242 >>> is_object_dtype(np.array([], dtype=object)) 

243 True 

244 >>> is_object_dtype(np.array([], dtype=int)) 

245 False 

246 >>> is_object_dtype([1, 2, 3]) 

247 False 

248 """ 

249 return _is_dtype_type(arr_or_dtype, classes(np.object_)) 

250 

251 

252def is_sparse(arr) -> bool: 

253 """ 

254 Check whether an array-like is a 1-D pandas sparse array. 

255 

256 Check that the one-dimensional array-like is a pandas sparse array. 

257 Returns True if it is a pandas sparse array, not another type of 

258 sparse array. 

259 

260 Parameters 

261 ---------- 

262 arr : array-like 

263 Array-like to check. 

264 

265 Returns 

266 ------- 

267 bool 

268 Whether or not the array-like is a pandas sparse array. 

269 

270 Examples 

271 -------- 

272 Returns `True` if the parameter is a 1-D pandas sparse array. 

273 

274 >>> is_sparse(pd.arrays.SparseArray([0, 0, 1, 0])) 

275 True 

276 >>> is_sparse(pd.Series(pd.arrays.SparseArray([0, 0, 1, 0]))) 

277 True 

278 

279 Returns `False` if the parameter is not sparse. 

280 

281 >>> is_sparse(np.array([0, 0, 1, 0])) 

282 False 

283 >>> is_sparse(pd.Series([0, 1, 0, 0])) 

284 False 

285 

286 Returns `False` if the parameter is not a pandas sparse array. 

287 

288 >>> from scipy.sparse import bsr_matrix 

289 >>> is_sparse(bsr_matrix([0, 1, 0, 0])) 

290 False 

291 

292 Returns `False` if the parameter has more than one dimension. 

293 """ 

294 from pandas.core.arrays.sparse import SparseDtype 

295 

296 dtype = getattr(arr, "dtype", arr) 

297 return isinstance(dtype, SparseDtype) 

298 

299 

300def is_scipy_sparse(arr) -> bool: 

301 """ 

302 Check whether an array-like is a scipy.sparse.spmatrix instance. 

303 

304 Parameters 

305 ---------- 

306 arr : array-like 

307 The array-like to check. 

308 

309 Returns 

310 ------- 

311 boolean 

312 Whether or not the array-like is a scipy.sparse.spmatrix instance. 

313 

314 Notes 

315 ----- 

316 If scipy is not installed, this function will always return False. 

317 

318 Examples 

319 -------- 

320 >>> from scipy.sparse import bsr_matrix 

321 >>> is_scipy_sparse(bsr_matrix([1, 2, 3])) 

322 True 

323 >>> is_scipy_sparse(pd.arrays.SparseArray([1, 2, 3])) 

324 False 

325 """ 

326 

327 global _is_scipy_sparse 

328 

329 if _is_scipy_sparse is None: 

330 try: 

331 from scipy.sparse import issparse as _is_scipy_sparse 

332 except ImportError: 

333 _is_scipy_sparse = lambda _: False 

334 

335 assert _is_scipy_sparse is not None 

336 return _is_scipy_sparse(arr) 

337 

338 

339def is_categorical(arr) -> bool: 

340 """ 

341 Check whether an array-like is a Categorical instance. 

342 

343 Parameters 

344 ---------- 

345 arr : array-like 

346 The array-like to check. 

347 

348 Returns 

349 ------- 

350 boolean 

351 Whether or not the array-like is of a Categorical instance. 

352 

353 Examples 

354 -------- 

355 >>> is_categorical([1, 2, 3]) 

356 False 

357 

358 Categoricals, Series Categoricals, and CategoricalIndex will return True. 

359 

360 >>> cat = pd.Categorical([1, 2, 3]) 

361 >>> is_categorical(cat) 

362 True 

363 >>> is_categorical(pd.Series(cat)) 

364 True 

365 >>> is_categorical(pd.CategoricalIndex([1, 2, 3])) 

366 True 

367 """ 

368 

369 return isinstance(arr, ABCCategorical) or is_categorical_dtype(arr) 

370 

371 

372def is_datetime64_dtype(arr_or_dtype) -> bool: 

373 """ 

374 Check whether an array-like or dtype is of the datetime64 dtype. 

375 

376 Parameters 

377 ---------- 

378 arr_or_dtype : array-like 

379 The array-like or dtype to check. 

380 

381 Returns 

382 ------- 

383 boolean 

384 Whether or not the array-like or dtype is of the datetime64 dtype. 

385 

386 Examples 

387 -------- 

388 >>> is_datetime64_dtype(object) 

389 False 

390 >>> is_datetime64_dtype(np.datetime64) 

391 True 

392 >>> is_datetime64_dtype(np.array([], dtype=int)) 

393 False 

394 >>> is_datetime64_dtype(np.array([], dtype=np.datetime64)) 

395 True 

396 >>> is_datetime64_dtype([1, 2, 3]) 

397 False 

398 """ 

399 

400 return _is_dtype_type(arr_or_dtype, classes(np.datetime64)) 

401 

402 

403def is_datetime64tz_dtype(arr_or_dtype) -> bool: 

404 """ 

405 Check whether an array-like or dtype is of a DatetimeTZDtype dtype. 

406 

407 Parameters 

408 ---------- 

409 arr_or_dtype : array-like 

410 The array-like or dtype to check. 

411 

412 Returns 

413 ------- 

414 boolean 

415 Whether or not the array-like or dtype is of a DatetimeTZDtype dtype. 

416 

417 Examples 

418 -------- 

419 >>> is_datetime64tz_dtype(object) 

420 False 

421 >>> is_datetime64tz_dtype([1, 2, 3]) 

422 False 

423 >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3])) # tz-naive 

424 False 

425 >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern")) 

426 True 

427 

428 >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern") 

429 >>> s = pd.Series([], dtype=dtype) 

430 >>> is_datetime64tz_dtype(dtype) 

431 True 

432 >>> is_datetime64tz_dtype(s) 

433 True 

434 """ 

435 

436 if arr_or_dtype is None: 

437 return False 

438 return DatetimeTZDtype.is_dtype(arr_or_dtype) 

439 

440 

441def is_timedelta64_dtype(arr_or_dtype) -> bool: 

442 """ 

443 Check whether an array-like or dtype is of the timedelta64 dtype. 

444 

445 Parameters 

446 ---------- 

447 arr_or_dtype : array-like 

448 The array-like or dtype to check. 

449 

450 Returns 

451 ------- 

452 boolean 

453 Whether or not the array-like or dtype is of the timedelta64 dtype. 

454 

455 Examples 

456 -------- 

457 >>> is_timedelta64_dtype(object) 

458 False 

459 >>> is_timedelta64_dtype(np.timedelta64) 

460 True 

461 >>> is_timedelta64_dtype([1, 2, 3]) 

462 False 

463 >>> is_timedelta64_dtype(pd.Series([], dtype="timedelta64[ns]")) 

464 True 

465 >>> is_timedelta64_dtype('0 days') 

466 False 

467 """ 

468 

469 return _is_dtype_type(arr_or_dtype, classes(np.timedelta64)) 

470 

471 

472def is_period_dtype(arr_or_dtype) -> bool: 

473 """ 

474 Check whether an array-like or dtype is of the Period dtype. 

475 

476 Parameters 

477 ---------- 

478 arr_or_dtype : array-like 

479 The array-like or dtype to check. 

480 

481 Returns 

482 ------- 

483 boolean 

484 Whether or not the array-like or dtype is of the Period dtype. 

485 

486 Examples 

487 -------- 

488 >>> is_period_dtype(object) 

489 False 

490 >>> is_period_dtype(PeriodDtype(freq="D")) 

491 True 

492 >>> is_period_dtype([1, 2, 3]) 

493 False 

494 >>> is_period_dtype(pd.Period("2017-01-01")) 

495 False 

496 >>> is_period_dtype(pd.PeriodIndex([], freq="A")) 

497 True 

498 """ 

499 

500 # TODO: Consider making Period an instance of PeriodDtype 

501 if arr_or_dtype is None: 

502 return False 

503 return PeriodDtype.is_dtype(arr_or_dtype) 

504 

505 

506def is_interval_dtype(arr_or_dtype) -> bool: 

507 """ 

508 Check whether an array-like or dtype is of the Interval dtype. 

509 

510 Parameters 

511 ---------- 

512 arr_or_dtype : array-like 

513 The array-like or dtype to check. 

514 

515 Returns 

516 ------- 

517 boolean 

518 Whether or not the array-like or dtype is of the Interval dtype. 

519 

520 Examples 

521 -------- 

522 >>> is_interval_dtype(object) 

523 False 

524 >>> is_interval_dtype(IntervalDtype()) 

525 True 

526 >>> is_interval_dtype([1, 2, 3]) 

527 False 

528 >>> 

529 >>> interval = pd.Interval(1, 2, closed="right") 

530 >>> is_interval_dtype(interval) 

531 False 

532 >>> is_interval_dtype(pd.IntervalIndex([interval])) 

533 True 

534 """ 

535 

536 # TODO: Consider making Interval an instance of IntervalDtype 

537 if arr_or_dtype is None: 

538 return False 

539 return IntervalDtype.is_dtype(arr_or_dtype) 

540 

541 

542def is_categorical_dtype(arr_or_dtype) -> bool: 

543 """ 

544 Check whether an array-like or dtype is of the Categorical dtype. 

545 

546 Parameters 

547 ---------- 

548 arr_or_dtype : array-like 

549 The array-like or dtype to check. 

550 

551 Returns 

552 ------- 

553 boolean 

554 Whether or not the array-like or dtype is of the Categorical dtype. 

555 

556 Examples 

557 -------- 

558 >>> is_categorical_dtype(object) 

559 False 

560 >>> is_categorical_dtype(CategoricalDtype()) 

561 True 

562 >>> is_categorical_dtype([1, 2, 3]) 

563 False 

564 >>> is_categorical_dtype(pd.Categorical([1, 2, 3])) 

565 True 

566 >>> is_categorical_dtype(pd.CategoricalIndex([1, 2, 3])) 

567 True 

568 """ 

569 

570 if arr_or_dtype is None: 

571 return False 

572 return CategoricalDtype.is_dtype(arr_or_dtype) 

573 

574 

575def is_string_dtype(arr_or_dtype) -> bool: 

576 """ 

577 Check whether the provided array or dtype is of the string dtype. 

578 

579 Parameters 

580 ---------- 

581 arr_or_dtype : array-like 

582 The array or dtype to check. 

583 

584 Returns 

585 ------- 

586 boolean 

587 Whether or not the array or dtype is of the string dtype. 

588 

589 Examples 

590 -------- 

591 >>> is_string_dtype(str) 

592 True 

593 >>> is_string_dtype(object) 

594 True 

595 >>> is_string_dtype(int) 

596 False 

597 >>> 

598 >>> is_string_dtype(np.array(['a', 'b'])) 

599 True 

600 >>> is_string_dtype(pd.Series([1, 2])) 

601 False 

602 """ 

603 

604 # TODO: gh-15585: consider making the checks stricter. 

605 def condition(dtype) -> bool: 

606 return dtype.kind in ("O", "S", "U") and not is_excluded_dtype(dtype) 

607 

608 def is_excluded_dtype(dtype) -> bool: 

609 """ 

610 These have kind = "O" but aren't string dtypes so need to be explicitly excluded 

611 """ 

612 is_excluded_checks = (is_period_dtype, is_interval_dtype) 

613 return any(is_excluded(dtype) for is_excluded in is_excluded_checks) 

614 

615 return _is_dtype(arr_or_dtype, condition) 

616 

617 

618def is_period_arraylike(arr) -> bool: 

619 """ 

620 Check whether an array-like is a periodical array-like or PeriodIndex. 

621 

622 Parameters 

623 ---------- 

624 arr : array-like 

625 The array-like to check. 

626 

627 Returns 

628 ------- 

629 boolean 

630 Whether or not the array-like is a periodical array-like or 

631 PeriodIndex instance. 

632 

633 Examples 

634 -------- 

635 >>> is_period_arraylike([1, 2, 3]) 

636 False 

637 >>> is_period_arraylike(pd.Index([1, 2, 3])) 

638 False 

639 >>> is_period_arraylike(pd.PeriodIndex(["2017-01-01"], freq="D")) 

640 True 

641 """ 

642 

643 if isinstance(arr, (ABCPeriodIndex, ABCPeriodArray)): 

644 return True 

645 elif isinstance(arr, (np.ndarray, ABCSeries)): 

646 return is_period_dtype(arr.dtype) 

647 return getattr(arr, "inferred_type", None) == "period" 

648 

649 

650def is_datetime_arraylike(arr) -> bool: 

651 """ 

652 Check whether an array-like is a datetime array-like or DatetimeIndex. 

653 

654 Parameters 

655 ---------- 

656 arr : array-like 

657 The array-like to check. 

658 

659 Returns 

660 ------- 

661 boolean 

662 Whether or not the array-like is a datetime array-like or 

663 DatetimeIndex. 

664 

665 Examples 

666 -------- 

667 >>> is_datetime_arraylike([1, 2, 3]) 

668 False 

669 >>> is_datetime_arraylike(pd.Index([1, 2, 3])) 

670 False 

671 >>> is_datetime_arraylike(pd.DatetimeIndex([1, 2, 3])) 

672 True 

673 """ 

674 

675 if isinstance(arr, ABCDatetimeIndex): 

676 return True 

677 elif isinstance(arr, (np.ndarray, ABCSeries)): 

678 return ( 

679 is_object_dtype(arr.dtype) 

680 and lib.infer_dtype(arr, skipna=False) == "datetime" 

681 ) 

682 return getattr(arr, "inferred_type", None) == "datetime" 

683 

684 

685def is_dtype_equal(source, target) -> bool: 

686 """ 

687 Check if two dtypes are equal. 

688 

689 Parameters 

690 ---------- 

691 source : The first dtype to compare 

692 target : The second dtype to compare 

693 

694 Returns 

695 ------- 

696 boolean 

697 Whether or not the two dtypes are equal. 

698 

699 Examples 

700 -------- 

701 >>> is_dtype_equal(int, float) 

702 False 

703 >>> is_dtype_equal("int", int) 

704 True 

705 >>> is_dtype_equal(object, "category") 

706 False 

707 >>> is_dtype_equal(CategoricalDtype(), "category") 

708 True 

709 >>> is_dtype_equal(DatetimeTZDtype(), "datetime64") 

710 False 

711 """ 

712 

713 try: 

714 source = _get_dtype(source) 

715 target = _get_dtype(target) 

716 return source == target 

717 except (TypeError, AttributeError): 

718 

719 # invalid comparison 

720 # object == category will hit this 

721 return False 

722 

723 

724def is_any_int_dtype(arr_or_dtype) -> bool: 

725 """ 

726 Check whether the provided array or dtype is of an integer dtype. 

727 

728 In this function, timedelta64 instances are also considered "any-integer" 

729 type objects and will return True. 

730 

731 This function is internal and should not be exposed in the public API. 

732 

733 .. versionchanged:: 0.24.0 

734 

735 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered 

736 as integer by this function. 

737 

738 Parameters 

739 ---------- 

740 arr_or_dtype : array-like 

741 The array or dtype to check. 

742 

743 Returns 

744 ------- 

745 boolean 

746 Whether or not the array or dtype is of an integer dtype. 

747 

748 Examples 

749 -------- 

750 >>> is_any_int_dtype(str) 

751 False 

752 >>> is_any_int_dtype(int) 

753 True 

754 >>> is_any_int_dtype(float) 

755 False 

756 >>> is_any_int_dtype(np.uint64) 

757 True 

758 >>> is_any_int_dtype(np.datetime64) 

759 False 

760 >>> is_any_int_dtype(np.timedelta64) 

761 True 

762 >>> is_any_int_dtype(np.array(['a', 'b'])) 

763 False 

764 >>> is_any_int_dtype(pd.Series([1, 2])) 

765 True 

766 >>> is_any_int_dtype(np.array([], dtype=np.timedelta64)) 

767 True 

768 >>> is_any_int_dtype(pd.Index([1, 2.])) # float 

769 False 

770 """ 

771 

772 return _is_dtype_type(arr_or_dtype, classes(np.integer, np.timedelta64)) 

773 

774 

775def is_integer_dtype(arr_or_dtype) -> bool: 

776 """ 

777 Check whether the provided array or dtype is of an integer dtype. 

778 

779 Unlike in `in_any_int_dtype`, timedelta64 instances will return False. 

780 

781 .. versionchanged:: 0.24.0 

782 

783 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered 

784 as integer by this function. 

785 

786 Parameters 

787 ---------- 

788 arr_or_dtype : array-like 

789 The array or dtype to check. 

790 

791 Returns 

792 ------- 

793 boolean 

794 Whether or not the array or dtype is of an integer dtype and 

795 not an instance of timedelta64. 

796 

797 Examples 

798 -------- 

799 >>> is_integer_dtype(str) 

800 False 

801 >>> is_integer_dtype(int) 

802 True 

803 >>> is_integer_dtype(float) 

804 False 

805 >>> is_integer_dtype(np.uint64) 

806 True 

807 >>> is_integer_dtype('int8') 

808 True 

809 >>> is_integer_dtype('Int8') 

810 True 

811 >>> is_integer_dtype(pd.Int8Dtype) 

812 True 

813 >>> is_integer_dtype(np.datetime64) 

814 False 

815 >>> is_integer_dtype(np.timedelta64) 

816 False 

817 >>> is_integer_dtype(np.array(['a', 'b'])) 

818 False 

819 >>> is_integer_dtype(pd.Series([1, 2])) 

820 True 

821 >>> is_integer_dtype(np.array([], dtype=np.timedelta64)) 

822 False 

823 >>> is_integer_dtype(pd.Index([1, 2.])) # float 

824 False 

825 """ 

826 

827 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.integer)) 

828 

829 

830def is_signed_integer_dtype(arr_or_dtype) -> bool: 

831 """ 

832 Check whether the provided array or dtype is of a signed integer dtype. 

833 

834 Unlike in `in_any_int_dtype`, timedelta64 instances will return False. 

835 

836 .. versionchanged:: 0.24.0 

837 

838 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered 

839 as integer by this function. 

840 

841 Parameters 

842 ---------- 

843 arr_or_dtype : array-like 

844 The array or dtype to check. 

845 

846 Returns 

847 ------- 

848 boolean 

849 Whether or not the array or dtype is of a signed integer dtype 

850 and not an instance of timedelta64. 

851 

852 Examples 

853 -------- 

854 >>> is_signed_integer_dtype(str) 

855 False 

856 >>> is_signed_integer_dtype(int) 

857 True 

858 >>> is_signed_integer_dtype(float) 

859 False 

860 >>> is_signed_integer_dtype(np.uint64) # unsigned 

861 False 

862 >>> is_signed_integer_dtype('int8') 

863 True 

864 >>> is_signed_integer_dtype('Int8') 

865 True 

866 >>> is_signed_dtype(pd.Int8Dtype) 

867 True 

868 >>> is_signed_integer_dtype(np.datetime64) 

869 False 

870 >>> is_signed_integer_dtype(np.timedelta64) 

871 False 

872 >>> is_signed_integer_dtype(np.array(['a', 'b'])) 

873 False 

874 >>> is_signed_integer_dtype(pd.Series([1, 2])) 

875 True 

876 >>> is_signed_integer_dtype(np.array([], dtype=np.timedelta64)) 

877 False 

878 >>> is_signed_integer_dtype(pd.Index([1, 2.])) # float 

879 False 

880 >>> is_signed_integer_dtype(np.array([1, 2], dtype=np.uint32)) # unsigned 

881 False 

882 """ 

883 

884 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.signedinteger)) 

885 

886 

887def is_unsigned_integer_dtype(arr_or_dtype) -> bool: 

888 """ 

889 Check whether the provided array or dtype is of an unsigned integer dtype. 

890 

891 .. versionchanged:: 0.24.0 

892 

893 The nullable Integer dtypes (e.g. pandas.UInt64Dtype) are also 

894 considered as integer by this function. 

895 

896 Parameters 

897 ---------- 

898 arr_or_dtype : array-like 

899 The array or dtype to check. 

900 

901 Returns 

902 ------- 

903 boolean 

904 Whether or not the array or dtype is of an unsigned integer dtype. 

905 

906 Examples 

907 -------- 

908 >>> is_unsigned_integer_dtype(str) 

909 False 

910 >>> is_unsigned_integer_dtype(int) # signed 

911 False 

912 >>> is_unsigned_integer_dtype(float) 

913 False 

914 >>> is_unsigned_integer_dtype(np.uint64) 

915 True 

916 >>> is_unsigned_integer_dtype('uint8') 

917 True 

918 >>> is_unsigned_integer_dtype('UInt8') 

919 True 

920 >>> is_unsigned_integer_dtype(pd.UInt8Dtype) 

921 True 

922 >>> is_unsigned_integer_dtype(np.array(['a', 'b'])) 

923 False 

924 >>> is_unsigned_integer_dtype(pd.Series([1, 2])) # signed 

925 False 

926 >>> is_unsigned_integer_dtype(pd.Index([1, 2.])) # float 

927 False 

928 >>> is_unsigned_integer_dtype(np.array([1, 2], dtype=np.uint32)) 

929 True 

930 """ 

931 return _is_dtype_type( 

932 arr_or_dtype, classes_and_not_datetimelike(np.unsignedinteger) 

933 ) 

934 

935 

936def is_int64_dtype(arr_or_dtype) -> bool: 

937 """ 

938 Check whether the provided array or dtype is of the int64 dtype. 

939 

940 Parameters 

941 ---------- 

942 arr_or_dtype : array-like 

943 The array or dtype to check. 

944 

945 Returns 

946 ------- 

947 boolean 

948 Whether or not the array or dtype is of the int64 dtype. 

949 

950 Notes 

951 ----- 

952 Depending on system architecture, the return value of `is_int64_dtype( 

953 int)` will be True if the OS uses 64-bit integers and False if the OS 

954 uses 32-bit integers. 

955 

956 Examples 

957 -------- 

958 >>> is_int64_dtype(str) 

959 False 

960 >>> is_int64_dtype(np.int32) 

961 False 

962 >>> is_int64_dtype(np.int64) 

963 True 

964 >>> is_int64_dtype('int8') 

965 False 

966 >>> is_int64_dtype('Int8') 

967 False 

968 >>> is_int64_dtype(pd.Int64Dtype) 

969 True 

970 >>> is_int64_dtype(float) 

971 False 

972 >>> is_int64_dtype(np.uint64) # unsigned 

973 False 

974 >>> is_int64_dtype(np.array(['a', 'b'])) 

975 False 

976 >>> is_int64_dtype(np.array([1, 2], dtype=np.int64)) 

977 True 

978 >>> is_int64_dtype(pd.Index([1, 2.])) # float 

979 False 

980 >>> is_int64_dtype(np.array([1, 2], dtype=np.uint32)) # unsigned 

981 False 

982 """ 

983 

984 return _is_dtype_type(arr_or_dtype, classes(np.int64)) 

985 

986 

987def is_datetime64_any_dtype(arr_or_dtype) -> bool: 

988 """ 

989 Check whether the provided array or dtype is of the datetime64 dtype. 

990 

991 Parameters 

992 ---------- 

993 arr_or_dtype : array-like 

994 The array or dtype to check. 

995 

996 Returns 

997 ------- 

998 boolean 

999 Whether or not the array or dtype is of the datetime64 dtype. 

1000 

1001 Examples 

1002 -------- 

1003 >>> is_datetime64_any_dtype(str) 

1004 False 

1005 >>> is_datetime64_any_dtype(int) 

1006 False 

1007 >>> is_datetime64_any_dtype(np.datetime64) # can be tz-naive 

1008 True 

1009 >>> is_datetime64_any_dtype(DatetimeTZDtype("ns", "US/Eastern")) 

1010 True 

1011 >>> is_datetime64_any_dtype(np.array(['a', 'b'])) 

1012 False 

1013 >>> is_datetime64_any_dtype(np.array([1, 2])) 

1014 False 

1015 >>> is_datetime64_any_dtype(np.array([], dtype=np.datetime64)) 

1016 True 

1017 >>> is_datetime64_any_dtype(pd.DatetimeIndex([1, 2, 3], 

1018 dtype=np.datetime64)) 

1019 True 

1020 """ 

1021 

1022 if arr_or_dtype is None: 

1023 return False 

1024 return is_datetime64_dtype(arr_or_dtype) or is_datetime64tz_dtype(arr_or_dtype) 

1025 

1026 

1027def is_datetime64_ns_dtype(arr_or_dtype) -> bool: 

1028 """ 

1029 Check whether the provided array or dtype is of the datetime64[ns] dtype. 

1030 

1031 Parameters 

1032 ---------- 

1033 arr_or_dtype : array-like 

1034 The array or dtype to check. 

1035 

1036 Returns 

1037 ------- 

1038 boolean 

1039 Whether or not the array or dtype is of the datetime64[ns] dtype. 

1040 

1041 Examples 

1042 -------- 

1043 >>> is_datetime64_ns_dtype(str) 

1044 False 

1045 >>> is_datetime64_ns_dtype(int) 

1046 False 

1047 >>> is_datetime64_ns_dtype(np.datetime64) # no unit 

1048 False 

1049 >>> is_datetime64_ns_dtype(DatetimeTZDtype("ns", "US/Eastern")) 

1050 True 

1051 >>> is_datetime64_ns_dtype(np.array(['a', 'b'])) 

1052 False 

1053 >>> is_datetime64_ns_dtype(np.array([1, 2])) 

1054 False 

1055 >>> is_datetime64_ns_dtype(np.array([], dtype=np.datetime64)) # no unit 

1056 False 

1057 >>> is_datetime64_ns_dtype(np.array([], 

1058 dtype="datetime64[ps]")) # wrong unit 

1059 False 

1060 >>> is_datetime64_ns_dtype(pd.DatetimeIndex([1, 2, 3], 

1061 dtype=np.datetime64)) # has 'ns' unit 

1062 True 

1063 """ 

1064 

1065 if arr_or_dtype is None: 

1066 return False 

1067 try: 

1068 tipo = _get_dtype(arr_or_dtype) 

1069 except TypeError: 

1070 if is_datetime64tz_dtype(arr_or_dtype): 

1071 tipo = _get_dtype(arr_or_dtype.dtype) 

1072 else: 

1073 return False 

1074 return tipo == _NS_DTYPE or getattr(tipo, "base", None) == _NS_DTYPE 

1075 

1076 

1077def is_timedelta64_ns_dtype(arr_or_dtype) -> bool: 

1078 """ 

1079 Check whether the provided array or dtype is of the timedelta64[ns] dtype. 

1080 

1081 This is a very specific dtype, so generic ones like `np.timedelta64` 

1082 will return False if passed into this function. 

1083 

1084 Parameters 

1085 ---------- 

1086 arr_or_dtype : array-like 

1087 The array or dtype to check. 

1088 

1089 Returns 

1090 ------- 

1091 boolean 

1092 Whether or not the array or dtype is of the timedelta64[ns] dtype. 

1093 

1094 Examples 

1095 -------- 

1096 >>> is_timedelta64_ns_dtype(np.dtype('m8[ns]')) 

1097 True 

1098 >>> is_timedelta64_ns_dtype(np.dtype('m8[ps]')) # Wrong frequency 

1099 False 

1100 >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype='m8[ns]')) 

1101 True 

1102 >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype=np.timedelta64)) 

1103 False 

1104 """ 

1105 return _is_dtype(arr_or_dtype, lambda dtype: dtype == _TD_DTYPE) 

1106 

1107 

1108def is_datetime_or_timedelta_dtype(arr_or_dtype) -> bool: 

1109 """ 

1110 Check whether the provided array or dtype is of 

1111 a timedelta64 or datetime64 dtype. 

1112 

1113 Parameters 

1114 ---------- 

1115 arr_or_dtype : array-like 

1116 The array or dtype to check. 

1117 

1118 Returns 

1119 ------- 

1120 boolean 

1121 Whether or not the array or dtype is of a timedelta64, 

1122 or datetime64 dtype. 

1123 

1124 Examples 

1125 -------- 

1126 >>> is_datetime_or_timedelta_dtype(str) 

1127 False 

1128 >>> is_datetime_or_timedelta_dtype(int) 

1129 False 

1130 >>> is_datetime_or_timedelta_dtype(np.datetime64) 

1131 True 

1132 >>> is_datetime_or_timedelta_dtype(np.timedelta64) 

1133 True 

1134 >>> is_datetime_or_timedelta_dtype(np.array(['a', 'b'])) 

1135 False 

1136 >>> is_datetime_or_timedelta_dtype(pd.Series([1, 2])) 

1137 False 

1138 >>> is_datetime_or_timedelta_dtype(np.array([], dtype=np.timedelta64)) 

1139 True 

1140 >>> is_datetime_or_timedelta_dtype(np.array([], dtype=np.datetime64)) 

1141 True 

1142 """ 

1143 

1144 return _is_dtype_type(arr_or_dtype, classes(np.datetime64, np.timedelta64)) 

1145 

1146 

1147def _is_unorderable_exception(e: TypeError) -> bool: 

1148 """ 

1149 Check if the exception raised is an unorderable exception. 

1150 

1151 Parameters 

1152 ---------- 

1153 e : Exception or sub-class 

1154 The exception object to check. 

1155 

1156 Returns 

1157 ------- 

1158 bool 

1159 Whether or not the exception raised is an unorderable exception. 

1160 """ 

1161 return "'>' not supported between instances of" in str(e) 

1162 

1163 

1164# This exists to silence numpy deprecation warnings, see GH#29553 

1165def is_numeric_v_string_like(a, b): 

1166 """ 

1167 Check if we are comparing a string-like object to a numeric ndarray. 

1168 NumPy doesn't like to compare such objects, especially numeric arrays 

1169 and scalar string-likes. 

1170 

1171 Parameters 

1172 ---------- 

1173 a : array-like, scalar 

1174 The first object to check. 

1175 b : array-like, scalar 

1176 The second object to check. 

1177 

1178 Returns 

1179 ------- 

1180 boolean 

1181 Whether we return a comparing a string-like object to a numeric array. 

1182 

1183 Examples 

1184 -------- 

1185 >>> is_numeric_v_string_like(1, 1) 

1186 False 

1187 >>> is_numeric_v_string_like("foo", "foo") 

1188 False 

1189 >>> is_numeric_v_string_like(1, "foo") # non-array numeric 

1190 False 

1191 >>> is_numeric_v_string_like(np.array([1]), "foo") 

1192 True 

1193 >>> is_numeric_v_string_like("foo", np.array([1])) # symmetric check 

1194 True 

1195 >>> is_numeric_v_string_like(np.array([1, 2]), np.array(["foo"])) 

1196 True 

1197 >>> is_numeric_v_string_like(np.array(["foo"]), np.array([1, 2])) 

1198 True 

1199 >>> is_numeric_v_string_like(np.array([1]), np.array([2])) 

1200 False 

1201 >>> is_numeric_v_string_like(np.array(["foo"]), np.array(["foo"])) 

1202 False 

1203 """ 

1204 

1205 is_a_array = isinstance(a, np.ndarray) 

1206 is_b_array = isinstance(b, np.ndarray) 

1207 

1208 is_a_numeric_array = is_a_array and is_numeric_dtype(a) 

1209 is_b_numeric_array = is_b_array and is_numeric_dtype(b) 

1210 is_a_string_array = is_a_array and is_string_like_dtype(a) 

1211 is_b_string_array = is_b_array and is_string_like_dtype(b) 

1212 

1213 is_a_scalar_string_like = not is_a_array and isinstance(a, str) 

1214 is_b_scalar_string_like = not is_b_array and isinstance(b, str) 

1215 

1216 return ( 

1217 (is_a_numeric_array and is_b_scalar_string_like) 

1218 or (is_b_numeric_array and is_a_scalar_string_like) 

1219 or (is_a_numeric_array and is_b_string_array) 

1220 or (is_b_numeric_array and is_a_string_array) 

1221 ) 

1222 

1223 

1224# This exists to silence numpy deprecation warnings, see GH#29553 

1225def is_datetimelike_v_numeric(a, b): 

1226 """ 

1227 Check if we are comparing a datetime-like object to a numeric object. 

1228 By "numeric," we mean an object that is either of an int or float dtype. 

1229 

1230 Parameters 

1231 ---------- 

1232 a : array-like, scalar 

1233 The first object to check. 

1234 b : array-like, scalar 

1235 The second object to check. 

1236 

1237 Returns 

1238 ------- 

1239 boolean 

1240 Whether we return a comparing a datetime-like to a numeric object. 

1241 

1242 Examples 

1243 -------- 

1244 >>> dt = np.datetime64(pd.datetime(2017, 1, 1)) 

1245 >>> 

1246 >>> is_datetimelike_v_numeric(1, 1) 

1247 False 

1248 >>> is_datetimelike_v_numeric(dt, dt) 

1249 False 

1250 >>> is_datetimelike_v_numeric(1, dt) 

1251 True 

1252 >>> is_datetimelike_v_numeric(dt, 1) # symmetric check 

1253 True 

1254 >>> is_datetimelike_v_numeric(np.array([dt]), 1) 

1255 True 

1256 >>> is_datetimelike_v_numeric(np.array([1]), dt) 

1257 True 

1258 >>> is_datetimelike_v_numeric(np.array([dt]), np.array([1])) 

1259 True 

1260 >>> is_datetimelike_v_numeric(np.array([1]), np.array([2])) 

1261 False 

1262 >>> is_datetimelike_v_numeric(np.array([dt]), np.array([dt])) 

1263 False 

1264 """ 

1265 

1266 if not hasattr(a, "dtype"): 

1267 a = np.asarray(a) 

1268 if not hasattr(b, "dtype"): 

1269 b = np.asarray(b) 

1270 

1271 def is_numeric(x): 

1272 """ 

1273 Check if an object has a numeric dtype (i.e. integer or float). 

1274 """ 

1275 return is_integer_dtype(x) or is_float_dtype(x) 

1276 

1277 return (needs_i8_conversion(a) and is_numeric(b)) or ( 

1278 needs_i8_conversion(b) and is_numeric(a) 

1279 ) 

1280 

1281 

1282def needs_i8_conversion(arr_or_dtype) -> bool: 

1283 """ 

1284 Check whether the array or dtype should be converted to int64. 

1285 

1286 An array-like or dtype "needs" such a conversion if the array-like 

1287 or dtype is of a datetime-like dtype 

1288 

1289 Parameters 

1290 ---------- 

1291 arr_or_dtype : array-like 

1292 The array or dtype to check. 

1293 

1294 Returns 

1295 ------- 

1296 boolean 

1297 Whether or not the array or dtype should be converted to int64. 

1298 

1299 Examples 

1300 -------- 

1301 >>> needs_i8_conversion(str) 

1302 False 

1303 >>> needs_i8_conversion(np.int64) 

1304 False 

1305 >>> needs_i8_conversion(np.datetime64) 

1306 True 

1307 >>> needs_i8_conversion(np.array(['a', 'b'])) 

1308 False 

1309 >>> needs_i8_conversion(pd.Series([1, 2])) 

1310 False 

1311 >>> needs_i8_conversion(pd.Series([], dtype="timedelta64[ns]")) 

1312 True 

1313 >>> needs_i8_conversion(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern")) 

1314 True 

1315 """ 

1316 

1317 if arr_or_dtype is None: 

1318 return False 

1319 return ( 

1320 is_datetime_or_timedelta_dtype(arr_or_dtype) 

1321 or is_datetime64tz_dtype(arr_or_dtype) 

1322 or is_period_dtype(arr_or_dtype) 

1323 ) 

1324 

1325 

1326def is_numeric_dtype(arr_or_dtype) -> bool: 

1327 """ 

1328 Check whether the provided array or dtype is of a numeric dtype. 

1329 

1330 Parameters 

1331 ---------- 

1332 arr_or_dtype : array-like 

1333 The array or dtype to check. 

1334 

1335 Returns 

1336 ------- 

1337 boolean 

1338 Whether or not the array or dtype is of a numeric dtype. 

1339 

1340 Examples 

1341 -------- 

1342 >>> is_numeric_dtype(str) 

1343 False 

1344 >>> is_numeric_dtype(int) 

1345 True 

1346 >>> is_numeric_dtype(float) 

1347 True 

1348 >>> is_numeric_dtype(np.uint64) 

1349 True 

1350 >>> is_numeric_dtype(np.datetime64) 

1351 False 

1352 >>> is_numeric_dtype(np.timedelta64) 

1353 False 

1354 >>> is_numeric_dtype(np.array(['a', 'b'])) 

1355 False 

1356 >>> is_numeric_dtype(pd.Series([1, 2])) 

1357 True 

1358 >>> is_numeric_dtype(pd.Index([1, 2.])) 

1359 True 

1360 >>> is_numeric_dtype(np.array([], dtype=np.timedelta64)) 

1361 False 

1362 """ 

1363 

1364 return _is_dtype_type( 

1365 arr_or_dtype, classes_and_not_datetimelike(np.number, np.bool_) 

1366 ) 

1367 

1368 

1369def is_string_like_dtype(arr_or_dtype) -> bool: 

1370 """ 

1371 Check whether the provided array or dtype is of a string-like dtype. 

1372 

1373 Unlike `is_string_dtype`, the object dtype is excluded because it 

1374 is a mixed dtype. 

1375 

1376 Parameters 

1377 ---------- 

1378 arr_or_dtype : array-like 

1379 The array or dtype to check. 

1380 

1381 Returns 

1382 ------- 

1383 boolean 

1384 Whether or not the array or dtype is of the string dtype. 

1385 

1386 Examples 

1387 -------- 

1388 >>> is_string_like_dtype(str) 

1389 True 

1390 >>> is_string_like_dtype(object) 

1391 False 

1392 >>> is_string_like_dtype(np.array(['a', 'b'])) 

1393 True 

1394 >>> is_string_like_dtype(pd.Series([1, 2])) 

1395 False 

1396 """ 

1397 

1398 return _is_dtype(arr_or_dtype, lambda dtype: dtype.kind in ("S", "U")) 

1399 

1400 

1401def is_float_dtype(arr_or_dtype) -> bool: 

1402 """ 

1403 Check whether the provided array or dtype is of a float dtype. 

1404 

1405 This function is internal and should not be exposed in the public API. 

1406 

1407 Parameters 

1408 ---------- 

1409 arr_or_dtype : array-like 

1410 The array or dtype to check. 

1411 

1412 Returns 

1413 ------- 

1414 boolean 

1415 Whether or not the array or dtype is of a float dtype. 

1416 

1417 Examples 

1418 -------- 

1419 >>> is_float_dtype(str) 

1420 False 

1421 >>> is_float_dtype(int) 

1422 False 

1423 >>> is_float_dtype(float) 

1424 True 

1425 >>> is_float_dtype(np.array(['a', 'b'])) 

1426 False 

1427 >>> is_float_dtype(pd.Series([1, 2])) 

1428 False 

1429 >>> is_float_dtype(pd.Index([1, 2.])) 

1430 True 

1431 """ 

1432 return _is_dtype_type(arr_or_dtype, classes(np.floating)) 

1433 

1434 

1435def is_bool_dtype(arr_or_dtype) -> bool: 

1436 """ 

1437 Check whether the provided array or dtype is of a boolean dtype. 

1438 

1439 Parameters 

1440 ---------- 

1441 arr_or_dtype : array-like 

1442 The array or dtype to check. 

1443 

1444 Returns 

1445 ------- 

1446 boolean 

1447 Whether or not the array or dtype is of a boolean dtype. 

1448 

1449 Notes 

1450 ----- 

1451 An ExtensionArray is considered boolean when the ``_is_boolean`` 

1452 attribute is set to True. 

1453 

1454 Examples 

1455 -------- 

1456 >>> is_bool_dtype(str) 

1457 False 

1458 >>> is_bool_dtype(int) 

1459 False 

1460 >>> is_bool_dtype(bool) 

1461 True 

1462 >>> is_bool_dtype(np.bool) 

1463 True 

1464 >>> is_bool_dtype(np.array(['a', 'b'])) 

1465 False 

1466 >>> is_bool_dtype(pd.Series([1, 2])) 

1467 False 

1468 >>> is_bool_dtype(np.array([True, False])) 

1469 True 

1470 >>> is_bool_dtype(pd.Categorical([True, False])) 

1471 True 

1472 >>> is_bool_dtype(pd.arrays.SparseArray([True, False])) 

1473 True 

1474 """ 

1475 if arr_or_dtype is None: 

1476 return False 

1477 try: 

1478 dtype = _get_dtype(arr_or_dtype) 

1479 except TypeError: 

1480 return False 

1481 

1482 if isinstance(arr_or_dtype, CategoricalDtype): 

1483 arr_or_dtype = arr_or_dtype.categories 

1484 # now we use the special definition for Index 

1485 

1486 if isinstance(arr_or_dtype, ABCIndexClass): 

1487 

1488 # TODO(jreback) 

1489 # we don't have a boolean Index class 

1490 # so its object, we need to infer to 

1491 # guess this 

1492 return arr_or_dtype.is_object and arr_or_dtype.inferred_type == "boolean" 

1493 elif is_extension_array_dtype(arr_or_dtype): 

1494 dtype = getattr(arr_or_dtype, "dtype", arr_or_dtype) 

1495 return dtype._is_boolean 

1496 

1497 return issubclass(dtype.type, np.bool_) 

1498 

1499 

1500def is_extension_type(arr) -> bool: 

1501 """ 

1502 Check whether an array-like is of a pandas extension class instance. 

1503 

1504 .. deprecated:: 1.0.0 

1505 Use ``is_extension_array_dtype`` instead. 

1506 

1507 Extension classes include categoricals, pandas sparse objects (i.e. 

1508 classes represented within the pandas library and not ones external 

1509 to it like scipy sparse matrices), and datetime-like arrays. 

1510 

1511 Parameters 

1512 ---------- 

1513 arr : array-like 

1514 The array-like to check. 

1515 

1516 Returns 

1517 ------- 

1518 boolean 

1519 Whether or not the array-like is of a pandas extension class instance. 

1520 

1521 Examples 

1522 -------- 

1523 >>> is_extension_type([1, 2, 3]) 

1524 False 

1525 >>> is_extension_type(np.array([1, 2, 3])) 

1526 False 

1527 >>> 

1528 >>> cat = pd.Categorical([1, 2, 3]) 

1529 >>> 

1530 >>> is_extension_type(cat) 

1531 True 

1532 >>> is_extension_type(pd.Series(cat)) 

1533 True 

1534 >>> is_extension_type(pd.arrays.SparseArray([1, 2, 3])) 

1535 True 

1536 >>> from scipy.sparse import bsr_matrix 

1537 >>> is_extension_type(bsr_matrix([1, 2, 3])) 

1538 False 

1539 >>> is_extension_type(pd.DatetimeIndex([1, 2, 3])) 

1540 False 

1541 >>> is_extension_type(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern")) 

1542 True 

1543 >>> 

1544 >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern") 

1545 >>> s = pd.Series([], dtype=dtype) 

1546 >>> is_extension_type(s) 

1547 True 

1548 """ 

1549 warnings.warn( 

1550 "'is_extension_type' is deprecated and will be removed in a future " 

1551 "version. Use 'is_extension_array_dtype' instead.", 

1552 FutureWarning, 

1553 stacklevel=2, 

1554 ) 

1555 

1556 if is_categorical(arr): 

1557 return True 

1558 elif is_sparse(arr): 

1559 return True 

1560 elif is_datetime64tz_dtype(arr): 

1561 return True 

1562 return False 

1563 

1564 

1565def is_extension_array_dtype(arr_or_dtype) -> bool: 

1566 """ 

1567 Check if an object is a pandas extension array type. 

1568 

1569 See the :ref:`Use Guide <extending.extension-types>` for more. 

1570 

1571 Parameters 

1572 ---------- 

1573 arr_or_dtype : object 

1574 For array-like input, the ``.dtype`` attribute will 

1575 be extracted. 

1576 

1577 Returns 

1578 ------- 

1579 bool 

1580 Whether the `arr_or_dtype` is an extension array type. 

1581 

1582 Notes 

1583 ----- 

1584 This checks whether an object implements the pandas extension 

1585 array interface. In pandas, this includes: 

1586 

1587 * Categorical 

1588 * Sparse 

1589 * Interval 

1590 * Period 

1591 * DatetimeArray 

1592 * TimedeltaArray 

1593 

1594 Third-party libraries may implement arrays or types satisfying 

1595 this interface as well. 

1596 

1597 Examples 

1598 -------- 

1599 >>> from pandas.api.types import is_extension_array_dtype 

1600 >>> arr = pd.Categorical(['a', 'b']) 

1601 >>> is_extension_array_dtype(arr) 

1602 True 

1603 >>> is_extension_array_dtype(arr.dtype) 

1604 True 

1605 

1606 >>> arr = np.array(['a', 'b']) 

1607 >>> is_extension_array_dtype(arr.dtype) 

1608 False 

1609 """ 

1610 dtype = getattr(arr_or_dtype, "dtype", arr_or_dtype) 

1611 return isinstance(dtype, ExtensionDtype) or registry.find(dtype) is not None 

1612 

1613 

1614def is_complex_dtype(arr_or_dtype) -> bool: 

1615 """ 

1616 Check whether the provided array or dtype is of a complex dtype. 

1617 

1618 Parameters 

1619 ---------- 

1620 arr_or_dtype : array-like 

1621 The array or dtype to check. 

1622 

1623 Returns 

1624 ------- 

1625 boolean 

1626 Whether or not the array or dtype is of a complex dtype. 

1627 

1628 Examples 

1629 -------- 

1630 >>> is_complex_dtype(str) 

1631 False 

1632 >>> is_complex_dtype(int) 

1633 False 

1634 >>> is_complex_dtype(np.complex) 

1635 True 

1636 >>> is_complex_dtype(np.array(['a', 'b'])) 

1637 False 

1638 >>> is_complex_dtype(pd.Series([1, 2])) 

1639 False 

1640 >>> is_complex_dtype(np.array([1 + 1j, 5])) 

1641 True 

1642 """ 

1643 

1644 return _is_dtype_type(arr_or_dtype, classes(np.complexfloating)) 

1645 

1646 

1647def _is_dtype(arr_or_dtype, condition) -> bool: 

1648 """ 

1649 Return a boolean if the condition is satisfied for the arr_or_dtype. 

1650 

1651 Parameters 

1652 ---------- 

1653 arr_or_dtype : array-like, str, np.dtype, or ExtensionArrayType 

1654 The array-like or dtype object whose dtype we want to extract. 

1655 condition : callable[Union[np.dtype, ExtensionDtype]] 

1656 

1657 Returns 

1658 ------- 

1659 bool 

1660 

1661 """ 

1662 

1663 if arr_or_dtype is None: 

1664 return False 

1665 try: 

1666 dtype = _get_dtype(arr_or_dtype) 

1667 except (TypeError, ValueError, UnicodeEncodeError): 

1668 return False 

1669 return condition(dtype) 

1670 

1671 

1672def _get_dtype(arr_or_dtype): 

1673 """ 

1674 Get the dtype instance associated with an array 

1675 or dtype object. 

1676 

1677 Parameters 

1678 ---------- 

1679 arr_or_dtype : array-like 

1680 The array-like or dtype object whose dtype we want to extract. 

1681 

1682 Returns 

1683 ------- 

1684 obj_dtype : The extract dtype instance from the 

1685 passed in array or dtype object. 

1686 

1687 Raises 

1688 ------ 

1689 TypeError : The passed in object is None. 

1690 """ 

1691 

1692 if arr_or_dtype is None: 

1693 raise TypeError("Cannot deduce dtype from null object") 

1694 

1695 # fastpath 

1696 elif isinstance(arr_or_dtype, np.dtype): 

1697 return arr_or_dtype 

1698 elif isinstance(arr_or_dtype, type): 

1699 return np.dtype(arr_or_dtype) 

1700 

1701 # if we have an array-like 

1702 elif hasattr(arr_or_dtype, "dtype"): 

1703 arr_or_dtype = arr_or_dtype.dtype 

1704 

1705 return pandas_dtype(arr_or_dtype) 

1706 

1707 

1708def _is_dtype_type(arr_or_dtype, condition) -> bool: 

1709 """ 

1710 Return a boolean if the condition is satisfied for the arr_or_dtype. 

1711 

1712 Parameters 

1713 ---------- 

1714 arr_or_dtype : array-like 

1715 The array-like or dtype object whose dtype we want to extract. 

1716 condition : callable[Union[np.dtype, ExtensionDtypeType]] 

1717 

1718 Returns 

1719 ------- 

1720 bool : if the condition is satisfied for the arr_or_dtype 

1721 """ 

1722 

1723 if arr_or_dtype is None: 

1724 return condition(type(None)) 

1725 

1726 # fastpath 

1727 if isinstance(arr_or_dtype, np.dtype): 

1728 return condition(arr_or_dtype.type) 

1729 elif isinstance(arr_or_dtype, type): 

1730 if issubclass(arr_or_dtype, ExtensionDtype): 

1731 arr_or_dtype = arr_or_dtype.type 

1732 return condition(np.dtype(arr_or_dtype).type) 

1733 

1734 # if we have an array-like 

1735 if hasattr(arr_or_dtype, "dtype"): 

1736 arr_or_dtype = arr_or_dtype.dtype 

1737 

1738 # we are not possibly a dtype 

1739 elif is_list_like(arr_or_dtype): 

1740 return condition(type(None)) 

1741 

1742 try: 

1743 tipo = pandas_dtype(arr_or_dtype).type 

1744 except (TypeError, ValueError, UnicodeEncodeError): 

1745 if is_scalar(arr_or_dtype): 

1746 return condition(type(None)) 

1747 

1748 return False 

1749 

1750 return condition(tipo) 

1751 

1752 

1753def infer_dtype_from_object(dtype): 

1754 """ 

1755 Get a numpy dtype.type-style object for a dtype object. 

1756 

1757 This methods also includes handling of the datetime64[ns] and 

1758 datetime64[ns, TZ] objects. 

1759 

1760 If no dtype can be found, we return ``object``. 

1761 

1762 Parameters 

1763 ---------- 

1764 dtype : dtype, type 

1765 The dtype object whose numpy dtype.type-style 

1766 object we want to extract. 

1767 

1768 Returns 

1769 ------- 

1770 dtype_object : The extracted numpy dtype.type-style object. 

1771 """ 

1772 

1773 if isinstance(dtype, type) and issubclass(dtype, np.generic): 

1774 # Type object from a dtype 

1775 return dtype 

1776 elif isinstance(dtype, (np.dtype, ExtensionDtype)): 

1777 # dtype object 

1778 try: 

1779 _validate_date_like_dtype(dtype) 

1780 except TypeError: 

1781 # Should still pass if we don't have a date-like 

1782 pass 

1783 return dtype.type 

1784 

1785 try: 

1786 dtype = pandas_dtype(dtype) 

1787 except TypeError: 

1788 pass 

1789 

1790 if is_extension_array_dtype(dtype): 

1791 return dtype.type 

1792 elif isinstance(dtype, str): 

1793 

1794 # TODO(jreback) 

1795 # should deprecate these 

1796 if dtype in ["datetimetz", "datetime64tz"]: 

1797 return DatetimeTZDtype.type 

1798 elif dtype in ["period"]: 

1799 raise NotImplementedError 

1800 

1801 if dtype == "datetime" or dtype == "timedelta": 

1802 dtype += "64" 

1803 try: 

1804 return infer_dtype_from_object(getattr(np, dtype)) 

1805 except (AttributeError, TypeError): 

1806 # Handles cases like _get_dtype(int) i.e., 

1807 # Python objects that are valid dtypes 

1808 # (unlike user-defined types, in general) 

1809 # 

1810 # TypeError handles the float16 type code of 'e' 

1811 # further handle internal types 

1812 pass 

1813 

1814 return infer_dtype_from_object(np.dtype(dtype)) 

1815 

1816 

1817def _validate_date_like_dtype(dtype) -> None: 

1818 """ 

1819 Check whether the dtype is a date-like dtype. Raises an error if invalid. 

1820 

1821 Parameters 

1822 ---------- 

1823 dtype : dtype, type 

1824 The dtype to check. 

1825 

1826 Raises 

1827 ------ 

1828 TypeError : The dtype could not be casted to a date-like dtype. 

1829 ValueError : The dtype is an illegal date-like dtype (e.g. the 

1830 the frequency provided is too specific) 

1831 """ 

1832 

1833 try: 

1834 typ = np.datetime_data(dtype)[0] 

1835 except ValueError as e: 

1836 raise TypeError(e) 

1837 if typ != "generic" and typ != "ns": 

1838 raise ValueError( 

1839 f"{repr(dtype.name)} is too specific of a frequency, " 

1840 f"try passing {repr(dtype.type.__name__)}" 

1841 ) 

1842 

1843 

1844def pandas_dtype(dtype): 

1845 """ 

1846 Convert input into a pandas only dtype object or a numpy dtype object. 

1847 

1848 Parameters 

1849 ---------- 

1850 dtype : object to be converted 

1851 

1852 Returns 

1853 ------- 

1854 np.dtype or a pandas dtype 

1855 

1856 Raises 

1857 ------ 

1858 TypeError if not a dtype 

1859 """ 

1860 # short-circuit 

1861 if isinstance(dtype, np.ndarray): 

1862 return dtype.dtype 

1863 elif isinstance(dtype, (np.dtype, ExtensionDtype)): 

1864 return dtype 

1865 

1866 # registered extension types 

1867 result = registry.find(dtype) 

1868 if result is not None: 

1869 return result 

1870 

1871 # try a numpy dtype 

1872 # raise a consistent TypeError if failed 

1873 try: 

1874 npdtype = np.dtype(dtype) 

1875 except SyntaxError: 

1876 # np.dtype uses `eval` which can raise SyntaxError 

1877 raise TypeError(f"data type '{dtype}' not understood") 

1878 

1879 # Any invalid dtype (such as pd.Timestamp) should raise an error. 

1880 # np.dtype(invalid_type).kind = 0 for such objects. However, this will 

1881 # also catch some valid dtypes such as object, np.object_ and 'object' 

1882 # which we safeguard against by catching them earlier and returning 

1883 # np.dtype(valid_dtype) before this condition is evaluated. 

1884 if is_hashable(dtype) and dtype in [object, np.object_, "object", "O"]: 

1885 # check hashability to avoid errors/DeprecationWarning when we get 

1886 # here and `dtype` is an array 

1887 return npdtype 

1888 elif npdtype.kind == "O": 

1889 raise TypeError(f"dtype '{dtype}' not understood") 

1890 

1891 return npdtype