CLN: Remove/deprecate unused/misleading dtype functions (#23917)

Author: jbrockmendel

doc/source/whatsnew/v0.24.0.rst

@@ -1048,6 +1048,8 @@ Deprecations
 - The ``keep_tz=False`` option (the default) of the ``keep_tz`` keyword of
   :meth:`DatetimeIndex.to_series` is deprecated (:issue:`17832`).
 - Timezone converting a tz-aware ``datetime.datetime`` or :class:`Timestamp` with :class:`Timestamp` and the ``tz`` argument is now deprecated. Instead, use :meth:`Timestamp.tz_convert` (:issue:`23579`)
+- :func:`pandas.types.is_period` is deprecated in favor of `pandas.types.is_period_dtype` (:issue:`23917`)
+- :func:`pandas.types.is_datetimetz` is deprecated in favor of `pandas.types.is_datetime64tz` (:issue:`23917`)
 
 .. _whatsnew_0240.deprecations.datetimelike_int_ops:
 

pandas/_libs/lib.pyx

@@ -1248,25 +1248,19 @@ def infer_dtype(value: object, skipna: bool=False) -> str:
     if util.is_datetime64_object(val):
         if is_datetime64_array(values):
             return 'datetime64'
-        elif is_timedelta_or_timedelta64_array(values):
-            return 'timedelta'
 
     elif is_timedelta(val):
         if is_timedelta_or_timedelta64_array(values):
             return 'timedelta'
 
     elif util.is_integer_object(val):
-        # a timedelta will show true here as well
-        if is_timedelta(val):
-            if is_timedelta_or_timedelta64_array(values):
-                return 'timedelta'
+        # ordering matters here; this check must come after the is_timedelta
+        #  check otherwise numpy timedelta64 objects would come through here
 
         if is_integer_array(values):
             return 'integer'
         elif is_integer_float_array(values):
             return 'mixed-integer-float'
-        elif is_timedelta_or_timedelta64_array(values):
-            return 'timedelta'
         return 'mixed-integer'
 
     elif PyDateTime_Check(val):
@@ -1699,27 +1693,6 @@ cdef class TimedeltaValidator(TemporalValidator):
         return is_null_timedelta64(value)
 
 
-# TODO: Not used outside of tests; remove?
-def is_timedelta_array(values: ndarray) -> bool:
-    cdef:
-        TimedeltaValidator validator = TimedeltaValidator(len(values),
-                                                          skipna=True)
-    return validator.validate(values)
-
-
-cdef class Timedelta64Validator(TimedeltaValidator):
-    cdef inline bint is_value_typed(self, object value) except -1:
-        return util.is_timedelta64_object(value)
-
-
-# TODO: Not used outside of tests; remove?
-def is_timedelta64_array(values: ndarray) -> bool:
-    cdef:
-        Timedelta64Validator validator = Timedelta64Validator(len(values),
-                                                              skipna=True)
-    return validator.validate(values)
-
-
 cdef class AnyTimedeltaValidator(TimedeltaValidator):
     cdef inline bint is_value_typed(self, object value) except -1:
         return is_timedelta(value)

pandas/core/algorithms.py

@@ -19,7 +19,7 @@
     ensure_float64, ensure_int64, ensure_object, ensure_platform_int,
     ensure_uint64, is_array_like, is_bool_dtype, is_categorical_dtype,
     is_complex_dtype, is_datetime64_any_dtype, is_datetime64tz_dtype,
-    is_datetimelike, is_datetimetz, is_extension_array_dtype, is_float_dtype,
+    is_datetimelike, is_extension_array_dtype, is_float_dtype,
     is_integer_dtype, is_interval_dtype, is_list_like, is_numeric_dtype,
     is_object_dtype, is_period_dtype, is_scalar, is_signed_integer_dtype,
     is_sparse, is_timedelta64_dtype, is_unsigned_integer_dtype,
@@ -1581,7 +1581,7 @@ def take_nd(arr, indexer, axis=0, out=None, fill_value=np.nan, mask_info=None,
     # dispatch to internal type takes
     if is_extension_array_dtype(arr):
         return arr.take(indexer, fill_value=fill_value, allow_fill=allow_fill)
-    elif is_datetimetz(arr):
+    elif is_datetime64tz_dtype(arr):
         return arr.take(indexer, fill_value=fill_value, allow_fill=allow_fill)
     elif is_interval_dtype(arr):
         return arr.take(indexer, fill_value=fill_value, allow_fill=allow_fill)

pandas/core/arrays/datetimes.py

@@ -1458,15 +1458,18 @@ def maybe_convert_dtype(data, copy):
     """
     Convert data based on dtype conventions, issuing deprecation warnings
     or errors where appropriate.
-     Parameters
+
+    Parameters
     ----------
     data : np.ndarray or pd.Index
     copy : bool
-     Returns
+
+    Returns
     -------
     data : np.ndarray or pd.Index
     copy : bool
-     Raises
+
+    Raises
     ------
     TypeError : PeriodDType data is passed
     """

pandas/core/dtypes/cast.py

@@ -13,11 +13,11 @@
     ensure_int8, ensure_int16, ensure_int32, ensure_int64, ensure_object,
     is_bool, is_bool_dtype, is_categorical_dtype, is_complex, is_complex_dtype,
     is_datetime64_dtype, is_datetime64_ns_dtype, is_datetime64tz_dtype,
-    is_datetime_or_timedelta_dtype, is_datetimelike, is_datetimetz,
-    is_dtype_equal, is_extension_array_dtype, is_extension_type, is_float,
-    is_float_dtype, is_integer, is_integer_dtype, is_object_dtype, is_scalar,
-    is_string_dtype, is_timedelta64_dtype, is_timedelta64_ns_dtype,
-    is_unsigned_integer_dtype, pandas_dtype)
+    is_datetime_or_timedelta_dtype, is_datetimelike, is_dtype_equal,
+    is_extension_array_dtype, is_extension_type, is_float, is_float_dtype,
+    is_integer, is_integer_dtype, is_object_dtype, is_scalar, is_string_dtype,
+    is_timedelta64_dtype, is_timedelta64_ns_dtype, is_unsigned_integer_dtype,
+    pandas_dtype)
 from .dtypes import (
     DatetimeTZDtype, ExtensionDtype, PandasExtensionDtype, PeriodDtype)
 from .generic import ABCDatetimeIndex, ABCPeriodIndex, ABCSeries
