DOC: Using deprecated sphinx directive instead of non-standard messag…

…es in docstrings (#18928) (#18934)

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