Coverage for /home/martinb/.local/share/virtualenvs/camcops/lib/python3.6/site-packages/pandas/core/dtypes/common.py : 27%

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
5import numpy as np
7from pandas._libs import algos, lib
8from pandas._libs.tslibs import conversion
9from pandas._typing import ArrayLike
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)
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}
64_NS_DTYPE = conversion.NS_DTYPE
65_TD_DTYPE = conversion.TD_DTYPE
66_INT64_DTYPE = np.dtype(np.int64)
68# oh the troubles to reduce import time
69_is_scipy_sparse = None
71ensure_float64 = algos.ensure_float64
72ensure_float32 = algos.ensure_float32
74_ensure_datetime64ns = conversion.ensure_datetime64ns
75_ensure_timedelta64ns = conversion.ensure_timedelta64ns
78def ensure_float(arr):
79 """
80 Ensure that an array object has a float dtype if possible.
82 Parameters
83 ----------
84 arr : array-like
85 The array whose data type we want to enforce as float.
87 Returns
88 -------
89 float_arr : The original array cast to the float dtype if
90 possible. Otherwise, the original array is returned.
91 """
93 if issubclass(arr.dtype.type, (np.integer, np.bool_)):
94 arr = arr.astype(float)
95 return arr
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
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
118def ensure_categorical(arr):
119 """
120 Ensure that an array-like object is a Categorical (if not already).
122 Parameters
123 ----------
124 arr : array-like
125 The array that we want to convert into a Categorical.
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 """
133 if not is_categorical(arr):
134 from pandas import Categorical
136 arr = Categorical(arr)
137 return arr
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.
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.
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.
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)
179def ensure_python_int(value: Union[int, np.integer]) -> int:
180 """
181 Ensure that a value is a python int.
183 Parameters
184 ----------
185 value: int or numpy.integer
187 Returns
188 -------
189 int
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
206def classes(*klasses) -> Callable:
207 """ evaluate if the tipo is a subclass of the klasses """
208 return lambda tipo: issubclass(tipo, klasses)
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 )
222def is_object_dtype(arr_or_dtype) -> bool:
223 """
224 Check whether an array-like or dtype is of the object dtype.
226 Parameters
227 ----------
228 arr_or_dtype : array-like
229 The array-like or dtype to check.
231 Returns
232 -------
233 boolean
234 Whether or not the array-like or dtype is of the object dtype.
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_))
252def is_sparse(arr) -> bool:
253 """
254 Check whether an array-like is a 1-D pandas sparse array.
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.
260 Parameters
261 ----------
262 arr : array-like
263 Array-like to check.
265 Returns
266 -------
267 bool
268 Whether or not the array-like is a pandas sparse array.
270 Examples
271 --------
272 Returns `True` if the parameter is a 1-D pandas sparse array.
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
279 Returns `False` if the parameter is not sparse.
281 >>> is_sparse(np.array([0, 0, 1, 0]))
282 False
283 >>> is_sparse(pd.Series([0, 1, 0, 0]))
284 False
286 Returns `False` if the parameter is not a pandas sparse array.
288 >>> from scipy.sparse import bsr_matrix
289 >>> is_sparse(bsr_matrix([0, 1, 0, 0]))
290 False
292 Returns `False` if the parameter has more than one dimension.
293 """
294 from pandas.core.arrays.sparse import SparseDtype
296 dtype = getattr(arr, "dtype", arr)
297 return isinstance(dtype, SparseDtype)
300def is_scipy_sparse(arr) -> bool:
301 """
302 Check whether an array-like is a scipy.sparse.spmatrix instance.
304 Parameters
305 ----------
306 arr : array-like
307 The array-like to check.
309 Returns
310 -------
311 boolean
312 Whether or not the array-like is a scipy.sparse.spmatrix instance.
314 Notes
315 -----
316 If scipy is not installed, this function will always return False.
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 """
327 global _is_scipy_sparse
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
335 assert _is_scipy_sparse is not None
336 return _is_scipy_sparse(arr)
339def is_categorical(arr) -> bool:
340 """
341 Check whether an array-like is a Categorical instance.
343 Parameters
344 ----------
345 arr : array-like
346 The array-like to check.
348 Returns
349 -------
350 boolean
351 Whether or not the array-like is of a Categorical instance.
353 Examples
354 --------
355 >>> is_categorical([1, 2, 3])
356 False
358 Categoricals, Series Categoricals, and CategoricalIndex will return True.
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 """
369 return isinstance(arr, ABCCategorical) or is_categorical_dtype(arr)
372def is_datetime64_dtype(arr_or_dtype) -> bool:
373 """
374 Check whether an array-like or dtype is of the datetime64 dtype.
376 Parameters
377 ----------
378 arr_or_dtype : array-like
379 The array-like or dtype to check.
381 Returns
382 -------
383 boolean
384 Whether or not the array-like or dtype is of the datetime64 dtype.
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 """
400 return _is_dtype_type(arr_or_dtype, classes(np.datetime64))
403def is_datetime64tz_dtype(arr_or_dtype) -> bool:
404 """
405 Check whether an array-like or dtype is of a DatetimeTZDtype dtype.
407 Parameters
408 ----------
409 arr_or_dtype : array-like
410 The array-like or dtype to check.
412 Returns
413 -------
414 boolean
415 Whether or not the array-like or dtype is of a DatetimeTZDtype dtype.
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
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 """
436 if arr_or_dtype is None:
437 return False
438 return DatetimeTZDtype.is_dtype(arr_or_dtype)
441def is_timedelta64_dtype(arr_or_dtype) -> bool:
442 """
443 Check whether an array-like or dtype is of the timedelta64 dtype.
445 Parameters
446 ----------
447 arr_or_dtype : array-like
448 The array-like or dtype to check.
450 Returns
451 -------
452 boolean
453 Whether or not the array-like or dtype is of the timedelta64 dtype.
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 """
469 return _is_dtype_type(arr_or_dtype, classes(np.timedelta64))
472def is_period_dtype(arr_or_dtype) -> bool:
473 """
474 Check whether an array-like or dtype is of the Period dtype.
476 Parameters
477 ----------
478 arr_or_dtype : array-like
479 The array-like or dtype to check.
481 Returns
482 -------
483 boolean
484 Whether or not the array-like or dtype is of the Period dtype.
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 """
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)
506def is_interval_dtype(arr_or_dtype) -> bool:
507 """
508 Check whether an array-like or dtype is of the Interval dtype.
510 Parameters
511 ----------
512 arr_or_dtype : array-like
513 The array-like or dtype to check.
515 Returns
516 -------
517 boolean
518 Whether or not the array-like or dtype is of the Interval dtype.
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 """
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)
542def is_categorical_dtype(arr_or_dtype) -> bool:
543 """
544 Check whether an array-like or dtype is of the Categorical dtype.
546 Parameters
547 ----------
548 arr_or_dtype : array-like
549 The array-like or dtype to check.
551 Returns
552 -------
553 boolean
554 Whether or not the array-like or dtype is of the Categorical dtype.
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 """
570 if arr_or_dtype is None:
571 return False
572 return CategoricalDtype.is_dtype(arr_or_dtype)
575def is_string_dtype(arr_or_dtype) -> bool:
576 """
577 Check whether the provided array or dtype is of the string dtype.
579 Parameters
580 ----------
581 arr_or_dtype : array-like
582 The array or dtype to check.
584 Returns
585 -------
586 boolean
587 Whether or not the array or dtype is of the string dtype.
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 """
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)
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)
615 return _is_dtype(arr_or_dtype, condition)
618def is_period_arraylike(arr) -> bool:
619 """
620 Check whether an array-like is a periodical array-like or PeriodIndex.
622 Parameters
623 ----------
624 arr : array-like
625 The array-like to check.
627 Returns
628 -------
629 boolean
630 Whether or not the array-like is a periodical array-like or
631 PeriodIndex instance.
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 """
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"
650def is_datetime_arraylike(arr) -> bool:
651 """
652 Check whether an array-like is a datetime array-like or DatetimeIndex.
654 Parameters
655 ----------
656 arr : array-like
657 The array-like to check.
659 Returns
660 -------
661 boolean
662 Whether or not the array-like is a datetime array-like or
663 DatetimeIndex.
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 """
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"
685def is_dtype_equal(source, target) -> bool:
686 """
687 Check if two dtypes are equal.
689 Parameters
690 ----------
691 source : The first dtype to compare
692 target : The second dtype to compare
694 Returns
695 -------
696 boolean
697 Whether or not the two dtypes are equal.
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 """
713 try:
714 source = _get_dtype(source)
715 target = _get_dtype(target)
716 return source == target
717 except (TypeError, AttributeError):
719 # invalid comparison
720 # object == category will hit this
721 return False
724def is_any_int_dtype(arr_or_dtype) -> bool:
725 """
726 Check whether the provided array or dtype is of an integer dtype.
728 In this function, timedelta64 instances are also considered "any-integer"
729 type objects and will return True.
731 This function is internal and should not be exposed in the public API.
733 .. versionchanged:: 0.24.0
735 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
736 as integer by this function.
738 Parameters
739 ----------
740 arr_or_dtype : array-like
741 The array or dtype to check.
743 Returns
744 -------
745 boolean
746 Whether or not the array or dtype is of an integer dtype.
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 """
772 return _is_dtype_type(arr_or_dtype, classes(np.integer, np.timedelta64))
775def is_integer_dtype(arr_or_dtype) -> bool:
776 """
777 Check whether the provided array or dtype is of an integer dtype.
779 Unlike in `in_any_int_dtype`, timedelta64 instances will return False.
781 .. versionchanged:: 0.24.0
783 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
784 as integer by this function.
786 Parameters
787 ----------
788 arr_or_dtype : array-like
789 The array or dtype to check.
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.
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 """
827 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.integer))
830def is_signed_integer_dtype(arr_or_dtype) -> bool:
831 """
832 Check whether the provided array or dtype is of a signed integer dtype.
834 Unlike in `in_any_int_dtype`, timedelta64 instances will return False.
836 .. versionchanged:: 0.24.0
838 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
839 as integer by this function.
841 Parameters
842 ----------
843 arr_or_dtype : array-like
844 The array or dtype to check.
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.
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 """
884 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.signedinteger))
887def is_unsigned_integer_dtype(arr_or_dtype) -> bool:
888 """
889 Check whether the provided array or dtype is of an unsigned integer dtype.
891 .. versionchanged:: 0.24.0
893 The nullable Integer dtypes (e.g. pandas.UInt64Dtype) are also
894 considered as integer by this function.
896 Parameters
897 ----------
898 arr_or_dtype : array-like
899 The array or dtype to check.
901 Returns
902 -------
903 boolean
904 Whether or not the array or dtype is of an unsigned integer dtype.
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 )
936def is_int64_dtype(arr_or_dtype) -> bool:
937 """
938 Check whether the provided array or dtype is of the int64 dtype.
940 Parameters
941 ----------
942 arr_or_dtype : array-like
943 The array or dtype to check.
945 Returns
946 -------
947 boolean
948 Whether or not the array or dtype is of the int64 dtype.
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.
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 """
984 return _is_dtype_type(arr_or_dtype, classes(np.int64))
987def is_datetime64_any_dtype(arr_or_dtype) -> bool:
988 """
989 Check whether the provided array or dtype is of the datetime64 dtype.
991 Parameters
992 ----------
993 arr_or_dtype : array-like
994 The array or dtype to check.
996 Returns
997 -------
998 boolean
999 Whether or not the array or dtype is of the datetime64 dtype.
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 """
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)
1027def is_datetime64_ns_dtype(arr_or_dtype) -> bool:
1028 """
1029 Check whether the provided array or dtype is of the datetime64[ns] dtype.
1031 Parameters
1032 ----------
1033 arr_or_dtype : array-like
1034 The array or dtype to check.
1036 Returns
1037 -------
1038 boolean
1039 Whether or not the array or dtype is of the datetime64[ns] dtype.
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 """
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
1077def is_timedelta64_ns_dtype(arr_or_dtype) -> bool:
1078 """
1079 Check whether the provided array or dtype is of the timedelta64[ns] dtype.
1081 This is a very specific dtype, so generic ones like `np.timedelta64`
1082 will return False if passed into this function.
1084 Parameters
1085 ----------
1086 arr_or_dtype : array-like
1087 The array or dtype to check.
1089 Returns
1090 -------
1091 boolean
1092 Whether or not the array or dtype is of the timedelta64[ns] dtype.
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)
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.
1113 Parameters
1114 ----------
1115 arr_or_dtype : array-like
1116 The array or dtype to check.
1118 Returns
1119 -------
1120 boolean
1121 Whether or not the array or dtype is of a timedelta64,
1122 or datetime64 dtype.
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 """
1144 return _is_dtype_type(arr_or_dtype, classes(np.datetime64, np.timedelta64))
1147def _is_unorderable_exception(e: TypeError) -> bool:
1148 """
1149 Check if the exception raised is an unorderable exception.
1151 Parameters
1152 ----------
1153 e : Exception or sub-class
1154 The exception object to check.
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)
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.
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.
1178 Returns
1179 -------
1180 boolean
1181 Whether we return a comparing a string-like object to a numeric array.
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 """
1205 is_a_array = isinstance(a, np.ndarray)
1206 is_b_array = isinstance(b, np.ndarray)
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)
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)
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 )
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.
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.
1237 Returns
1238 -------
1239 boolean
1240 Whether we return a comparing a datetime-like to a numeric object.
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 """
1266 if not hasattr(a, "dtype"):
1267 a = np.asarray(a)
1268 if not hasattr(b, "dtype"):
1269 b = np.asarray(b)
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)
1277 return (needs_i8_conversion(a) and is_numeric(b)) or (
1278 needs_i8_conversion(b) and is_numeric(a)
1279 )
1282def needs_i8_conversion(arr_or_dtype) -> bool:
1283 """
1284 Check whether the array or dtype should be converted to int64.
1286 An array-like or dtype "needs" such a conversion if the array-like
1287 or dtype is of a datetime-like dtype
1289 Parameters
1290 ----------
1291 arr_or_dtype : array-like
1292 The array or dtype to check.
1294 Returns
1295 -------
1296 boolean
1297 Whether or not the array or dtype should be converted to int64.
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 """
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 )
1326def is_numeric_dtype(arr_or_dtype) -> bool:
1327 """
1328 Check whether the provided array or dtype is of a numeric dtype.
1330 Parameters
1331 ----------
1332 arr_or_dtype : array-like
1333 The array or dtype to check.
1335 Returns
1336 -------
1337 boolean
1338 Whether or not the array or dtype is of a numeric dtype.
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 """
1364 return _is_dtype_type(
1365 arr_or_dtype, classes_and_not_datetimelike(np.number, np.bool_)
1366 )
1369def is_string_like_dtype(arr_or_dtype) -> bool:
1370 """
1371 Check whether the provided array or dtype is of a string-like dtype.
1373 Unlike `is_string_dtype`, the object dtype is excluded because it
1374 is a mixed dtype.
1376 Parameters
1377 ----------
1378 arr_or_dtype : array-like
1379 The array or dtype to check.
1381 Returns
1382 -------
1383 boolean
1384 Whether or not the array or dtype is of the string dtype.
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 """
1398 return _is_dtype(arr_or_dtype, lambda dtype: dtype.kind in ("S", "U"))
1401def is_float_dtype(arr_or_dtype) -> bool:
1402 """
1403 Check whether the provided array or dtype is of a float dtype.
1405 This function is internal and should not be exposed in the public API.
1407 Parameters
1408 ----------
1409 arr_or_dtype : array-like
1410 The array or dtype to check.
1412 Returns
1413 -------
1414 boolean
1415 Whether or not the array or dtype is of a float dtype.
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))
1435def is_bool_dtype(arr_or_dtype) -> bool:
1436 """
1437 Check whether the provided array or dtype is of a boolean dtype.
1439 Parameters
1440 ----------
1441 arr_or_dtype : array-like
1442 The array or dtype to check.
1444 Returns
1445 -------
1446 boolean
1447 Whether or not the array or dtype is of a boolean dtype.
1449 Notes
1450 -----
1451 An ExtensionArray is considered boolean when the ``_is_boolean``
1452 attribute is set to True.
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
1482 if isinstance(arr_or_dtype, CategoricalDtype):
1483 arr_or_dtype = arr_or_dtype.categories
1484 # now we use the special definition for Index
1486 if isinstance(arr_or_dtype, ABCIndexClass):
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
1497 return issubclass(dtype.type, np.bool_)
1500def is_extension_type(arr) -> bool:
1501 """
1502 Check whether an array-like is of a pandas extension class instance.
1504 .. deprecated:: 1.0.0
1505 Use ``is_extension_array_dtype`` instead.
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.
1511 Parameters
1512 ----------
1513 arr : array-like
1514 The array-like to check.
1516 Returns
1517 -------
1518 boolean
1519 Whether or not the array-like is of a pandas extension class instance.
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 )
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
1565def is_extension_array_dtype(arr_or_dtype) -> bool:
1566 """
1567 Check if an object is a pandas extension array type.
1569 See the :ref:`Use Guide <extending.extension-types>` for more.
1571 Parameters
1572 ----------
1573 arr_or_dtype : object
1574 For array-like input, the ``.dtype`` attribute will
1575 be extracted.
1577 Returns
1578 -------
1579 bool
1580 Whether the `arr_or_dtype` is an extension array type.
1582 Notes
1583 -----
1584 This checks whether an object implements the pandas extension
1585 array interface. In pandas, this includes:
1587 * Categorical
1588 * Sparse
1589 * Interval
1590 * Period
1591 * DatetimeArray
1592 * TimedeltaArray
1594 Third-party libraries may implement arrays or types satisfying
1595 this interface as well.
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
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
1614def is_complex_dtype(arr_or_dtype) -> bool:
1615 """
1616 Check whether the provided array or dtype is of a complex dtype.
1618 Parameters
1619 ----------
1620 arr_or_dtype : array-like
1621 The array or dtype to check.
1623 Returns
1624 -------
1625 boolean
1626 Whether or not the array or dtype is of a complex dtype.
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 """
1644 return _is_dtype_type(arr_or_dtype, classes(np.complexfloating))
1647def _is_dtype(arr_or_dtype, condition) -> bool:
1648 """
1649 Return a boolean if the condition is satisfied for the arr_or_dtype.
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]]
1657 Returns
1658 -------
1659 bool
1661 """
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)
1672def _get_dtype(arr_or_dtype):
1673 """
1674 Get the dtype instance associated with an array
1675 or dtype object.
1677 Parameters
1678 ----------
1679 arr_or_dtype : array-like
1680 The array-like or dtype object whose dtype we want to extract.
1682 Returns
1683 -------
1684 obj_dtype : The extract dtype instance from the
1685 passed in array or dtype object.
1687 Raises
1688 ------
1689 TypeError : The passed in object is None.
1690 """
1692 if arr_or_dtype is None:
1693 raise TypeError("Cannot deduce dtype from null object")
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)
1701 # if we have an array-like
1702 elif hasattr(arr_or_dtype, "dtype"):
1703 arr_or_dtype = arr_or_dtype.dtype
1705 return pandas_dtype(arr_or_dtype)
1708def _is_dtype_type(arr_or_dtype, condition) -> bool:
1709 """
1710 Return a boolean if the condition is satisfied for the arr_or_dtype.
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]]
1718 Returns
1719 -------
1720 bool : if the condition is satisfied for the arr_or_dtype
1721 """
1723 if arr_or_dtype is None:
1724 return condition(type(None))
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)
1734 # if we have an array-like
1735 if hasattr(arr_or_dtype, "dtype"):
1736 arr_or_dtype = arr_or_dtype.dtype
1738 # we are not possibly a dtype
1739 elif is_list_like(arr_or_dtype):
1740 return condition(type(None))
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))
1748 return False
1750 return condition(tipo)
1753def infer_dtype_from_object(dtype):
1754 """
1755 Get a numpy dtype.type-style object for a dtype object.
1757 This methods also includes handling of the datetime64[ns] and
1758 datetime64[ns, TZ] objects.
1760 If no dtype can be found, we return ``object``.
1762 Parameters
1763 ----------
1764 dtype : dtype, type
1765 The dtype object whose numpy dtype.type-style
1766 object we want to extract.
1768 Returns
1769 -------
1770 dtype_object : The extracted numpy dtype.type-style object.
1771 """
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
1785 try:
1786 dtype = pandas_dtype(dtype)
1787 except TypeError:
1788 pass
1790 if is_extension_array_dtype(dtype):
1791 return dtype.type
1792 elif isinstance(dtype, str):
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
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
1814 return infer_dtype_from_object(np.dtype(dtype))
1817def _validate_date_like_dtype(dtype) -> None:
1818 """
1819 Check whether the dtype is a date-like dtype. Raises an error if invalid.
1821 Parameters
1822 ----------
1823 dtype : dtype, type
1824 The dtype to check.
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 """
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 )
1844def pandas_dtype(dtype):
1845 """
1846 Convert input into a pandas only dtype object or a numpy dtype object.
1848 Parameters
1849 ----------
1850 dtype : object to be converted
1852 Returns
1853 -------
1854 np.dtype or a pandas dtype
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
1866 # registered extension types
1867 result = registry.find(dtype)
1868 if result is not None:
1869 return result
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")
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")
1891 return npdtype