Coverage for /var/srv/projects/api.amasfac.comuna18.com/tmp/venv/lib/python3.9/site-packages/pandas/core/dtypes/common.py: 19%
333 statements
« prev ^ index » next coverage.py v6.4.4, created at 2023-07-17 14:22 -0600
1"""
2Common type operations.
3"""
4from __future__ import annotations
6from typing import (
7 Any,
8 Callable,
9)
10import warnings
12import numpy as np
14from pandas._libs import (
15 Interval,
16 Period,
17 algos,
18 lib,
19)
20from pandas._libs.tslibs import conversion
21from pandas._typing import (
22 ArrayLike,
23 DtypeObj,
24)
25from pandas.util._exceptions import find_stack_level
27from pandas.core.dtypes.base import _registry as registry
28from pandas.core.dtypes.dtypes import (
29 CategoricalDtype,
30 DatetimeTZDtype,
31 ExtensionDtype,
32 IntervalDtype,
33 PeriodDtype,
34)
35from pandas.core.dtypes.generic import (
36 ABCCategorical,
37 ABCIndex,
38)
39from pandas.core.dtypes.inference import (
40 is_array_like,
41 is_bool,
42 is_complex,
43 is_dataclass,
44 is_decimal,
45 is_dict_like,
46 is_file_like,
47 is_float,
48 is_hashable,
49 is_integer,
50 is_interval,
51 is_iterator,
52 is_list_like,
53 is_named_tuple,
54 is_nested_list_like,
55 is_number,
56 is_re,
57 is_re_compilable,
58 is_scalar,
59 is_sequence,
60)
62DT64NS_DTYPE = conversion.DT64NS_DTYPE
63TD64NS_DTYPE = conversion.TD64NS_DTYPE
64INT64_DTYPE = np.dtype(np.int64)
66# oh the troubles to reduce import time
67_is_scipy_sparse = None
69ensure_float64 = algos.ensure_float64
72def ensure_float(arr):
73 """
74 Ensure that an array object has a float dtype if possible.
76 Parameters
77 ----------
78 arr : array-like
79 The array whose data type we want to enforce as float.
81 Returns
82 -------
83 float_arr : The original array cast to the float dtype if
84 possible. Otherwise, the original array is returned.
85 """
86 if is_extension_array_dtype(arr.dtype):
87 if is_float_dtype(arr.dtype):
88 arr = arr.to_numpy(dtype=arr.dtype.numpy_dtype, na_value=np.nan)
89 else:
90 arr = arr.to_numpy(dtype="float64", na_value=np.nan)
91 elif issubclass(arr.dtype.type, (np.integer, np.bool_)):
92 arr = arr.astype(float)
93 return arr
96ensure_int64 = algos.ensure_int64
97ensure_int32 = algos.ensure_int32
98ensure_int16 = algos.ensure_int16
99ensure_int8 = algos.ensure_int8
100ensure_platform_int = algos.ensure_platform_int
101ensure_object = algos.ensure_object
102ensure_uint64 = algos.ensure_uint64
105def ensure_str(value: bytes | Any) -> str:
106 """
107 Ensure that bytes and non-strings get converted into ``str`` objects.
108 """
109 if isinstance(value, bytes):
110 value = value.decode("utf-8")
111 elif not isinstance(value, str):
112 value = str(value)
113 return value
116def ensure_python_int(value: int | np.integer) -> int:
117 """
118 Ensure that a value is a python int.
120 Parameters
121 ----------
122 value: int or numpy.integer
124 Returns
125 -------
126 int
128 Raises
129 ------
130 TypeError: if the value isn't an int or can't be converted to one.
131 """
132 if not (is_integer(value) or is_float(value)):
133 if not is_scalar(value):
134 raise TypeError(
135 f"Value needs to be a scalar value, was type {type(value).__name__}"
136 )
137 raise TypeError(f"Wrong type {type(value)} for value {value}")
138 try:
139 new_value = int(value)
140 assert new_value == value
141 except (TypeError, ValueError, AssertionError) as err:
142 raise TypeError(f"Wrong type {type(value)} for value {value}") from err
143 return new_value
146def classes(*klasses) -> Callable:
147 """Evaluate if the tipo is a subclass of the klasses."""
148 return lambda tipo: issubclass(tipo, klasses)
151def classes_and_not_datetimelike(*klasses) -> Callable:
152 """
153 Evaluate if the tipo is a subclass of the klasses
154 and not a datetimelike.
155 """
156 return lambda tipo: (
157 issubclass(tipo, klasses)
158 and not issubclass(tipo, (np.datetime64, np.timedelta64))
159 )
162def is_object_dtype(arr_or_dtype) -> bool:
163 """
164 Check whether an array-like or dtype is of the object dtype.
166 Parameters
167 ----------
168 arr_or_dtype : array-like or dtype
169 The array-like or dtype to check.
171 Returns
172 -------
173 boolean
174 Whether or not the array-like or dtype is of the object dtype.
176 Examples
177 --------
178 >>> is_object_dtype(object)
179 True
180 >>> is_object_dtype(int)
181 False
182 >>> is_object_dtype(np.array([], dtype=object))
183 True
184 >>> is_object_dtype(np.array([], dtype=int))
185 False
186 >>> is_object_dtype([1, 2, 3])
187 False
188 """
189 return _is_dtype_type(arr_or_dtype, classes(np.object_))
192def is_sparse(arr) -> bool:
193 """
194 Check whether an array-like is a 1-D pandas sparse array.
196 Check that the one-dimensional array-like is a pandas sparse array.
197 Returns True if it is a pandas sparse array, not another type of
198 sparse array.
200 Parameters
201 ----------
202 arr : array-like
203 Array-like to check.
205 Returns
206 -------
207 bool
208 Whether or not the array-like is a pandas sparse array.
210 Examples
211 --------
212 Returns `True` if the parameter is a 1-D pandas sparse array.
214 >>> is_sparse(pd.arrays.SparseArray([0, 0, 1, 0]))
215 True
216 >>> is_sparse(pd.Series(pd.arrays.SparseArray([0, 0, 1, 0])))
217 True
219 Returns `False` if the parameter is not sparse.
221 >>> is_sparse(np.array([0, 0, 1, 0]))
222 False
223 >>> is_sparse(pd.Series([0, 1, 0, 0]))
224 False
226 Returns `False` if the parameter is not a pandas sparse array.
228 >>> from scipy.sparse import bsr_matrix
229 >>> is_sparse(bsr_matrix([0, 1, 0, 0]))
230 False
232 Returns `False` if the parameter has more than one dimension.
233 """
234 from pandas.core.arrays.sparse import SparseDtype
236 dtype = getattr(arr, "dtype", arr)
237 return isinstance(dtype, SparseDtype)
240def is_scipy_sparse(arr) -> bool:
241 """
242 Check whether an array-like is a scipy.sparse.spmatrix instance.
244 Parameters
245 ----------
246 arr : array-like
247 The array-like to check.
249 Returns
250 -------
251 boolean
252 Whether or not the array-like is a scipy.sparse.spmatrix instance.
254 Notes
255 -----
256 If scipy is not installed, this function will always return False.
258 Examples
259 --------
260 >>> from scipy.sparse import bsr_matrix
261 >>> is_scipy_sparse(bsr_matrix([1, 2, 3]))
262 True
263 >>> is_scipy_sparse(pd.arrays.SparseArray([1, 2, 3]))
264 False
265 """
266 global _is_scipy_sparse
268 if _is_scipy_sparse is None:
269 try:
270 from scipy.sparse import issparse as _is_scipy_sparse
271 except ImportError:
272 _is_scipy_sparse = lambda _: False
274 assert _is_scipy_sparse is not None
275 return _is_scipy_sparse(arr)
278def is_categorical(arr) -> bool:
279 """
280 Check whether an array-like is a Categorical instance.
282 .. deprecated:: 1.1.0
283 Use ``is_categorical_dtype`` instead.
285 Parameters
286 ----------
287 arr : array-like
288 The array-like to check.
290 Returns
291 -------
292 boolean
293 Whether or not the array-like is of a Categorical instance.
295 Examples
296 --------
297 >>> is_categorical([1, 2, 3])
298 False
300 Categoricals, Series Categoricals, and CategoricalIndex will return True.
302 >>> cat = pd.Categorical([1, 2, 3])
303 >>> is_categorical(cat)
304 True
305 >>> is_categorical(pd.Series(cat))
306 True
307 >>> is_categorical(pd.CategoricalIndex([1, 2, 3]))
308 True
309 """
310 warnings.warn(
311 "is_categorical is deprecated and will be removed in a future version. "
312 "Use is_categorical_dtype instead.",
313 FutureWarning,
314 stacklevel=find_stack_level(),
315 )
316 return isinstance(arr, ABCCategorical) or is_categorical_dtype(arr)
319def is_datetime64_dtype(arr_or_dtype) -> bool:
320 """
321 Check whether an array-like or dtype is of the datetime64 dtype.
323 Parameters
324 ----------
325 arr_or_dtype : array-like or dtype
326 The array-like or dtype to check.
328 Returns
329 -------
330 boolean
331 Whether or not the array-like or dtype is of the datetime64 dtype.
333 Examples
334 --------
335 >>> is_datetime64_dtype(object)
336 False
337 >>> is_datetime64_dtype(np.datetime64)
338 True
339 >>> is_datetime64_dtype(np.array([], dtype=int))
340 False
341 >>> is_datetime64_dtype(np.array([], dtype=np.datetime64))
342 True
343 >>> is_datetime64_dtype([1, 2, 3])
344 False
345 """
346 if isinstance(arr_or_dtype, np.dtype):
347 # GH#33400 fastpath for dtype object
348 return arr_or_dtype.kind == "M"
349 return _is_dtype_type(arr_or_dtype, classes(np.datetime64))
352def is_datetime64tz_dtype(arr_or_dtype) -> bool:
353 """
354 Check whether an array-like or dtype is of a DatetimeTZDtype dtype.
356 Parameters
357 ----------
358 arr_or_dtype : array-like or dtype
359 The array-like or dtype to check.
361 Returns
362 -------
363 boolean
364 Whether or not the array-like or dtype is of a DatetimeTZDtype dtype.
366 Examples
367 --------
368 >>> is_datetime64tz_dtype(object)
369 False
370 >>> is_datetime64tz_dtype([1, 2, 3])
371 False
372 >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3])) # tz-naive
373 False
374 >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
375 True
377 >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern")
378 >>> s = pd.Series([], dtype=dtype)
379 >>> is_datetime64tz_dtype(dtype)
380 True
381 >>> is_datetime64tz_dtype(s)
382 True
383 """
384 if isinstance(arr_or_dtype, ExtensionDtype):
385 # GH#33400 fastpath for dtype object
386 return arr_or_dtype.kind == "M"
388 if arr_or_dtype is None:
389 return False
390 return DatetimeTZDtype.is_dtype(arr_or_dtype)
393def is_timedelta64_dtype(arr_or_dtype) -> bool:
394 """
395 Check whether an array-like or dtype is of the timedelta64 dtype.
397 Parameters
398 ----------
399 arr_or_dtype : array-like or dtype
400 The array-like or dtype to check.
402 Returns
403 -------
404 boolean
405 Whether or not the array-like or dtype is of the timedelta64 dtype.
407 Examples
408 --------
409 >>> is_timedelta64_dtype(object)
410 False
411 >>> is_timedelta64_dtype(np.timedelta64)
412 True
413 >>> is_timedelta64_dtype([1, 2, 3])
414 False
415 >>> is_timedelta64_dtype(pd.Series([], dtype="timedelta64[ns]"))
416 True
417 >>> is_timedelta64_dtype('0 days')
418 False
419 """
420 if isinstance(arr_or_dtype, np.dtype):
421 # GH#33400 fastpath for dtype object
422 return arr_or_dtype.kind == "m"
424 return _is_dtype_type(arr_or_dtype, classes(np.timedelta64))
427def is_period_dtype(arr_or_dtype) -> bool:
428 """
429 Check whether an array-like or dtype is of the Period dtype.
431 Parameters
432 ----------
433 arr_or_dtype : array-like or dtype
434 The array-like or dtype to check.
436 Returns
437 -------
438 boolean
439 Whether or not the array-like or dtype is of the Period dtype.
441 Examples
442 --------
443 >>> is_period_dtype(object)
444 False
445 >>> is_period_dtype(PeriodDtype(freq="D"))
446 True
447 >>> is_period_dtype([1, 2, 3])
448 False
449 >>> is_period_dtype(pd.Period("2017-01-01"))
450 False
451 >>> is_period_dtype(pd.PeriodIndex([], freq="A"))
452 True
453 """
454 if isinstance(arr_or_dtype, ExtensionDtype):
455 # GH#33400 fastpath for dtype object
456 return arr_or_dtype.type is Period
458 if arr_or_dtype is None:
459 return False
460 return PeriodDtype.is_dtype(arr_or_dtype)
463def is_interval_dtype(arr_or_dtype) -> bool:
464 """
465 Check whether an array-like or dtype is of the Interval dtype.
467 Parameters
468 ----------
469 arr_or_dtype : array-like or dtype
470 The array-like or dtype to check.
472 Returns
473 -------
474 boolean
475 Whether or not the array-like or dtype is of the Interval dtype.
477 Examples
478 --------
479 >>> is_interval_dtype(object)
480 False
481 >>> is_interval_dtype(IntervalDtype())
482 True
483 >>> is_interval_dtype([1, 2, 3])
484 False
485 >>>
486 >>> interval = pd.Interval(1, 2, closed="right")
487 >>> is_interval_dtype(interval)
488 False
489 >>> is_interval_dtype(pd.IntervalIndex([interval]))
490 True
491 """
492 if isinstance(arr_or_dtype, ExtensionDtype):
493 # GH#33400 fastpath for dtype object
494 return arr_or_dtype.type is Interval
496 if arr_or_dtype is None:
497 return False
498 return IntervalDtype.is_dtype(arr_or_dtype)
501def is_categorical_dtype(arr_or_dtype) -> bool:
502 """
503 Check whether an array-like or dtype is of the Categorical dtype.
505 Parameters
506 ----------
507 arr_or_dtype : array-like or dtype
508 The array-like or dtype to check.
510 Returns
511 -------
512 boolean
513 Whether or not the array-like or dtype is of the Categorical dtype.
515 Examples
516 --------
517 >>> is_categorical_dtype(object)
518 False
519 >>> is_categorical_dtype(CategoricalDtype())
520 True
521 >>> is_categorical_dtype([1, 2, 3])
522 False
523 >>> is_categorical_dtype(pd.Categorical([1, 2, 3]))
524 True
525 >>> is_categorical_dtype(pd.CategoricalIndex([1, 2, 3]))
526 True
527 """
528 if isinstance(arr_or_dtype, ExtensionDtype):
529 # GH#33400 fastpath for dtype object
530 return arr_or_dtype.name == "category"
532 if arr_or_dtype is None:
533 return False
534 return CategoricalDtype.is_dtype(arr_or_dtype)
537def is_string_or_object_np_dtype(dtype: np.dtype) -> bool:
538 """
539 Faster alternative to is_string_dtype, assumes we have a np.dtype object.
540 """
541 return dtype == object or dtype.kind in "SU"
544def is_string_dtype(arr_or_dtype) -> bool:
545 """
546 Check whether the provided array or dtype is of the string dtype.
548 Parameters
549 ----------
550 arr_or_dtype : array-like or dtype
551 The array or dtype to check.
553 Returns
554 -------
555 boolean
556 Whether or not the array or dtype is of the string dtype.
558 Examples
559 --------
560 >>> is_string_dtype(str)
561 True
562 >>> is_string_dtype(object)
563 True
564 >>> is_string_dtype(int)
565 False
566 >>>
567 >>> is_string_dtype(np.array(['a', 'b']))
568 True
569 >>> is_string_dtype(pd.Series([1, 2]))
570 False
571 """
572 # TODO: gh-15585: consider making the checks stricter.
573 def condition(dtype) -> bool:
574 return dtype.kind in ("O", "S", "U") and not is_excluded_dtype(dtype)
576 def is_excluded_dtype(dtype) -> bool:
577 """
578 These have kind = "O" but aren't string dtypes so need to be explicitly excluded
579 """
580 return isinstance(dtype, (PeriodDtype, IntervalDtype, CategoricalDtype))
582 return _is_dtype(arr_or_dtype, condition)
585def is_dtype_equal(source, target) -> bool:
586 """
587 Check if two dtypes are equal.
589 Parameters
590 ----------
591 source : The first dtype to compare
592 target : The second dtype to compare
594 Returns
595 -------
596 boolean
597 Whether or not the two dtypes are equal.
599 Examples
600 --------
601 >>> is_dtype_equal(int, float)
602 False
603 >>> is_dtype_equal("int", int)
604 True
605 >>> is_dtype_equal(object, "category")
606 False
607 >>> is_dtype_equal(CategoricalDtype(), "category")
608 True
609 >>> is_dtype_equal(DatetimeTZDtype(tz="UTC"), "datetime64")
610 False
611 """
612 if isinstance(target, str):
613 if not isinstance(source, str):
614 # GH#38516 ensure we get the same behavior from
615 # is_dtype_equal(CDT, "category") and CDT == "category"
616 try:
617 src = get_dtype(source)
618 if isinstance(src, ExtensionDtype):
619 return src == target
620 except (TypeError, AttributeError, ImportError):
621 return False
622 elif isinstance(source, str):
623 return is_dtype_equal(target, source)
625 try:
626 source = get_dtype(source)
627 target = get_dtype(target)
628 return source == target
629 except (TypeError, AttributeError, ImportError):
631 # invalid comparison
632 # object == category will hit this
633 return False
636def is_any_int_dtype(arr_or_dtype) -> bool:
637 """
638 Check whether the provided array or dtype is of an integer dtype.
640 In this function, timedelta64 instances are also considered "any-integer"
641 type objects and will return True.
643 This function is internal and should not be exposed in the public API.
645 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
646 as integer by this function.
648 Parameters
649 ----------
650 arr_or_dtype : array-like or dtype
651 The array or dtype to check.
653 Returns
654 -------
655 boolean
656 Whether or not the array or dtype is of an integer dtype.
658 Examples
659 --------
660 >>> is_any_int_dtype(str)
661 False
662 >>> is_any_int_dtype(int)
663 True
664 >>> is_any_int_dtype(float)
665 False
666 >>> is_any_int_dtype(np.uint64)
667 True
668 >>> is_any_int_dtype(np.datetime64)
669 False
670 >>> is_any_int_dtype(np.timedelta64)
671 True
672 >>> is_any_int_dtype(np.array(['a', 'b']))
673 False
674 >>> is_any_int_dtype(pd.Series([1, 2]))
675 True
676 >>> is_any_int_dtype(np.array([], dtype=np.timedelta64))
677 True
678 >>> is_any_int_dtype(pd.Index([1, 2.])) # float
679 False
680 """
681 return _is_dtype_type(arr_or_dtype, classes(np.integer, np.timedelta64))
684def is_integer_dtype(arr_or_dtype) -> bool:
685 """
686 Check whether the provided array or dtype is of an integer dtype.
688 Unlike in `is_any_int_dtype`, timedelta64 instances will return False.
690 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
691 as integer by this function.
693 Parameters
694 ----------
695 arr_or_dtype : array-like or dtype
696 The array or dtype to check.
698 Returns
699 -------
700 boolean
701 Whether or not the array or dtype is of an integer dtype and
702 not an instance of timedelta64.
704 Examples
705 --------
706 >>> is_integer_dtype(str)
707 False
708 >>> is_integer_dtype(int)
709 True
710 >>> is_integer_dtype(float)
711 False
712 >>> is_integer_dtype(np.uint64)
713 True
714 >>> is_integer_dtype('int8')
715 True
716 >>> is_integer_dtype('Int8')
717 True
718 >>> is_integer_dtype(pd.Int8Dtype)
719 True
720 >>> is_integer_dtype(np.datetime64)
721 False
722 >>> is_integer_dtype(np.timedelta64)
723 False
724 >>> is_integer_dtype(np.array(['a', 'b']))
725 False
726 >>> is_integer_dtype(pd.Series([1, 2]))
727 True
728 >>> is_integer_dtype(np.array([], dtype=np.timedelta64))
729 False
730 >>> is_integer_dtype(pd.Index([1, 2.])) # float
731 False
732 """
733 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.integer))
736def is_signed_integer_dtype(arr_or_dtype) -> bool:
737 """
738 Check whether the provided array or dtype is of a signed integer dtype.
740 Unlike in `is_any_int_dtype`, timedelta64 instances will return False.
742 The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
743 as integer by this function.
745 Parameters
746 ----------
747 arr_or_dtype : array-like or dtype
748 The array or dtype to check.
750 Returns
751 -------
752 boolean
753 Whether or not the array or dtype is of a signed integer dtype
754 and not an instance of timedelta64.
756 Examples
757 --------
758 >>> is_signed_integer_dtype(str)
759 False
760 >>> is_signed_integer_dtype(int)
761 True
762 >>> is_signed_integer_dtype(float)
763 False
764 >>> is_signed_integer_dtype(np.uint64) # unsigned
765 False
766 >>> is_signed_integer_dtype('int8')
767 True
768 >>> is_signed_integer_dtype('Int8')
769 True
770 >>> is_signed_integer_dtype(pd.Int8Dtype)
771 True
772 >>> is_signed_integer_dtype(np.datetime64)
773 False
774 >>> is_signed_integer_dtype(np.timedelta64)
775 False
776 >>> is_signed_integer_dtype(np.array(['a', 'b']))
777 False
778 >>> is_signed_integer_dtype(pd.Series([1, 2]))
779 True
780 >>> is_signed_integer_dtype(np.array([], dtype=np.timedelta64))
781 False
782 >>> is_signed_integer_dtype(pd.Index([1, 2.])) # float
783 False
784 >>> is_signed_integer_dtype(np.array([1, 2], dtype=np.uint32)) # unsigned
785 False
786 """
787 return _is_dtype_type(arr_or_dtype, classes_and_not_datetimelike(np.signedinteger))
790def is_unsigned_integer_dtype(arr_or_dtype) -> bool:
791 """
792 Check whether the provided array or dtype is of an unsigned integer dtype.
794 The nullable Integer dtypes (e.g. pandas.UInt64Dtype) are also
795 considered as integer by this function.
797 Parameters
798 ----------
799 arr_or_dtype : array-like or dtype
800 The array or dtype to check.
802 Returns
803 -------
804 boolean
805 Whether or not the array or dtype is of an unsigned integer dtype.
807 Examples
808 --------
809 >>> is_unsigned_integer_dtype(str)
810 False
811 >>> is_unsigned_integer_dtype(int) # signed
812 False
813 >>> is_unsigned_integer_dtype(float)
814 False
815 >>> is_unsigned_integer_dtype(np.uint64)
816 True
817 >>> is_unsigned_integer_dtype('uint8')
818 True
819 >>> is_unsigned_integer_dtype('UInt8')
820 True
821 >>> is_unsigned_integer_dtype(pd.UInt8Dtype)
822 True
823 >>> is_unsigned_integer_dtype(np.array(['a', 'b']))
824 False
825 >>> is_unsigned_integer_dtype(pd.Series([1, 2])) # signed
826 False
827 >>> is_unsigned_integer_dtype(pd.Index([1, 2.])) # float
828 False
829 >>> is_unsigned_integer_dtype(np.array([1, 2], dtype=np.uint32))
830 True
831 """
832 return _is_dtype_type(
833 arr_or_dtype, classes_and_not_datetimelike(np.unsignedinteger)
834 )
837def is_int64_dtype(arr_or_dtype) -> bool:
838 """
839 Check whether the provided array or dtype is of the int64 dtype.
841 Parameters
842 ----------
843 arr_or_dtype : array-like or dtype
844 The array or dtype to check.
846 Returns
847 -------
848 boolean
849 Whether or not the array or dtype is of the int64 dtype.
851 Notes
852 -----
853 Depending on system architecture, the return value of `is_int64_dtype(
854 int)` will be True if the OS uses 64-bit integers and False if the OS
855 uses 32-bit integers.
857 Examples
858 --------
859 >>> is_int64_dtype(str)
860 False
861 >>> is_int64_dtype(np.int32)
862 False
863 >>> is_int64_dtype(np.int64)
864 True
865 >>> is_int64_dtype('int8')
866 False
867 >>> is_int64_dtype('Int8')
868 False
869 >>> is_int64_dtype(pd.Int64Dtype)
870 True
871 >>> is_int64_dtype(float)
872 False
873 >>> is_int64_dtype(np.uint64) # unsigned
874 False
875 >>> is_int64_dtype(np.array(['a', 'b']))
876 False
877 >>> is_int64_dtype(np.array([1, 2], dtype=np.int64))
878 True
879 >>> is_int64_dtype(pd.Index([1, 2.])) # float
880 False
881 >>> is_int64_dtype(np.array([1, 2], dtype=np.uint32)) # unsigned
882 False
883 """
884 return _is_dtype_type(arr_or_dtype, classes(np.int64))
887def is_datetime64_any_dtype(arr_or_dtype) -> bool:
888 """
889 Check whether the provided array or dtype is of the datetime64 dtype.
891 Parameters
892 ----------
893 arr_or_dtype : array-like or dtype
894 The array or dtype to check.
896 Returns
897 -------
898 bool
899 Whether or not the array or dtype is of the datetime64 dtype.
901 Examples
902 --------
903 >>> is_datetime64_any_dtype(str)
904 False
905 >>> is_datetime64_any_dtype(int)
906 False
907 >>> is_datetime64_any_dtype(np.datetime64) # can be tz-naive
908 True
909 >>> is_datetime64_any_dtype(DatetimeTZDtype("ns", "US/Eastern"))
910 True
911 >>> is_datetime64_any_dtype(np.array(['a', 'b']))
912 False
913 >>> is_datetime64_any_dtype(np.array([1, 2]))
914 False
915 >>> is_datetime64_any_dtype(np.array([], dtype="datetime64[ns]"))
916 True
917 >>> is_datetime64_any_dtype(pd.DatetimeIndex([1, 2, 3], dtype="datetime64[ns]"))
918 True
919 """
920 if isinstance(arr_or_dtype, (np.dtype, ExtensionDtype)):
921 # GH#33400 fastpath for dtype object
922 return arr_or_dtype.kind == "M"
924 if arr_or_dtype is None:
925 return False
926 return is_datetime64_dtype(arr_or_dtype) or is_datetime64tz_dtype(arr_or_dtype)
929def is_datetime64_ns_dtype(arr_or_dtype) -> bool:
930 """
931 Check whether the provided array or dtype is of the datetime64[ns] dtype.
933 Parameters
934 ----------
935 arr_or_dtype : array-like or dtype
936 The array or dtype to check.
938 Returns
939 -------
940 bool
941 Whether or not the array or dtype is of the datetime64[ns] dtype.
943 Examples
944 --------
945 >>> is_datetime64_ns_dtype(str)
946 False
947 >>> is_datetime64_ns_dtype(int)
948 False
949 >>> is_datetime64_ns_dtype(np.datetime64) # no unit
950 False
951 >>> is_datetime64_ns_dtype(DatetimeTZDtype("ns", "US/Eastern"))
952 True
953 >>> is_datetime64_ns_dtype(np.array(['a', 'b']))
954 False
955 >>> is_datetime64_ns_dtype(np.array([1, 2]))
956 False
957 >>> is_datetime64_ns_dtype(np.array([], dtype="datetime64")) # no unit
958 False
959 >>> is_datetime64_ns_dtype(np.array([], dtype="datetime64[ps]")) # wrong unit
960 False
961 >>> is_datetime64_ns_dtype(pd.DatetimeIndex([1, 2, 3], dtype="datetime64[ns]"))
962 True
963 """
964 if arr_or_dtype is None:
965 return False
966 try:
967 tipo = get_dtype(arr_or_dtype)
968 except TypeError:
969 if is_datetime64tz_dtype(arr_or_dtype):
970 tipo = get_dtype(arr_or_dtype.dtype)
971 else:
972 return False
973 return tipo == DT64NS_DTYPE or (
974 isinstance(tipo, DatetimeTZDtype) and tipo._unit == "ns"
975 )
978def is_timedelta64_ns_dtype(arr_or_dtype) -> bool:
979 """
980 Check whether the provided array or dtype is of the timedelta64[ns] dtype.
982 This is a very specific dtype, so generic ones like `np.timedelta64`
983 will return False if passed into this function.
985 Parameters
986 ----------
987 arr_or_dtype : array-like or dtype
988 The array or dtype to check.
990 Returns
991 -------
992 boolean
993 Whether or not the array or dtype is of the timedelta64[ns] dtype.
995 Examples
996 --------
997 >>> is_timedelta64_ns_dtype(np.dtype('m8[ns]'))
998 True
999 >>> is_timedelta64_ns_dtype(np.dtype('m8[ps]')) # Wrong frequency
1000 False
1001 >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype='m8[ns]'))
1002 True
1003 >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype=np.timedelta64))
1004 False
1005 """
1006 return _is_dtype(arr_or_dtype, lambda dtype: dtype == TD64NS_DTYPE)
1009def is_datetime_or_timedelta_dtype(arr_or_dtype) -> bool:
1010 """
1011 Check whether the provided array or dtype is of
1012 a timedelta64 or datetime64 dtype.
1014 Parameters
1015 ----------
1016 arr_or_dtype : array-like or dtype
1017 The array or dtype to check.
1019 Returns
1020 -------
1021 boolean
1022 Whether or not the array or dtype is of a timedelta64,
1023 or datetime64 dtype.
1025 Examples
1026 --------
1027 >>> is_datetime_or_timedelta_dtype(str)
1028 False
1029 >>> is_datetime_or_timedelta_dtype(int)
1030 False
1031 >>> is_datetime_or_timedelta_dtype(np.datetime64)
1032 True
1033 >>> is_datetime_or_timedelta_dtype(np.timedelta64)
1034 True
1035 >>> is_datetime_or_timedelta_dtype(np.array(['a', 'b']))
1036 False
1037 >>> is_datetime_or_timedelta_dtype(pd.Series([1, 2]))
1038 False
1039 >>> is_datetime_or_timedelta_dtype(np.array([], dtype=np.timedelta64))
1040 True
1041 >>> is_datetime_or_timedelta_dtype(np.array([], dtype=np.datetime64))
1042 True
1043 """
1044 return _is_dtype_type(arr_or_dtype, classes(np.datetime64, np.timedelta64))
1047# This exists to silence numpy deprecation warnings, see GH#29553
1048def is_numeric_v_string_like(a: ArrayLike, b) -> bool:
1049 """
1050 Check if we are comparing a string-like object to a numeric ndarray.
1051 NumPy doesn't like to compare such objects, especially numeric arrays
1052 and scalar string-likes.
1054 Parameters
1055 ----------
1056 a : array-like, scalar
1057 The first object to check.
1058 b : array-like, scalar
1059 The second object to check.
1061 Returns
1062 -------
1063 boolean
1064 Whether we return a comparing a string-like object to a numeric array.
1066 Examples
1067 --------
1068 >>> is_numeric_v_string_like(np.array([1]), "foo")
1069 True
1070 >>> is_numeric_v_string_like(np.array([1, 2]), np.array(["foo"]))
1071 True
1072 >>> is_numeric_v_string_like(np.array(["foo"]), np.array([1, 2]))
1073 True
1074 >>> is_numeric_v_string_like(np.array([1]), np.array([2]))
1075 False
1076 >>> is_numeric_v_string_like(np.array(["foo"]), np.array(["foo"]))
1077 False
1078 """
1079 is_a_array = isinstance(a, np.ndarray)
1080 is_b_array = isinstance(b, np.ndarray)
1082 is_a_numeric_array = is_a_array and a.dtype.kind in ("u", "i", "f", "c", "b")
1083 is_b_numeric_array = is_b_array and b.dtype.kind in ("u", "i", "f", "c", "b")
1084 is_a_string_array = is_a_array and a.dtype.kind in ("S", "U")
1085 is_b_string_array = is_b_array and b.dtype.kind in ("S", "U")
1087 is_b_scalar_string_like = not is_b_array and isinstance(b, str)
1089 return (
1090 (is_a_numeric_array and is_b_scalar_string_like)
1091 or (is_a_numeric_array and is_b_string_array)
1092 or (is_b_numeric_array and is_a_string_array)
1093 )
1096# This exists to silence numpy deprecation warnings, see GH#29553
1097def is_datetimelike_v_numeric(a, b) -> bool:
1098 """
1099 Check if we are comparing a datetime-like object to a numeric object.
1100 By "numeric," we mean an object that is either of an int or float dtype.
1102 Parameters
1103 ----------
1104 a : array-like, scalar
1105 The first object to check.
1106 b : array-like, scalar
1107 The second object to check.
1109 Returns
1110 -------
1111 boolean
1112 Whether we return a comparing a datetime-like to a numeric object.
1114 Examples
1115 --------
1116 >>> from datetime import datetime
1117 >>> dt = np.datetime64(datetime(2017, 1, 1))
1118 >>>
1119 >>> is_datetimelike_v_numeric(1, 1)
1120 False
1121 >>> is_datetimelike_v_numeric(dt, dt)
1122 False
1123 >>> is_datetimelike_v_numeric(1, dt)
1124 True
1125 >>> is_datetimelike_v_numeric(dt, 1) # symmetric check
1126 True
1127 >>> is_datetimelike_v_numeric(np.array([dt]), 1)
1128 True
1129 >>> is_datetimelike_v_numeric(np.array([1]), dt)
1130 True
1131 >>> is_datetimelike_v_numeric(np.array([dt]), np.array([1]))
1132 True
1133 >>> is_datetimelike_v_numeric(np.array([1]), np.array([2]))
1134 False
1135 >>> is_datetimelike_v_numeric(np.array([dt]), np.array([dt]))
1136 False
1137 """
1138 if not hasattr(a, "dtype"):
1139 a = np.asarray(a)
1140 if not hasattr(b, "dtype"):
1141 b = np.asarray(b)
1143 def is_numeric(x):
1144 """
1145 Check if an object has a numeric dtype (i.e. integer or float).
1146 """
1147 return is_integer_dtype(x) or is_float_dtype(x)
1149 return (needs_i8_conversion(a) and is_numeric(b)) or (
1150 needs_i8_conversion(b) and is_numeric(a)
1151 )
1154def needs_i8_conversion(arr_or_dtype) -> bool:
1155 """
1156 Check whether the array or dtype should be converted to int64.
1158 An array-like or dtype "needs" such a conversion if the array-like
1159 or dtype is of a datetime-like dtype
1161 Parameters
1162 ----------
1163 arr_or_dtype : array-like or dtype
1164 The array or dtype to check.
1166 Returns
1167 -------
1168 boolean
1169 Whether or not the array or dtype should be converted to int64.
1171 Examples
1172 --------
1173 >>> needs_i8_conversion(str)
1174 False
1175 >>> needs_i8_conversion(np.int64)
1176 False
1177 >>> needs_i8_conversion(np.datetime64)
1178 True
1179 >>> needs_i8_conversion(np.array(['a', 'b']))
1180 False
1181 >>> needs_i8_conversion(pd.Series([1, 2]))
1182 False
1183 >>> needs_i8_conversion(pd.Series([], dtype="timedelta64[ns]"))
1184 True
1185 >>> needs_i8_conversion(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
1186 True
1187 """
1188 if arr_or_dtype is None:
1189 return False
1190 if isinstance(arr_or_dtype, np.dtype):
1191 return arr_or_dtype.kind in ["m", "M"]
1192 elif isinstance(arr_or_dtype, ExtensionDtype):
1193 return isinstance(arr_or_dtype, (PeriodDtype, DatetimeTZDtype))
1195 try:
1196 dtype = get_dtype(arr_or_dtype)
1197 except (TypeError, ValueError):
1198 return False
1199 if isinstance(dtype, np.dtype):
1200 return dtype.kind in ["m", "M"]
1201 return isinstance(dtype, (PeriodDtype, DatetimeTZDtype))
1204def is_numeric_dtype(arr_or_dtype) -> bool:
1205 """
1206 Check whether the provided array or dtype is of a numeric dtype.
1208 Parameters
1209 ----------
1210 arr_or_dtype : array-like or dtype
1211 The array or dtype to check.
1213 Returns
1214 -------
1215 boolean
1216 Whether or not the array or dtype is of a numeric dtype.
1218 Examples
1219 --------
1220 >>> is_numeric_dtype(str)
1221 False
1222 >>> is_numeric_dtype(int)
1223 True
1224 >>> is_numeric_dtype(float)
1225 True
1226 >>> is_numeric_dtype(np.uint64)
1227 True
1228 >>> is_numeric_dtype(np.datetime64)
1229 False
1230 >>> is_numeric_dtype(np.timedelta64)
1231 False
1232 >>> is_numeric_dtype(np.array(['a', 'b']))
1233 False
1234 >>> is_numeric_dtype(pd.Series([1, 2]))
1235 True
1236 >>> is_numeric_dtype(pd.Index([1, 2.]))
1237 True
1238 >>> is_numeric_dtype(np.array([], dtype=np.timedelta64))
1239 False
1240 """
1241 return _is_dtype_type(
1242 arr_or_dtype, classes_and_not_datetimelike(np.number, np.bool_)
1243 )
1246def is_float_dtype(arr_or_dtype) -> bool:
1247 """
1248 Check whether the provided array or dtype is of a float dtype.
1250 Parameters
1251 ----------
1252 arr_or_dtype : array-like or dtype
1253 The array or dtype to check.
1255 Returns
1256 -------
1257 boolean
1258 Whether or not the array or dtype is of a float dtype.
1260 Examples
1261 --------
1262 >>> is_float_dtype(str)
1263 False
1264 >>> is_float_dtype(int)
1265 False
1266 >>> is_float_dtype(float)
1267 True
1268 >>> is_float_dtype(np.array(['a', 'b']))
1269 False
1270 >>> is_float_dtype(pd.Series([1, 2]))
1271 False
1272 >>> is_float_dtype(pd.Index([1, 2.]))
1273 True
1274 """
1275 return _is_dtype_type(arr_or_dtype, classes(np.floating))
1278def is_bool_dtype(arr_or_dtype) -> bool:
1279 """
1280 Check whether the provided array or dtype is of a boolean dtype.
1282 Parameters
1283 ----------
1284 arr_or_dtype : array-like or dtype
1285 The array or dtype to check.
1287 Returns
1288 -------
1289 boolean
1290 Whether or not the array or dtype is of a boolean dtype.
1292 Notes
1293 -----
1294 An ExtensionArray is considered boolean when the ``_is_boolean``
1295 attribute is set to True.
1297 Examples
1298 --------
1299 >>> is_bool_dtype(str)
1300 False
1301 >>> is_bool_dtype(int)
1302 False
1303 >>> is_bool_dtype(bool)
1304 True
1305 >>> is_bool_dtype(np.bool_)
1306 True
1307 >>> is_bool_dtype(np.array(['a', 'b']))
1308 False
1309 >>> is_bool_dtype(pd.Series([1, 2]))
1310 False
1311 >>> is_bool_dtype(np.array([True, False]))
1312 True
1313 >>> is_bool_dtype(pd.Categorical([True, False]))
1314 True
1315 >>> is_bool_dtype(pd.arrays.SparseArray([True, False]))
1316 True
1317 """
1318 if arr_or_dtype is None:
1319 return False
1320 try:
1321 dtype = get_dtype(arr_or_dtype)
1322 except (TypeError, ValueError):
1323 return False
1325 if isinstance(dtype, CategoricalDtype):
1326 arr_or_dtype = dtype.categories
1327 # now we use the special definition for Index
1329 if isinstance(arr_or_dtype, ABCIndex):
1330 # Allow Index[object] that is all-bools or Index["boolean"]
1331 return arr_or_dtype.inferred_type == "boolean"
1332 elif isinstance(dtype, ExtensionDtype):
1333 return getattr(dtype, "_is_boolean", False)
1335 return issubclass(dtype.type, np.bool_)
1338def is_extension_type(arr) -> bool:
1339 """
1340 Check whether an array-like is of a pandas extension class instance.
1342 .. deprecated:: 1.0.0
1343 Use ``is_extension_array_dtype`` instead.
1345 Extension classes include categoricals, pandas sparse objects (i.e.
1346 classes represented within the pandas library and not ones external
1347 to it like scipy sparse matrices), and datetime-like arrays.
1349 Parameters
1350 ----------
1351 arr : array-like, scalar
1352 The array-like to check.
1354 Returns
1355 -------
1356 boolean
1357 Whether or not the array-like is of a pandas extension class instance.
1359 Examples
1360 --------
1361 >>> is_extension_type([1, 2, 3])
1362 False
1363 >>> is_extension_type(np.array([1, 2, 3]))
1364 False
1365 >>>
1366 >>> cat = pd.Categorical([1, 2, 3])
1367 >>>
1368 >>> is_extension_type(cat)
1369 True
1370 >>> is_extension_type(pd.Series(cat))
1371 True
1372 >>> is_extension_type(pd.arrays.SparseArray([1, 2, 3]))
1373 True
1374 >>> from scipy.sparse import bsr_matrix
1375 >>> is_extension_type(bsr_matrix([1, 2, 3]))
1376 False
1377 >>> is_extension_type(pd.DatetimeIndex([1, 2, 3]))
1378 False
1379 >>> is_extension_type(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
1380 True
1381 >>>
1382 >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern")
1383 >>> s = pd.Series([], dtype=dtype)
1384 >>> is_extension_type(s)
1385 True
1386 """
1387 warnings.warn(
1388 "'is_extension_type' is deprecated and will be removed in a future "
1389 "version. Use 'is_extension_array_dtype' instead.",
1390 FutureWarning,
1391 stacklevel=find_stack_level(),
1392 )
1394 if is_categorical_dtype(arr):
1395 return True
1396 elif is_sparse(arr):
1397 return True
1398 elif is_datetime64tz_dtype(arr):
1399 return True
1400 return False
1403def is_1d_only_ea_obj(obj: Any) -> bool:
1404 """
1405 ExtensionArray that does not support 2D, or more specifically that does
1406 not use HybridBlock.
1407 """
1408 from pandas.core.arrays import (
1409 DatetimeArray,
1410 ExtensionArray,
1411 PeriodArray,
1412 TimedeltaArray,
1413 )
1415 return isinstance(obj, ExtensionArray) and not isinstance(
1416 obj, (DatetimeArray, TimedeltaArray, PeriodArray)
1417 )
1420def is_1d_only_ea_dtype(dtype: DtypeObj | None) -> bool:
1421 """
1422 Analogue to is_extension_array_dtype but excluding DatetimeTZDtype.
1423 """
1424 # Note: if other EA dtypes are ever held in HybridBlock, exclude those
1425 # here too.
1426 # NB: need to check DatetimeTZDtype and not is_datetime64tz_dtype
1427 # to exclude ArrowTimestampUSDtype
1428 return isinstance(dtype, ExtensionDtype) and not isinstance(
1429 dtype, (DatetimeTZDtype, PeriodDtype)
1430 )
1433def is_extension_array_dtype(arr_or_dtype) -> bool:
1434 """
1435 Check if an object is a pandas extension array type.
1437 See the :ref:`Use Guide <extending.extension-types>` for more.
1439 Parameters
1440 ----------
1441 arr_or_dtype : object
1442 For array-like input, the ``.dtype`` attribute will
1443 be extracted.
1445 Returns
1446 -------
1447 bool
1448 Whether the `arr_or_dtype` is an extension array type.
1450 Notes
1451 -----
1452 This checks whether an object implements the pandas extension
1453 array interface. In pandas, this includes:
1455 * Categorical
1456 * Sparse
1457 * Interval
1458 * Period
1459 * DatetimeArray
1460 * TimedeltaArray
1462 Third-party libraries may implement arrays or types satisfying
1463 this interface as well.
1465 Examples
1466 --------
1467 >>> from pandas.api.types import is_extension_array_dtype
1468 >>> arr = pd.Categorical(['a', 'b'])
1469 >>> is_extension_array_dtype(arr)
1470 True
1471 >>> is_extension_array_dtype(arr.dtype)
1472 True
1474 >>> arr = np.array(['a', 'b'])
1475 >>> is_extension_array_dtype(arr.dtype)
1476 False
1477 """
1478 dtype = getattr(arr_or_dtype, "dtype", arr_or_dtype)
1479 if isinstance(dtype, ExtensionDtype):
1480 return True
1481 elif isinstance(dtype, np.dtype):
1482 return False
1483 else:
1484 return registry.find(dtype) is not None
1487def is_ea_or_datetimelike_dtype(dtype: DtypeObj | None) -> bool:
1488 """
1489 Check for ExtensionDtype, datetime64 dtype, or timedelta64 dtype.
1491 Notes
1492 -----
1493 Checks only for dtype objects, not dtype-castable strings or types.
1494 """
1495 return isinstance(dtype, ExtensionDtype) or (
1496 isinstance(dtype, np.dtype) and dtype.kind in ["m", "M"]
1497 )
1500def is_complex_dtype(arr_or_dtype) -> bool:
1501 """
1502 Check whether the provided array or dtype is of a complex dtype.
1504 Parameters
1505 ----------
1506 arr_or_dtype : array-like or dtype
1507 The array or dtype to check.
1509 Returns
1510 -------
1511 boolean
1512 Whether or not the array or dtype is of a complex dtype.
1514 Examples
1515 --------
1516 >>> is_complex_dtype(str)
1517 False
1518 >>> is_complex_dtype(int)
1519 False
1520 >>> is_complex_dtype(np.complex_)
1521 True
1522 >>> is_complex_dtype(np.array(['a', 'b']))
1523 False
1524 >>> is_complex_dtype(pd.Series([1, 2]))
1525 False
1526 >>> is_complex_dtype(np.array([1 + 1j, 5]))
1527 True
1528 """
1529 return _is_dtype_type(arr_or_dtype, classes(np.complexfloating))
1532def _is_dtype(arr_or_dtype, condition) -> bool:
1533 """
1534 Return true if the condition is satisfied for the arr_or_dtype.
1536 Parameters
1537 ----------
1538 arr_or_dtype : array-like, str, np.dtype, or ExtensionArrayType
1539 The array-like or dtype object whose dtype we want to extract.
1540 condition : callable[Union[np.dtype, ExtensionDtype]]
1542 Returns
1543 -------
1544 bool
1546 """
1547 if arr_or_dtype is None:
1548 return False
1549 try:
1550 dtype = get_dtype(arr_or_dtype)
1551 except (TypeError, ValueError):
1552 return False
1553 return condition(dtype)
1556def get_dtype(arr_or_dtype) -> DtypeObj:
1557 """
1558 Get the dtype instance associated with an array
1559 or dtype object.
1561 Parameters
1562 ----------
1563 arr_or_dtype : array-like or dtype
1564 The array-like or dtype object whose dtype we want to extract.
1566 Returns
1567 -------
1568 obj_dtype : The extract dtype instance from the
1569 passed in array or dtype object.
1571 Raises
1572 ------
1573 TypeError : The passed in object is None.
1574 """
1575 if arr_or_dtype is None:
1576 raise TypeError("Cannot deduce dtype from null object")
1578 # fastpath
1579 elif isinstance(arr_or_dtype, np.dtype):
1580 return arr_or_dtype
1581 elif isinstance(arr_or_dtype, type):
1582 return np.dtype(arr_or_dtype)
1584 # if we have an array-like
1585 elif hasattr(arr_or_dtype, "dtype"):
1586 arr_or_dtype = arr_or_dtype.dtype
1588 return pandas_dtype(arr_or_dtype)
1591def _is_dtype_type(arr_or_dtype, condition) -> bool:
1592 """
1593 Return true if the condition is satisfied for the arr_or_dtype.
1595 Parameters
1596 ----------
1597 arr_or_dtype : array-like or dtype
1598 The array-like or dtype object whose dtype we want to extract.
1599 condition : callable[Union[np.dtype, ExtensionDtypeType]]
1601 Returns
1602 -------
1603 bool : if the condition is satisfied for the arr_or_dtype
1604 """
1605 if arr_or_dtype is None:
1606 return condition(type(None))
1608 # fastpath
1609 if isinstance(arr_or_dtype, np.dtype):
1610 return condition(arr_or_dtype.type)
1611 elif isinstance(arr_or_dtype, type):
1612 if issubclass(arr_or_dtype, ExtensionDtype):
1613 arr_or_dtype = arr_or_dtype.type
1614 return condition(np.dtype(arr_or_dtype).type)
1616 # if we have an array-like
1617 if hasattr(arr_or_dtype, "dtype"):
1618 arr_or_dtype = arr_or_dtype.dtype
1620 # we are not possibly a dtype
1621 elif is_list_like(arr_or_dtype):
1622 return condition(type(None))
1624 try:
1625 tipo = pandas_dtype(arr_or_dtype).type
1626 except (TypeError, ValueError):
1627 if is_scalar(arr_or_dtype):
1628 return condition(type(None))
1630 return False
1632 return condition(tipo)
1635def infer_dtype_from_object(dtype) -> type:
1636 """
1637 Get a numpy dtype.type-style object for a dtype object.
1639 This methods also includes handling of the datetime64[ns] and
1640 datetime64[ns, TZ] objects.
1642 If no dtype can be found, we return ``object``.
1644 Parameters
1645 ----------
1646 dtype : dtype, type
1647 The dtype object whose numpy dtype.type-style
1648 object we want to extract.
1650 Returns
1651 -------
1652 type
1653 """
1654 if isinstance(dtype, type) and issubclass(dtype, np.generic):
1655 # Type object from a dtype
1657 return dtype
1658 elif isinstance(dtype, (np.dtype, ExtensionDtype)):
1659 # dtype object
1660 try:
1661 _validate_date_like_dtype(dtype)
1662 except TypeError:
1663 # Should still pass if we don't have a date-like
1664 pass
1665 return dtype.type
1667 try:
1668 dtype = pandas_dtype(dtype)
1669 except TypeError:
1670 pass
1672 if is_extension_array_dtype(dtype):
1673 return dtype.type
1674 elif isinstance(dtype, str):
1676 # TODO(jreback)
1677 # should deprecate these
1678 if dtype in ["datetimetz", "datetime64tz"]:
1679 return DatetimeTZDtype.type
1680 elif dtype in ["period"]:
1681 raise NotImplementedError
1683 if dtype in ["datetime", "timedelta"]:
1684 dtype += "64"
1685 try:
1686 return infer_dtype_from_object(getattr(np, dtype))
1687 except (AttributeError, TypeError):
1688 # Handles cases like get_dtype(int) i.e.,
1689 # Python objects that are valid dtypes
1690 # (unlike user-defined types, in general)
1691 #
1692 # TypeError handles the float16 type code of 'e'
1693 # further handle internal types
1694 pass
1696 return infer_dtype_from_object(np.dtype(dtype))
1699def _validate_date_like_dtype(dtype) -> None:
1700 """
1701 Check whether the dtype is a date-like dtype. Raises an error if invalid.
1703 Parameters
1704 ----------
1705 dtype : dtype, type
1706 The dtype to check.
1708 Raises
1709 ------
1710 TypeError : The dtype could not be casted to a date-like dtype.
1711 ValueError : The dtype is an illegal date-like dtype (e.g. the
1712 frequency provided is too specific)
1713 """
1714 try:
1715 typ = np.datetime_data(dtype)[0]
1716 except ValueError as e:
1717 raise TypeError(e) from e
1718 if typ not in ["generic", "ns"]:
1719 raise ValueError(
1720 f"{repr(dtype.name)} is too specific of a frequency, "
1721 f"try passing {repr(dtype.type.__name__)}"
1722 )
1725def validate_all_hashable(*args, error_name: str | None = None) -> None:
1726 """
1727 Return None if all args are hashable, else raise a TypeError.
1729 Parameters
1730 ----------
1731 *args
1732 Arguments to validate.
1733 error_name : str, optional
1734 The name to use if error
1736 Raises
1737 ------
1738 TypeError : If an argument is not hashable
1740 Returns
1741 -------
1742 None
1743 """
1744 if not all(is_hashable(arg) for arg in args):
1745 if error_name:
1746 raise TypeError(f"{error_name} must be a hashable type")
1747 else:
1748 raise TypeError("All elements must be hashable")
1751def pandas_dtype(dtype) -> DtypeObj:
1752 """
1753 Convert input into a pandas only dtype object or a numpy dtype object.
1755 Parameters
1756 ----------
1757 dtype : object to be converted
1759 Returns
1760 -------
1761 np.dtype or a pandas dtype
1763 Raises
1764 ------
1765 TypeError if not a dtype
1766 """
1767 # short-circuit
1768 if isinstance(dtype, np.ndarray): 1768 ↛ 1769line 1768 didn't jump to line 1769, because the condition on line 1768 was never true
1769 return dtype.dtype
1770 elif isinstance(dtype, (np.dtype, ExtensionDtype)): 1770 ↛ 1771line 1770 didn't jump to line 1771, because the condition on line 1770 was never true
1771 return dtype
1773 # registered extension types
1774 result = registry.find(dtype)
1775 if result is not None:
1776 return result
1778 # try a numpy dtype
1779 # raise a consistent TypeError if failed
1780 try:
1781 npdtype = np.dtype(dtype)
1782 except SyntaxError as err:
1783 # np.dtype uses `eval` which can raise SyntaxError
1784 raise TypeError(f"data type '{dtype}' not understood") from err
1786 # Any invalid dtype (such as pd.Timestamp) should raise an error.
1787 # np.dtype(invalid_type).kind = 0 for such objects. However, this will
1788 # also catch some valid dtypes such as object, np.object_ and 'object'
1789 # which we safeguard against by catching them earlier and returning
1790 # np.dtype(valid_dtype) before this condition is evaluated.
1791 if is_hashable(dtype) and dtype in [object, np.object_, "object", "O"]:
1792 # check hashability to avoid errors/DeprecationWarning when we get
1793 # here and `dtype` is an array
1794 return npdtype
1795 elif npdtype.kind == "O": 1795 ↛ 1796line 1795 didn't jump to line 1796, because the condition on line 1795 was never true
1796 raise TypeError(f"dtype '{dtype}' not understood")
1798 return npdtype
1801def is_all_strings(value: ArrayLike) -> bool:
1802 """
1803 Check if this is an array of strings that we should try parsing.
1805 Includes object-dtype ndarray containing all-strings, StringArray,
1806 and Categorical with all-string categories.
1807 Does not include numpy string dtypes.
1808 """
1809 dtype = value.dtype
1811 if isinstance(dtype, np.dtype):
1812 return (
1813 dtype == np.dtype("object")
1814 and lib.infer_dtype(value, skipna=False) == "string"
1815 )
1816 elif isinstance(dtype, CategoricalDtype):
1817 return dtype.categories.inferred_type == "string"
1818 return dtype == "string"
1821__all__ = [
1822 "classes",
1823 "classes_and_not_datetimelike",
1824 "DT64NS_DTYPE",
1825 "ensure_float",
1826 "ensure_float64",
1827 "ensure_python_int",
1828 "ensure_str",
1829 "get_dtype",
1830 "infer_dtype_from_object",
1831 "INT64_DTYPE",
1832 "is_1d_only_ea_dtype",
1833 "is_1d_only_ea_obj",
1834 "is_all_strings",
1835 "is_any_int_dtype",
1836 "is_array_like",
1837 "is_bool",
1838 "is_bool_dtype",
1839 "is_categorical",
1840 "is_categorical_dtype",
1841 "is_complex",
1842 "is_complex_dtype",
1843 "is_dataclass",
1844 "is_datetime64_any_dtype",
1845 "is_datetime64_dtype",
1846 "is_datetime64_ns_dtype",
1847 "is_datetime64tz_dtype",
1848 "is_datetimelike_v_numeric",
1849 "is_datetime_or_timedelta_dtype",
1850 "is_decimal",
1851 "is_dict_like",
1852 "is_dtype_equal",
1853 "is_ea_or_datetimelike_dtype",
1854 "is_extension_array_dtype",
1855 "is_extension_type",
1856 "is_file_like",
1857 "is_float_dtype",
1858 "is_int64_dtype",
1859 "is_integer_dtype",
1860 "is_interval",
1861 "is_interval_dtype",
1862 "is_iterator",
1863 "is_named_tuple",
1864 "is_nested_list_like",
1865 "is_number",
1866 "is_numeric_dtype",
1867 "is_numeric_v_string_like",
1868 "is_object_dtype",
1869 "is_period_dtype",
1870 "is_re",
1871 "is_re_compilable",
1872 "is_scipy_sparse",
1873 "is_sequence",
1874 "is_signed_integer_dtype",
1875 "is_sparse",
1876 "is_string_dtype",
1877 "is_string_or_object_np_dtype",
1878 "is_timedelta64_dtype",
1879 "is_timedelta64_ns_dtype",
1880 "is_unsigned_integer_dtype",
1881 "needs_i8_conversion",
1882 "pandas_dtype",
1883 "TD64NS_DTYPE",
1884 "validate_all_hashable",
1885]