DOC: Using deprecated sphinx directive instead of non-standard messages in docstrings (#18928)

Author: datapythonista

ci/lint.sh

@@ -117,6 +117,10 @@ if [ "$LINT" ]; then
         fi
     done
     echo "Check for incorrect sphinx directives DONE"
+
+    echo "Check for deprecated messages without sphinx directive"
+    grep -R --include="*.py" --include="*.pyx" -E "(DEPRECATED|DEPRECATE|Deprecated)(:|,|\.)" pandas
+    echo "Check for deprecated messages without sphinx directive DONE"
 else
     echo "NOT Linting"
 fi

doc/source/contributing.rst

@@ -547,7 +547,30 @@ Backwards Compatibility
 Please try to maintain backward compatibility. *pandas* has lots of users with lots of
 existing code, so don't break it if at all possible.  If you think breakage is required,
 clearly state why as part of the pull request.  Also, be careful when changing method
-signatures and add deprecation warnings where needed.
+signatures and add deprecation warnings where needed. Also, add the deprecated sphinx
+directive to the deprecated functions or methods.
+
+If a function with the same arguments as the one being deprecated exist, you can use
+the ``pandas.util._decorators.deprecate``:
+
+.. code-block:: python
+
+    from pandas.util._decorators import deprecate
+
+    deprecate('old_func', 'new_func', '0.21.0')
+
+Otherwise, you need to do it manually:
+
+.. code-block:: python
+
+    def old_func():
+        """Summary of the function.
+
+        .. deprecated:: 0.21.0
+           Use new_func instead.
+        """
+        warnings.warn('Use new_func instead.', FutureWarning, stacklevel=2)
+        new_func()
 
 .. _contributing.ci:
 

pandas/__init__.py

@@ -51,7 +51,7 @@
 plot_params = pandas.plotting._style._Options(deprecated=True)
 # do not import deprecate to top namespace
 scatter_matrix = pandas.util._decorators.deprecate(
-    'pandas.scatter_matrix', pandas.plotting.scatter_matrix,
+    'pandas.scatter_matrix', pandas.plotting.scatter_matrix, '0.20.0',
     'pandas.plotting.scatter_matrix')
 
 from pandas.util._print_versions import show_versions

pandas/_libs/tslibs/timestamps.pyx

@@ -389,9 +389,6 @@ class Timestamp(_Timestamp):
         Unit used for conversion if ts_input is of type int or float. The
         valid values are 'D', 'h', 'm', 's', 'ms', 'us', and 'ns'. For
         example, 's' means seconds and 'ms' means milliseconds.
-    offset : str, DateOffset
-        Deprecated, use freq
-
     year, month, day : int
         .. versionadded:: 0.19.0
     hour, minute, second, microsecond : int, optional, default 0

pandas/computation/expressions.py

@@ -2,6 +2,10 @@
 
 
 def set_use_numexpr(v=True):
+    """
+    .. deprecated:: 0.20.0
+        Use ``pandas.set_option('compute.use_numexpr', v)`` instead.
+    """
     warnings.warn("pandas.computation.expressions.set_use_numexpr is "
                   "deprecated and will be removed in a future version.\n"
                   "you can toggle usage of numexpr via "

pandas/core/categorical.py

@@ -594,7 +594,8 @@ def _get_labels(self):
         """
         Get the category labels (deprecated).
 
-        Deprecated, use .codes!
+        .. deprecated:: 0.15.0
+            Use `.codes()` instead.
         """
         warn("'labels' is deprecated. Use 'codes' instead", FutureWarning,
              stacklevel=2)

pandas/core/datetools.py

@@ -1,4 +1,8 @@
-"""A collection of random tools for dealing with dates in Python"""
+"""A collection of random tools for dealing with dates in Python.
+
+.. deprecated:: 0.19.0
+    Use pandas.tseries module instead.
+"""
 
 # flake8: noqa
 

pandas/core/dtypes/common.py

@@ -758,10 +758,9 @@ def is_dtype_union_equal(source, target):
 
 
 def is_any_int_dtype(arr_or_dtype):
-    """
-    DEPRECATED: This function will be removed in a future version.
+    """Check whether the provided array or dtype is of an integer dtype.
 
-    Check whether the provided array or dtype is of an integer dtype.
+    .. deprecated:: 0.20.0
 
     In this function, timedelta64 instances are also considered "any-integer"
     type objects and will return True.
@@ -1557,12 +1556,11 @@ def is_float_dtype(arr_or_dtype):
 
 
 def is_floating_dtype(arr_or_dtype):
-    """
-    DEPRECATED: This function will be removed in a future version.
-
-    Check whether the provided array or dtype is an instance of
+    """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`.
     """

pandas/core/frame.py

@@ -1326,9 +1326,10 @@ def _from_arrays(cls, arrays, columns, index, dtype=None):
     def from_csv(cls, path, header=0, sep=',', index_col=0, parse_dates=True,
                  encoding=None, tupleize_cols=None,
                  infer_datetime_format=False):
-        """
-        Read CSV file (DEPRECATED, please use :func:`pandas.read_csv`
-        instead).
+        """Read CSV file.
+
+        .. deprecated:: 0.21.0
+            Use :func:`pandas.read_csv` instead.
 
         It is preferable to use the more powerful :func:`pandas.read_csv`
         for most general purposes, but ``from_csv`` makes for an easy
@@ -1979,12 +1980,10 @@ def _unpickle_matrix_compat(self, state):  # pragma: no cover
     # Getting and setting elements
 
     def get_value(self, index, col, takeable=False):
-        """
-        Quickly retrieve single value at passed column and index
+        """Quickly retrieve single value at passed column and index
 
         .. deprecated:: 0.21.0
-
-        Please use .at[] or .iat[] accessors.
+            Use .at[] or .iat[] accessors instead.
 
         Parameters
         ----------
@@ -2024,12 +2023,10 @@ def _get_value(self, index, col, takeable=False):
     _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, index, col, value, takeable=False):
-        """
-        Put single value at passed column and index
+        """Put single value at passed column and index
 
         .. deprecated:: 0.21.0
-
-        Please use .at[] or .iat[] accessors.
+            Use .at[] or .iat[] accessors instead.
 
         Parameters
         ----------
@@ -3737,12 +3734,13 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
 
     def sortlevel(self, level=0, axis=0, ascending=True, inplace=False,
                   sort_remaining=True):
-        """
-        DEPRECATED: use :meth:`DataFrame.sort_index`
-
-        Sort multilevel index by chosen axis and primary level. Data will be
+        """Sort multilevel index by chosen axis and primary level. Data will be
         lexicographically sorted by the chosen level followed by the other
-        levels (in order)
+        levels (in order).
+
+        .. deprecated:: 0.20.0
+            Use :meth:`DataFrame.sort_index`
+
 
         Parameters
         ----------

pandas/core/generic.py

@@ -2718,10 +2718,10 @@ def xs(self, key, axis=0, level=None, drop_level=True):
     _xs = xs
 
     def select(self, crit, axis=0):
-        """
-        Return data corresponding to axis labels matching criteria
+        """Return data corresponding to axis labels matching criteria
 
-        DEPRECATED: use df.loc[df.index.map(crit)] to select via labels
+        .. deprecated:: 0.21.0
+            Use df.loc[df.index.map(crit)] to select via labels
 
         Parameters
         ----------
@@ -4108,8 +4108,11 @@ def _consolidate(self, inplace=False):
             return self._constructor(cons_data).__finalize__(self)
 
     def consolidate(self, inplace=False):
-        """
-        DEPRECATED: consolidate will be an internal implementation only.
+        """Compute NDFrame with "consolidated" internals (data of each dtype
+        grouped together in a single ndarray).
+
+        .. deprecated:: 0.20.0
+            Consolidate will be an internal implementation only.
         """
         # 15483
         warnings.warn("consolidate is deprecated and will be removed in a "
@@ -4160,11 +4163,10 @@ def _get_bool_data(self):
     # Internal Interface Methods
 
     def as_matrix(self, columns=None):
-        """
-        DEPRECATED: as_matrix will be removed in a future version.
-        Use :meth:`DataFrame.values` instead.
+        """Convert the frame to its Numpy-array representation.
 
-        Convert the frame to its Numpy-array representation.
+        .. deprecated:: 0.23.0
+            Use :meth:`DataFrame.values` instead.
 
         Parameters
         ----------
@@ -4479,12 +4481,11 @@ def _convert(self, datetime=False, numeric=False, timedelta=False,
                                timedelta=timedelta, coerce=coerce,
                                copy=copy)).__finalize__(self)
 
-    # TODO: Remove in 0.18 or 2017, which ever is sooner
     def convert_objects(self, convert_dates=True, convert_numeric=False,
                         convert_timedeltas=True, copy=True):
-        """
-        Deprecated.
-        Attempt to infer better dtype for object columns
+        """Attempt to infer better dtype for object columns.
+
+        .. deprecated:: 0.21.0
 
         Parameters
         ----------

pandas/core/indexes/datetimelike.py

@@ -441,9 +441,10 @@ def _isnan(self):
 
     @property
     def asobject(self):
-        """DEPRECATED: Use ``astype(object)`` instead.
+        """Return object Index which contains boxed values.
 
-        return object Index which contains boxed values
+        .. deprecated:: 0.23.0
+            Use ``astype(object)`` instead.
 
         *this is an internal non-public method*
         """

pandas/core/panel.py

@@ -477,8 +477,7 @@ def as_matrix(self):
     # Getting and setting elements
 
     def get_value(self, *args, **kwargs):
-        """
-        Quickly retrieve single value at (item, major, minor) location
+        """Quickly retrieve single value at (item, major, minor) location
 
         .. deprecated:: 0.21.0
 
@@ -525,8 +524,7 @@ def _get_value(self, *args, **kwargs):
     _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, *args, **kwargs):
-        """
-        Quickly set single value at (item, major, minor) location
+        """Quickly set single value at (item, major, minor) location
 
         .. deprecated:: 0.21.0
 

pandas/core/series.py

@@ -93,8 +93,10 @@
 
 # see gh-16971
 def remove_na(arr):
-    """
-    DEPRECATED : this function will be removed in a future version.
+    """Remove null values from array like structure.
+
+    .. deprecated:: 0.21.0
+        Use s[s.notnull()] instead.
     """
 
     warnings.warn("remove_na is deprecated and is a private "
@@ -290,8 +292,10 @@ def _init_dict(self, data, index=None, dtype=None):
     @classmethod
     def from_array(cls, arr, index=None, name=None, dtype=None, copy=False,
                    fastpath=False):
-        """
-        DEPRECATED: use the pd.Series(..) constructor instead.
+        """Construct Series from array.
+
+        .. deprecated :: 0.23.0
+            Use pd.Series(..) constructor instead.
 
         """
         warnings.warn("'from_array' is deprecated and will be removed in a "
@@ -450,9 +454,11 @@ def get_values(self):
 
     @property
     def asobject(self):
-        """DEPRECATED: Use ``astype(object)`` instead.
+        """Return object Series which contains boxed values.
+
+        .. deprecated :: 0.23.0
+            Use ``astype(object) instead.
 
-        return object Series which contains boxed values
 
         *this is an internal non-public method*
         """
@@ -911,12 +917,10 @@ def repeat(self, repeats, *args, **kwargs):
                                  index=new_index).__finalize__(self)
 
     def get_value(self, label, takeable=False):
-        """
-        Quickly retrieve single value at passed index label
+        """Quickly retrieve single value at passed index label
 
         .. deprecated:: 0.21.0
-
-        Please use .at[] or .iat[] accessors.
+            Please use .at[] or .iat[] accessors.
 
         Parameters
         ----------
@@ -940,14 +944,12 @@ def _get_value(self, label, takeable=False):
     _get_value.__doc__ = get_value.__doc__
 
     def set_value(self, label, value, takeable=False):
-        """
-        Quickly set single value at passed label. If label is not contained, a
-        new object is created with the label placed at the end of the result
-        index
+        """Quickly set single value at passed label. If label is not contained,
+        a new object is created with the label placed at the end of the result
+        index.
 
         .. deprecated:: 0.21.0
-
-        Please use .at[] or .iat[] accessors.
+            Please use .at[] or .iat[] accessors.
 
         Parameters
         ----------
@@ -1382,13 +1384,13 @@ def idxmax(self, axis=None, skipna=True, *args, **kwargs):
         return self.index[i]
 
     # ndarray compat
-    argmin = deprecate('argmin', idxmin,
+    argmin = deprecate('argmin', idxmin, '0.21.0',
                        msg="'argmin' is deprecated, use 'idxmin' instead. "
                            "The behavior of 'argmin' will be corrected to "
                            "return the positional minimum in the future. "
                            "Use 'series.values.argmin' to get the position of "
                            "the minimum now.")
-    argmax = deprecate('argmax', idxmax,
+    argmax = deprecate('argmax', idxmax, '0.21.0',
                        msg="'argmax' is deprecated, use 'idxmax' instead. "
                            "The behavior of 'argmax' will be corrected to "
                            "return the positional maximum in the future. "
@@ -2120,12 +2122,12 @@ def nsmallest(self, n=5, keep='first'):
         return algorithms.SelectNSeries(self, n=n, keep=keep).nsmallest()
 
     def sortlevel(self, level=0, ascending=True, sort_remaining=True):
-        """
-        DEPRECATED: use :meth:`Series.sort_index`
-
-        Sort Series with MultiIndex by chosen level. Data will be
+        """Sort Series with MultiIndex by chosen level. Data will be
         lexicographically sorted by the chosen level followed by the other
-        levels (in order)
+        levels (in order),
+
+        .. deprecated:: 0.20.0
+            Use :meth:`Series.sort_index`
 
         Parameters
         ----------
@@ -2670,7 +2672,12 @@ def shift(self, periods=1, freq=None, axis=0):
         return super(Series, self).shift(periods=periods, freq=freq, axis=axis)
 
     def reindex_axis(self, labels, axis=0, **kwargs):
-        """ for compatibility with higher dims """
+        """Conform Series to new index with optional filling logic.
+
+        .. deprecated:: 0.21.0
+            Use ``Series.reindex`` instead.
+        """
+        # for compatibility with higher dims
         if axis != 0:
             raise ValueError("cannot reindex series on non-zero axis!")
         msg = ("'.reindex_axis' is deprecated and will be removed in a future "
@@ -2808,9 +2815,10 @@ def between(self, left, right, inclusive=True):
     @classmethod
     def from_csv(cls, path, sep=',', parse_dates=True, header=None,
                  index_col=0, encoding=None, infer_datetime_format=False):
-        """
-        Read CSV file (DEPRECATED, please use :func:`pandas.read_csv`
-        instead).
+        """Read CSV file.
+
+        .. deprecated:: 0.21.0
+            Use :func:`pandas.read_csv` instead.
 
         It is preferable to use the more powerful :func:`pandas.read_csv`
         for most general purposes, but ``from_csv`` makes for an easy
@@ -2978,8 +2986,10 @@ def dropna(self, axis=0, inplace=False, **kwargs):
                 return self.copy()
 
     def valid(self, inplace=False, **kwargs):
-        """DEPRECATED. Series.valid will be removed in a future version.
-        Use :meth:`Series.dropna` instead.
+        """Return Series without null values.
+
+        .. deprecated:: 0.23.0
+            Use :meth:`Series.dropna` instead.
         """
         warnings.warn("Method .valid will be removed in a future version. "
                       "Use .dropna instead.", FutureWarning, stacklevel=2)

pandas/core/sparse/frame.py

@@ -820,12 +820,12 @@ def cumsum(self, axis=0, *args, **kwargs):
 
         return self.apply(lambda x: x.cumsum(), axis=axis)
 
-    @Appender(generic._shared_docs['isna'])
+    @Appender(generic._shared_docs['isna'] % _shared_doc_kwargs)
     def isna(self):
         return self._apply_columns(lambda x: x.isna())
     isnull = isna
 
-    @Appender(generic._shared_docs['notna'])
+    @Appender(generic._shared_docs['notna'] % _shared_doc_kwargs)
     def notna(self):
         return self._apply_columns(lambda x: x.notna())
     notnull = notna

pandas/core/sparse/series.py

@@ -255,9 +255,10 @@ def npoints(self):
     @classmethod
     def from_array(cls, arr, index=None, name=None, copy=False,
                    fill_value=None, fastpath=False):
-        """
-        DEPRECATED: use the pd.SparseSeries(..) constructor instead.
+        """Construct SparseSeries from array.
 
+        .. deprecated:: 0.23.0
+            Use the pd.SparseSeries(..) constructor instead.
         """
         warnings.warn("'from_array' is deprecated and will be removed in a "
                       "future version. Please use the pd.SparseSeries(..) "
@@ -571,8 +572,9 @@ def to_dense(self, sparse_only=False):
 
         Parameters
         ----------
-        sparse_only: bool, default False
-            DEPRECATED: this argument will be removed in a future version.
+        sparse_only : bool, default False
+            .. deprecated:: 0.20.0
+                This argument will be removed in a future version.
 
             If True, return just the non-sparse values, or the dense version
             of `self.values` if False.
@@ -679,15 +681,15 @@ def cumsum(self, axis=0, *args, **kwargs):
             new_array, index=self.index,
             sparse_index=new_array.sp_index).__finalize__(self)
 
-    @Appender(generic._shared_docs['isna'])
+    @Appender(generic._shared_docs['isna'] % _shared_doc_kwargs)
     def isna(self):
         arr = SparseArray(isna(self.values.sp_values),
                           sparse_index=self.values.sp_index,
                           fill_value=isna(self.fill_value))
         return self._constructor(arr, index=self.index).__finalize__(self)
     isnull = isna
 
-    @Appender(generic._shared_docs['notna'])
+    @Appender(generic._shared_docs['notna'] % _shared_doc_kwargs)
     def notna(self):
         arr = SparseArray(notna(self.values.sp_values),
                           sparse_index=self.values.sp_index,

pandas/core/strings.py

@@ -478,7 +478,8 @@ def str_match(arr, pat, case=True, flags=0, na=np.nan, as_indexer=None):
     flags : int, default 0 (no flags)
         re module flags, e.g. re.IGNORECASE
     na : default NaN, fill value for missing values.
-    as_indexer : DEPRECATED - Keyword is ignored.
+    as_indexer
+        .. deprecated:: 0.21.0
 
     Returns
     -------

pandas/util/_decorators.py

@@ -7,17 +7,24 @@
 from functools import wraps, update_wrapper
 
 
-def deprecate(name, alternative, alt_name=None, klass=None,
-              stacklevel=2, msg=None):
-    """
-    Return a new function that emits a deprecation warning on use.
+def deprecate(name, alternative, version, alt_name=None,
+              klass=None, stacklevel=2, msg=None):
+    """Return a new function that emits a deprecation warning on use.
+
+    To use this method for a deprecated function, another function
+    `alternative` with the same signature must exist. The deprecated
+    function will emit a deprecation warning, and in the docstring
+    it will contain the deprecation directive with the provided version
+    so it can be detected for future removal.
 
     Parameters
     ----------
     name : str
         Name of function to deprecate
     alternative : str
         Name of function to use instead
+    version : str
+        Version of pandas in which the method has been deprecated
     alt_name : str, optional
         Name to use in preference of alternative.__name__
     klass : Warning, default FutureWarning
@@ -29,16 +36,24 @@ def deprecate(name, alternative, alt_name=None, klass=None,
 
     alt_name = alt_name or alternative.__name__
     klass = klass or FutureWarning
-    msg = msg or "{} is deprecated, use {} instead".format(name, alt_name)
+    warning_msg = msg or '{} is deprecated, use {} instead'.format(name,
+                                                                   alt_name)
 
     @wraps(alternative)
     def wrapper(*args, **kwargs):
-        warnings.warn(msg, klass, stacklevel=stacklevel)
+        warnings.warn(warning_msg, klass, stacklevel=stacklevel)
         return alternative(*args, **kwargs)
 
-    if getattr(wrapper, '__doc__', None) is not None:
-        wrapper.__doc__ = ('\n'.join(wrap(msg, 70)) + '\n'
-                           + dedent(wrapper.__doc__))
+    # adding deprecated directive to the docstring
+    msg = msg or 'Use `{alt_name}` instead.'
+    docstring = '.. deprecated:: {}\n'.format(version)
+    docstring += dedent('    ' + ('\n'.join(wrap(msg, 70))))
+
+    if getattr(wrapper, '__doc__') is not None:
+        docstring += dedent(wrapper.__doc__)
+
+    wrapper.__doc__ = docstring
+
     return wrapper
 
 

scripts/announce.py

@@ -30,7 +30,7 @@
 
 From the bash command line with $GITHUB token.
 
-    $ ./scripts/announce $GITHUB v1.11.0..v1.11.1 > announce.rst
+    $ ./scripts/announce.py $GITHUB v1.11.0..v1.11.1 > announce.rst
 
 """
 from __future__ import print_function, division

scripts/api_rst_coverage.py

@@ -1,3 +1,22 @@
+#!/usr/bin/env python
+# -*- encoding: utf-8 -*-
+"""
+Script to generate a report with the coverage of the API in the docs.
+
+The output of this script shows the existing methods that are not
+included in the API documentation, as well as the methods documented
+that do not exist. Ideally, no method should be listed. Currently it
+considers the methods of Series, DataFrame and Panel.
+
+Deprecated methods are usually removed from the documentation, while
+still available for three minor versions. They are listed with the
+word deprecated and the version number next to them.
+
+Usage::
+
+    $ PYTHONPATH=.. ./api_rst_coverage.py
+
+"""
 import pandas as pd
 import inspect
 import re
@@ -13,6 +32,32 @@ def class_name_sort_key(x):
         else:
             return x
 
+    def get_docstring(x):
+        class_name, method = x.split('.')
+        obj = getattr(getattr(pd, class_name), method)
+        return obj.__doc__
+
+    def deprecation_version(x):
+        pattern = re.compile('\.\. deprecated:: ([0-9]+\.[0-9]+\.[0-9]+)')
+        doc = get_docstring(x)
+        match = pattern.search(doc)
+        if match:
+            return match.groups()[0]
+
+    def add_notes(x):
+        # Some methods are not documented in api.rst because they
+        # have been deprecated. Adding a comment to detect them easier.
+        doc = get_docstring(x)
+        note = None
+        if not doc:
+            note = 'no docstring'
+        else:
+            version = deprecation_version(x)
+            if version:
+                note = 'deprecated in {}'.format(version)
+
+        return '{} ({})'.format(x, note) if note else x
+
     # class members
     class_members = set()
     for cls in classes:
@@ -34,10 +79,12 @@ def class_name_sort_key(x):
         print(x)
 
     print()
-    print("Class members (other than those beginning with '_') missing from api.rst:")
-    for x in sorted(class_members.difference(api_rst_members), key=class_name_sort_key):
+    print("Class members (other than those beginning with '_') "
+          "missing from api.rst:")
+    for x in sorted(class_members.difference(api_rst_members),
+                    key=class_name_sort_key):
         if '._' not in x:
-            print(x)
+            print(add_notes(x))
 
 if __name__ == "__main__":
     main()