Skip to content

Commit

Permalink
DOC: Using deprecated sphinx directive instead of non-standard messag…
Browse files Browse the repository at this point in the history
…es in docstrings (#18928) (#18934)
  • Loading branch information
datapythonista authored and jreback committed Jan 6, 2018
1 parent 5bd0836 commit 1d32264
Show file tree
Hide file tree
Showing 19 changed files with 204 additions and 100 deletions.
4 changes: 4 additions & 0 deletions ci/lint.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 24 additions & 1 deletion doc/source/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion pandas/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 0 additions & 3 deletions pandas/_libs/tslibs/timestamps.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions pandas/computation/expressions.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 "
Expand Down
3 changes: 2 additions & 1 deletion pandas/core/categorical.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
6 changes: 5 additions & 1 deletion pandas/core/datetools.py
Original file line number Diff line number Diff line change
@@ -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

Expand Down
12 changes: 5 additions & 7 deletions pandas/core/dtypes/common.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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`.
"""
Expand Down
30 changes: 14 additions & 16 deletions pandas/core/frame.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand Down
27 changes: 14 additions & 13 deletions pandas/core/generic.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down Expand Up @@ -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 "
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand Down
5 changes: 3 additions & 2 deletions pandas/core/indexes/datetimelike.py
Original file line number Diff line number Diff line change
Expand Up @@ -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*
"""
Expand Down
6 changes: 2 additions & 4 deletions pandas/core/panel.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 1d32264

Please sign in to comment.