DOC: Document pandas.core.dtypes.common

Closes pandas-devgh-15895.

Author: gfyoung

pandas/core/dtypes/common.py

@@ -82,46 +82,242 @@ def _ensure_categorical(arr):
 
 
 def is_object_dtype(arr_or_dtype):
+    """
+    Check whether an array-like or dtype is of the object dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like, dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    is_object_dtype : Whether or not the array-like or dtype is of
+                      the object dtype.
+
+    Examples
+    --------
+    >>> is_object_dtype(object)
+    True
+    >>> is_object_dtype(int)
+    False
+    >>> is_object_dtype(np.array([], dtype=object))
+    True
+    >>> is_object_dtype(np.array([], dtype=int))
+    False
+    >>> is_object_dtype([1, 2, 3])
+    False
+    """
+
     if arr_or_dtype is None:
         return False
     tipo = _get_dtype_type(arr_or_dtype)
     return issubclass(tipo, np.object_)
 
 
 def is_sparse(array):
-    """ return if we are a sparse array """
+    """
+    Check whether an array-like is a pandas sparse array.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_sparse : Whether or not the array-like is a pandas sparse array.
+
+    Examples
+    --------
+    >>> is_sparse(np.array([1, 2, 3]))
+    False
+    >>> is_sparse(pd.SparseArray([1, 2, 3]))
+    True
+    >>> is_sparse(pd.SparseSeries([1, 2, 3]))
+    True
+
+    This function checks only for pandas sparse array instances, so
+    sparse arrays from other libraries will return False.
+
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_sparse(bsr_matrix([1, 2, 3]))
+    False
+    """
+
     return isinstance(array, (ABCSparseArray, ABCSparseSeries))
 
 
 def is_scipy_sparse(array):
-    """ return if we are a scipy.sparse.spmatrix """
+    """
+    Check whether an array-like is a scipy.sparse.spmatrix instance.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_scipy_sparse : Whether or not the array-like is a
+                      scipy.sparse.spmatrix instance.
+
+    Notes
+    -----
+    If scipy is not installed, this function will always return False.
+
+    Examples
+    --------
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_scipy_sparse(bsr_matrix([1, 2, 3]))
+    True
+    >>> is_scipy_sparse(pd.SparseArray([1, 2, 3]))
+    False
+    >>> is_scipy_sparse(pd.SparseSeries([1, 2, 3]))
+    False
+    """
+
     global _is_scipy_sparse
+
     if _is_scipy_sparse is None:
         try:
             from scipy.sparse import issparse as _is_scipy_sparse
         except ImportError:
             _is_scipy_sparse = lambda _: False
+
     return _is_scipy_sparse(array)
 
 
 def is_categorical(array):
-    """ return if we are a categorical possibility """
+    """
+    Check whether an array-like is a Categorical instance.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_categorical : Whether or not the array-like is a Categorical instance.
+
+    Examples
+    --------
+    >>> is_categorical([1, 2, 3])
+    False
+
+    Categoricals and Series Categoricals will return True.
+
+    >>> cat = pd.Categorical([1, 2, 3])
+    >>> is_categorical(cat)
+    True
+    >>> is_categorical(pd.Series(cat))
+    True
+    """
+
     return isinstance(array, ABCCategorical) or is_categorical_dtype(array)
 
 
 def is_datetimetz(array):
-    """ return if we are a datetime with tz array """
+    """
+    Check whether an array-like is a datetime array-like with a timezone
+    component in its dtype.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_datetimetz : Whether or not the array-like is a datetime array-like
+                    with a timezone component in its dtype.
+
+    Examples
+    --------
+    >>> is_datetimetz([1, 2, 3])
+    False
+
+    Although the following examples are both DatetimeIndex objects,
+    the first one returns False because it has no timezone component
+    unlike the second one, which returns True.
+
+    >>> is_datetimetz(pd.DatetimeIndex([1, 2, 3]))
+    False
+    >>> is_datetimetz(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
+    True
+
+    The object need not be a DatetimeIndex object. It just needs to have
+    a dtype which has a timezone component.
+
+    >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern")
+    >>> s = pd.Series([], dtype=dtype)
+    >>> is_datetimetz(s)
+    True
+    """
+
+    # TODO: do we need this function?
+    # It seems like a repeat of is_datetime64tz_dtype.
+
     return ((isinstance(array, ABCDatetimeIndex) and
              getattr(array, 'tz', None) is not None) or
             is_datetime64tz_dtype(array))
 
 
 def is_period(array):
-    """ return if we are a period array """
+    """
+    Check whether an array-like is a periodical index.
+
+    Parameters
+    ----------
+    array : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    is_period: : Whether or not the array-like is a periodical index.
+
+    Examples
+    --------
+    >>> is_period([1, 2, 3])
+    False
+    >>> is_period(pd.Index([1, 2, 3]))
+    False
+    >>> is_period(pd.PeriodIndex(["2017-01-01"], freq="D"))
+    True
+    """
+
     return isinstance(array, ABCPeriodIndex) or is_period_arraylike(array)
 
 
 def is_datetime64_dtype(arr_or_dtype):
+    """
+    Check whether an array-like or dtype is of the datetime64 dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like, dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    is_datetime64_dtype : Whether or not the array-like or dtype is of
+                          the datetime64 dtype.
+
+    Examples
+    --------
+    >>> is_datetime64_dtype(object)
+    False
+    >>> is_datetime64_dtype(np.datetime64)
+    True
+    >>> is_datetime64_dtype(np.array([], dtype=int))
+    False
+    >>> is_datetime64_dtype(np.array([], dtype=np.datetime64))
+    True
+    >>> is_datetime64_dtype([1, 2, 3])
+    False
+    """
+
     if arr_or_dtype is None:
         return False
     try:
@@ -132,6 +328,38 @@ def is_datetime64_dtype(arr_or_dtype):
 
 
 def is_datetime64tz_dtype(arr_or_dtype):
+    """
+    Check whether an array-like or dtype is of a DatetimeTZDtype dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like, dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    is_datetime64tz_dtype : Whether or not the array-like or dtype is 
+                            of a DatetimeTZDtype dtype.
+
+    Examples
+    --------
+    >>> is_datetime64tz_dtype(object)
+    False
+    >>> is_datetime64tz_dtype([1, 2, 3])
+    False
+    >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3]))  # tz-naive
+    False
+    >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
+    True
+
+    >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern")
+    >>> s = pd.Series([], dtype=dtype)
+    >>> is_datetime64tz_dtype(dtype)
+    True
+    >>> is_datetime64tz_dtype(s)
+    True
+    """
+
     if arr_or_dtype is None:
         return False
     return DatetimeTZDtype.is_dtype(arr_or_dtype)