@@ -267,7 +267,7 @@ def maybe_promote(dtype, fill_value=np.nan):
         fill_value = tslibs.Timestamp(fill_value).value
     elif issubclass(dtype.type, np.timedelta64):
         fill_value = tslibs.Timedelta(fill_value).value
-    elif is_datetimetz(dtype):
+    elif is_datetime64tz_dtype(dtype):
         if isna(fill_value):
             fill_value = iNaT
     elif is_extension_array_dtype(dtype) and isna(fill_value):
@@ -310,7 +310,7 @@ def maybe_promote(dtype, fill_value=np.nan):
     # in case we have a string that looked like a number
     if is_extension_array_dtype(dtype):
         pass
-    elif is_datetimetz(dtype):
+    elif is_datetime64tz_dtype(dtype):
         pass
     elif issubclass(np.dtype(dtype).type, string_types):
         dtype = np.object_
@@ -546,34 +546,6 @@ def invalidate_string_dtypes(dtype_set):
         raise TypeError("string dtypes are not allowed, use 'object' instead")
 
 
-def maybe_convert_string_to_object(values):
-    """
-
-    Convert string-like and string-like array to convert object dtype.
-    This is to avoid numpy to handle the array as str dtype.
-    """
-    if isinstance(values, string_types):
-        values = np.array([values], dtype=object)
-    elif (isinstance(values, np.ndarray) and
-          issubclass(values.dtype.type, (np.string_, np.unicode_))):
-        values = values.astype(object)
-    return values
-
-
-def maybe_convert_scalar(values):
-    """
-    Convert a python scalar to the appropriate numpy dtype if possible
-    This avoids numpy directly converting according to platform preferences
-    """
-    if is_scalar(values):
-        dtype, values = infer_dtype_from_scalar(values)
-        try:
-            values = dtype(values)
-        except TypeError:
-            pass
-    return values
-
-
 def coerce_indexer_dtype(indexer, categories):
     """ coerce the indexer input array to the smallest dtype possible """
     length = len(categories)
