From 0673b512bb8dba5592ef5d9f4c087bb9fee6cdcc Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 6 Jan 2018 13:54:46 +0000 Subject: [PATCH] DOC: Using deprecated sphinx directive instead of non-standard messages in docstrings (#18928) --- ci/lint.sh | 4 ++ doc/source/contributing.rst | 25 ++++++++++- pandas/__init__.py | 2 +- pandas/_libs/tslibs/timestamps.pyx | 3 -- pandas/computation/expressions.py | 4 ++ pandas/core/categorical.py | 3 +- pandas/core/datetools.py | 6 ++- pandas/core/dtypes/common.py | 12 +++-- pandas/core/frame.py | 30 ++++++------- pandas/core/generic.py | 27 ++++++------ pandas/core/indexes/datetimelike.py | 5 ++- pandas/core/panel.py | 6 +-- pandas/core/series.py | 68 +++++++++++++++++------------ pandas/core/sparse/frame.py | 4 +- pandas/core/sparse/series.py | 14 +++--- pandas/core/strings.py | 3 +- pandas/util/_decorators.py | 33 ++++++++++---- scripts/announce.py | 2 +- scripts/api_rst_coverage.py | 53 ++++++++++++++++++++-- 19 files changed, 204 insertions(+), 100 deletions(-) mode change 100644 => 100755 scripts/api_rst_coverage.py diff --git a/ci/lint.sh b/ci/lint.sh index b4eafcaf28e39..d00e0c9afb6dc 100755 --- a/ci/lint.sh +++ b/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 diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 83437022563d5..dc07104f64c65 100644 --- a/doc/source/contributing.rst +++ b/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: diff --git a/pandas/__init__.py b/pandas/__init__.py index 93c5b6484b840..78501620d780b 100644 --- a/pandas/__init__.py +++ b/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 diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index ffc1c89dd8adf..de31643742d87 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/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 diff --git a/pandas/computation/expressions.py b/pandas/computation/expressions.py index f46487cfa1b79..d194cd2404c9d 100644 --- a/pandas/computation/expressions.py +++ b/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 " diff --git a/pandas/core/categorical.py b/pandas/core/categorical.py index d47cb0762447b..630b68e9ed4a6 100644 --- a/pandas/core/categorical.py +++ b/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) diff --git a/pandas/core/datetools.py b/pandas/core/datetools.py index 3444d09c6ed1b..83167a45369c4 100644 --- a/pandas/core/datetools.py +++ b/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 diff --git a/pandas/core/dtypes/common.py b/pandas/core/dtypes/common.py index e2ee3deb5396e..5d6fc7487eeb5 100644 --- a/pandas/core/dtypes/common.py +++ b/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`. """ diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 821db3c263885..62993a3d168db 100644 --- a/pandas/core/frame.py +++ b/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 ---------- diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 37247ab133948..c9672a43a95a8 100644 --- a/pandas/core/generic.py +++ b/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 ---------- diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index ee2fdd213dd9a..07e001007d58d 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/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* """ diff --git a/pandas/core/panel.py b/pandas/core/panel.py index 1c401c4854306..26e7c192ad0af 100644 --- a/pandas/core/panel.py +++ b/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 diff --git a/pandas/core/series.py b/pandas/core/series.py index 5d8092fd30496..71cded4f9c888 100644 --- a/pandas/core/series.py +++ b/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) diff --git a/pandas/core/sparse/frame.py b/pandas/core/sparse/frame.py index 05f39a8caa6f6..49a0b8d86ad31 100644 --- a/pandas/core/sparse/frame.py +++ b/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 diff --git a/pandas/core/sparse/series.py b/pandas/core/sparse/series.py index 8a38b1054a1f5..b5d2c0b607444 100644 --- a/pandas/core/sparse/series.py +++ b/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,7 +681,7 @@ 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, @@ -687,7 +689,7 @@ def isna(self): 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, diff --git a/pandas/core/strings.py b/pandas/core/strings.py index 3b7ec2ad8a508..e0012c25e366d 100644 --- a/pandas/core/strings.py +++ b/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 ------- diff --git a/pandas/util/_decorators.py b/pandas/util/_decorators.py index 6be6152b09fc8..eed9cee54efb3 100644 --- a/pandas/util/_decorators.py +++ b/pandas/util/_decorators.py @@ -7,10 +7,15 @@ 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 ---------- @@ -18,6 +23,8 @@ def deprecate(name, alternative, alt_name=None, klass=None, 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 diff --git a/scripts/announce.py b/scripts/announce.py index 1459d2fc18d2a..7b7933eba54dd 100644 --- a/scripts/announce.py +++ b/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 diff --git a/scripts/api_rst_coverage.py b/scripts/api_rst_coverage.py old mode 100644 new mode 100755 index 45340ba0923c4..28e761ef256d0 --- a/scripts/api_rst_coverage.py +++ b/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()