API: Added is_extension_array_dtype (#24771)

Author: TomAugspurger

doc/source/api/general_utility_functions.rst

@@ -63,6 +63,7 @@ Dtype introspection
     api.types.is_datetime64_ns_dtype
     api.types.is_datetime64tz_dtype
     api.types.is_extension_type
+    api.types.is_extension_array_dtype
     api.types.is_float_dtype
     api.types.is_int64_dtype
     api.types.is_integer_dtype

pandas/core/dtypes/api.py

@@ -5,10 +5,10 @@
     is_categorical_dtype, is_complex, is_complex_dtype,
     is_datetime64_any_dtype, is_datetime64_dtype, is_datetime64_ns_dtype,
     is_datetime64tz_dtype, is_datetimetz, is_dict_like, is_dtype_equal,
-    is_extension_type, is_file_like, is_float, is_float_dtype, is_hashable,
-    is_int64_dtype, is_integer, is_integer_dtype, is_interval,
-    is_interval_dtype, is_iterator, is_list_like, is_named_tuple, is_number,
-    is_numeric_dtype, is_object_dtype, is_period, is_period_dtype, is_re,
-    is_re_compilable, is_scalar, is_signed_integer_dtype, is_sparse,
+    is_extension_array_dtype, is_extension_type, is_file_like, is_float,
+    is_float_dtype, is_hashable, is_int64_dtype, is_integer, is_integer_dtype,
+    is_interval, is_interval_dtype, is_iterator, is_list_like, is_named_tuple,
+    is_number, is_numeric_dtype, is_object_dtype, is_period, is_period_dtype,
+    is_re, is_re_compilable, is_scalar, is_signed_integer_dtype, is_sparse,
     is_string_dtype, is_timedelta64_dtype, is_timedelta64_ns_dtype,
     is_unsigned_integer_dtype, pandas_dtype)

pandas/core/dtypes/common.py

@@ -1700,15 +1700,21 @@ def is_extension_type(arr):
 
 
 def is_extension_array_dtype(arr_or_dtype):
-    """Check if an object is a pandas extension array type.
+    """
+    Check if an object is a pandas extension array type.
+
+    See the :ref:`Use Guide <extending.extension-types>` for more.
 
     Parameters
     ----------
     arr_or_dtype : object
+        For array-like input, the ``.dtype`` attribute will
+        be extracted.
 
     Returns
     -------
     bool
+        Whether the `arr_or_dtype` is an extension array type.
 
     Notes
     -----
@@ -1718,9 +1724,25 @@ def is_extension_array_dtype(arr_or_dtype):
     * Categorical
     * Sparse
     * Interval
+    * Period
+    * DatetimeArray
+    * TimedeltaArray
 
     Third-party libraries may implement arrays or types satisfying
     this interface as well.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_extension_array_dtype
+    >>> arr = pd.Categorical(['a', 'b'])
+    >>> is_extension_array_dtype(arr)
+    True
+    >>> is_extension_array_dtype(arr.dtype)
+    True
+
+    >>> arr = np.array(['a', 'b'])
+    >>> is_extension_array_dtype(arr.dtype)
+    False
     """
     dtype = getattr(arr_or_dtype, 'dtype', arr_or_dtype)
     return (isinstance(dtype, ExtensionDtype) or

pandas/tests/api/test_types.py

@@ -24,7 +24,8 @@ class TestTypes(Base):
                'is_dict_like', 'is_iterator', 'is_file_like',
                'is_list_like', 'is_hashable', 'is_array_like',
                'is_named_tuple',
-               'pandas_dtype', 'union_categoricals', 'infer_dtype']
+               'pandas_dtype', 'union_categoricals', 'infer_dtype',
+               'is_extension_array_dtype']
     deprecated = ['is_period', 'is_datetimetz']
     dtypes = ['CategoricalDtype', 'DatetimeTZDtype',
               'PeriodDtype', 'IntervalDtype']