@@ -1188,7 +1160,7 @@ def construct_1d_arraylike_from_scalar(value, length, dtype):
     np.ndarray / pandas type of length, filled with value
 
     """
-    if is_datetimetz(dtype):
+    if is_datetime64tz_dtype(dtype):
         from pandas import DatetimeIndex
         subarr = DatetimeIndex([value] * length, dtype=dtype)
     elif is_categorical_dtype(dtype):

pandas/core/dtypes/common.py

@@ -1,4 +1,6 @@
 """ common type operations """
+import warnings
+
 import numpy as np
 
 from pandas._libs import algos, lib
@@ -287,6 +289,8 @@ def is_datetimetz(arr):
     Check whether an array-like is a datetime array-like with a timezone
     component in its dtype.
 
+    .. deprecated:: 0.24.0
+
     Parameters
     ----------
     arr : array-like
@@ -320,12 +324,10 @@ def is_datetimetz(arr):
     True
     """
 
-    # TODO: do we need this function?
-    # It seems like a repeat of is_datetime64tz_dtype.
-
-    return ((isinstance(arr, ABCDatetimeIndex) and
-             getattr(arr, 'tz', None) is not None) or
-            is_datetime64tz_dtype(arr))
+    warnings.warn("'is_datetimetz' is deprecated and will be removed in a "
+                  "future version.  Use 'is_datetime64tz_dtype' instead.",
+                  FutureWarning, stacklevel=2)
+    return is_datetime64tz_dtype(arr)
 
 
 def is_offsetlike(arr_or_obj):
@@ -363,6 +365,8 @@ def is_period(arr):
     """
     Check whether an array-like is a periodical index.
 
+    .. deprecated:: 0.24.0
+
     Parameters
     ----------
     arr : array-like
@@ -382,8 +386,10 @@ def is_period(arr):
     True
     """
 
-    # TODO: do we need this function?
-    # It seems like a repeat of is_period_arraylike.
+    warnings.warn("'is_period' is deprecated and will be removed in a future "
+                  "version.  Use 'is_period_dtype' or is_period_arraylike' "
+                  "instead.", FutureWarning, stacklevel=2)
+
     return isinstance(arr, ABCPeriodIndex) or is_period_arraylike(arr)
 
 
@@ -743,8 +749,7 @@ def is_datetimelike(arr):
 
     return (is_datetime64_dtype(arr) or is_datetime64tz_dtype(arr) or
             is_timedelta64_dtype(arr) or
-            isinstance(arr, ABCPeriodIndex) or
-            is_datetimetz(arr))
+            isinstance(arr, ABCPeriodIndex))
 
 
 def is_dtype_equal(source, target):
@@ -1050,54 +1055,6 @@ def is_int64_dtype(arr_or_dtype):
     return issubclass(tipo, np.int64)
 
 
-def is_int_or_datetime_dtype(arr_or_dtype):
-    """
-    Check whether the provided array or dtype is of an
-    integer, timedelta64, or datetime64 dtype.
-
-    Parameters
-    ----------
-    arr_or_dtype : array-like
-        The array or dtype to check.
-
-    Returns
-    -------
-    boolean : Whether or not the array or dtype is of an
-              integer, timedelta64, or datetime64 dtype.
-
-    Examples
-    --------
-    >>> is_int_or_datetime_dtype(str)
-    False
-    >>> is_int_or_datetime_dtype(int)
-    True
-    >>> is_int_or_datetime_dtype(float)
-    False
-    >>> is_int_or_datetime_dtype(np.uint64)
-    True
-    >>> is_int_or_datetime_dtype(np.datetime64)
-    True
-    >>> is_int_or_datetime_dtype(np.timedelta64)
-    True
-    >>> is_int_or_datetime_dtype(np.array(['a', 'b']))
-    False
-    >>> is_int_or_datetime_dtype(pd.Series([1, 2]))
-    True
-    >>> is_int_or_datetime_dtype(np.array([], dtype=np.timedelta64))
-    True
-    >>> is_int_or_datetime_dtype(np.array([], dtype=np.datetime64))
-    True
-    >>> is_int_or_datetime_dtype(pd.Index([1, 2.]))  # float
-    False
-    """
-
-    if arr_or_dtype is None:
-        return False
-    tipo = _get_dtype_type(arr_or_dtype)
-    return (issubclass(tipo, np.integer) or
-            issubclass(tipo, (np.datetime64, np.timedelta64)))
-
-
 def is_datetime64_any_dtype(arr_or_dtype):
     """
     Check whether the provided array or dtype is of the datetime64 dtype.
@@ -1619,22 +1576,6 @@ def is_float_dtype(arr_or_dtype):
     return issubclass(tipo, np.floating)
 
 
-def is_floating_dtype(arr_or_dtype):
-    """Check whether the provided array or dtype is an instance of
-    numpy's float dtype.
-
-    .. deprecated:: 0.20.0
-
-    Unlike, `is_float_dtype`, this check is a lot stricter, as it requires
-    `isinstance` of `np.floating` and not `issubclass`.
-    """
-
-    if arr_or_dtype is None:
-        return False
-    tipo = _get_dtype_type(arr_or_dtype)
-    return isinstance(tipo, np.floating)
-
-
 def is_bool_dtype(arr_or_dtype):
     """
     Check whether the provided array or dtype is of a boolean dtype.
@@ -1758,7 +1699,7 @@ def is_extension_type(arr):
         return True
     elif is_sparse(arr):
         return True
-    elif is_datetimetz(arr):
+    elif is_datetime64tz_dtype(arr):
         return True
     return False
 
@@ -1991,7 +1932,7 @@ def _get_dtype_from_object(dtype):
         return dtype
     elif is_categorical(dtype):
         return CategoricalDtype().type
-    elif is_datetimetz(dtype):
+    elif is_datetime64tz_dtype(dtype):
         return DatetimeTZDtype(dtype).type
     elif isinstance(dtype, np.dtype):  # dtype object
         try:

pandas/core/dtypes/concat.py

@@ -8,7 +8,7 @@
 
 from pandas.core.dtypes.common import (
     _NS_DTYPE, _TD_DTYPE, is_bool_dtype, is_categorical_dtype,
-    is_datetime64_dtype, is_datetimetz, is_dtype_equal,
+    is_datetime64_dtype, is_datetime64tz_dtype, is_dtype_equal,
     is_extension_array_dtype, is_interval_dtype, is_object_dtype,
     is_period_dtype, is_sparse, is_timedelta64_dtype)
 from pandas.core.dtypes.generic import (
@@ -39,7 +39,7 @@ def get_dtype_kinds(l):
             typ = 'sparse'
         elif isinstance(arr, ABCRangeIndex):
             typ = 'range'
-        elif is_datetimetz(arr):
+        elif is_datetime64tz_dtype(arr):
             # if to_concat contains different tz,
             # the result must be object dtype
             typ = str(arr.dtype)

pandas/core/frame.py

@@ -54,7 +54,7 @@
     is_object_dtype,
     is_extension_type,
     is_extension_array_dtype,
-    is_datetimetz,
+    is_datetime64tz_dtype,
     is_datetime64_any_dtype,
     is_bool_dtype,
     is_integer_dtype,
@@ -542,7 +542,8 @@ def _get_axes(N, K, index=index, columns=columns):
             index, columns = _get_axes(len(values), 1)
             return _arrays_to_mgr([values], columns, index, columns,
                                   dtype=dtype)
-        elif (is_datetimetz(values) or is_extension_array_dtype(values)):
+        elif (is_datetime64tz_dtype(values) or
+              is_extension_array_dtype(values)):
             # GH19157
             if columns is None:
                 columns = [0]