From 71556272e251fd863ae36bc35abd7db04d787c83 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Fri, 9 Mar 2018 12:31:09 +0100 Subject: [PATCH 1/3] Clean-up shared_docs --- pandas/core/frame.py | 6 +-- pandas/core/generic.py | 92 +++++++++++------------------------- pandas/core/panel.py | 13 +++-- pandas/core/series.py | 8 ++-- pandas/core/sparse/series.py | 4 +- 5 files changed, 47 insertions(+), 76 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index a66d00fff9714..50d758b6ab70d 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -3011,7 +3011,7 @@ def align(self, other, join='outer', axis=None, level=None, copy=True, fill_axis=fill_axis, broadcast_axis=broadcast_axis) - @Appender(_shared_docs['reindex'] % _shared_doc_kwargs) + @Appender(NDFrame.reindex.__doc__ % _shared_doc_kwargs) @rewrite_axis_style_signature('labels', [('method', None), ('copy', True), ('level', None), @@ -3691,7 +3691,7 @@ def f(vals): # ---------------------------------------------------------------------- # Sorting - @Appender(_shared_docs['sort_values'] % _shared_doc_kwargs) + @Appender(NDFrame.sort_values.__doc__ % _shared_doc_kwargs) def sort_values(self, by, axis=0, ascending=True, inplace=False, kind='quicksort', na_position='last'): inplace = validate_bool_kwarg(inplace, 'inplace') @@ -3736,7 +3736,7 @@ def sort_values(self, by, axis=0, ascending=True, inplace=False, else: return self._constructor(new_data).__finalize__(self) - @Appender(_shared_docs['sort_index'] % _shared_doc_kwargs) + @Appender(NDFrame.sort_index.__doc__ % _shared_doc_kwargs) def sort_index(self, axis=0, level=None, ascending=True, inplace=False, kind='quicksort', na_position='last', sort_remaining=True, by=None): diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..c4e0a49775fad 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -487,7 +487,8 @@ def _expand_axes(self, key): return new_axes - _shared_docs['set_axis'] = """Assign desired index to given axis + def set_axis(self, labels, axis=0, inplace=None): + """Assign desired index to given axis Parameters ---------- @@ -547,9 +548,6 @@ def _expand_axes(self, key): 2 3 6 """ - - @Appender(_shared_docs['set_axis'] % dict(klass='NDFrame')) - def set_axis(self, labels, axis=0, inplace=None): if is_scalar(labels): warnings.warn( 'set_axis now takes "labels" as first argument, and ' @@ -577,7 +575,8 @@ def _set_axis(self, axis, labels): self._data.set_axis(axis, labels) self._clear_item_cache() - _shared_docs['transpose'] = """ + def transpose(self, *args, **kwargs): + """ Permute the dimensions of the %(klass)s Parameters @@ -597,9 +596,6 @@ def _set_axis(self, axis, labels): y : same as input """ - @Appender(_shared_docs['transpose'] % _shared_doc_kwargs) - def transpose(self, *args, **kwargs): - # construct the args axes, kwargs = self._construct_axes_from_arguments(args, kwargs, require_all=True) @@ -749,9 +745,8 @@ def swaplevel(self, i=-2, j=-1, axis=0): # ---------------------------------------------------------------------- # Rename - # TODO: define separate funcs for DataFrame, Series and Panel so you can - # get completion on keyword arguments. - _shared_docs['rename'] = """ + def rename(self, *args, **kwargs): + """ Alter axes input function or functions. Function / dict values must be unique (1-to-1). Labels not contained in a dict / Series will be left as-is. Extra labels listed don't throw an error. Alternatively, change @@ -759,13 +754,11 @@ def swaplevel(self, i=-2, j=-1, axis=0): Parameters ---------- - %(optional_mapper)s %(axes)s : scalar, list-like, dict-like or function, optional Scalar or list-like will alter the ``Series.name`` attribute, and raise on DataFrame or Panel. dict-like or functions are transformations to apply to that axis' values - %(optional_axis)s copy : boolean, default True Also copy underlying data inplace : boolean, default False @@ -853,12 +846,6 @@ def swaplevel(self, i=-2, j=-1, axis=0): See the :ref:`user guide ` for more. """ - - @Appender(_shared_docs['rename'] % dict(axes='axes keywords for this' - ' object', klass='NDFrame', - optional_mapper='', - optional_axis='')) - def rename(self, *args, **kwargs): axes, kwargs = self._construct_axes_from_arguments(args, kwargs) copy = kwargs.pop('copy', True) inplace = kwargs.pop('inplace', False) @@ -910,8 +897,6 @@ def f(x): else: return result.__finalize__(self) - rename.__doc__ = _shared_docs['rename'] - def rename_axis(self, mapper, axis=0, copy=True, inplace=False): """Alter the name of the index or columns. @@ -2060,7 +2045,13 @@ def to_xarray(self): coords=coords, ) - _shared_docs['to_latex'] = r""" + def to_latex(self, buf=None, columns=None, col_space=None, header=True, + index=True, na_rep='NaN', formatters=None, float_format=None, + sparsify=None, index_names=True, bold_rows=False, + column_format=None, longtable=None, escape=None, + encoding=None, decimal='.', multicolumn=None, + multicolumn_format=None, multirow=None): + r""" Render an object to a tabular environment table. You can splice this into a LaTeX document. Requires \\usepackage{booktabs}. @@ -2111,18 +2102,7 @@ def to_xarray(self): The default will be read from the pandas config module. .. versionadded:: 0.20.0 - """ - - @Substitution(header='Write out the column names. If a list of strings ' - 'is given, it is assumed to be aliases for the ' - 'column names.') - @Appender(_shared_docs['to_latex'] % _shared_doc_kwargs) - def to_latex(self, buf=None, columns=None, col_space=None, header=True, - index=True, na_rep='NaN', formatters=None, float_format=None, - sparsify=None, index_names=True, bold_rows=False, - column_format=None, longtable=None, escape=None, - encoding=None, decimal='.', multicolumn=None, - multicolumn_format=None, multirow=None): + """ # Get defaults from the pandas config if self.ndim == 1: self = self.to_frame() @@ -2454,7 +2434,8 @@ def __delitem__(self, key): except KeyError: pass - _shared_docs['_take'] = """ + def _take(self, indices, axis=0, convert=True, is_copy=True): + """ Return the elements in the given *positional* indices along an axis. This means that we are not indexing according to actual values in @@ -2490,9 +2471,6 @@ def __delitem__(self, key): numpy.ndarray.take numpy.take """ - - @Appender(_shared_docs['_take']) - def _take(self, indices, axis=0, convert=True, is_copy=True): self._consolidate_inplace() if convert: @@ -2510,7 +2488,8 @@ def _take(self, indices, axis=0, convert=True, is_copy=True): return result - _shared_docs['take'] = """ + def take(self, indices, axis=0, convert=None, is_copy=True, **kwargs): + """ Return the elements in the given *positional* indices along an axis. This means that we are not indexing according to actual values in @@ -2587,9 +2566,6 @@ class max_speed numpy.ndarray.take numpy.take """ - - @Appender(_shared_docs['take']) - def take(self, indices, axis=0, convert=None, is_copy=True, **kwargs): if convert is not None: msg = ("The 'convert' parameter is deprecated " "and will be removed in a future version.") @@ -2991,7 +2967,9 @@ def add_suffix(self, suffix): new_data = self._data.add_suffix(suffix) return self._constructor(new_data).__finalize__(self) - _shared_docs['sort_values'] = """ + def sort_values(self, by=None, axis=0, ascending=True, inplace=False, + kind='quicksort', na_position='last'): + """ Sort by the values along either axis Parameters @@ -3076,17 +3054,12 @@ def add_suffix(self, suffix): 0 A 2 0 1 A 1 1 """ - - def sort_values(self, by=None, axis=0, ascending=True, inplace=False, - kind='quicksort', na_position='last'): - """ - NOT IMPLEMENTED: do not call this method, as sorting values is not - supported for Panel objects and will raise an error. - """ raise NotImplementedError("sort_values has not been implemented " "on Panel or Panel4D objects.") - _shared_docs['sort_index'] = """ + def sort_index(self, axis=0, level=None, ascending=True, inplace=False, + kind='quicksort', na_position='last', sort_remaining=True): + """ Sort object by labels (along an axis) Parameters @@ -3114,10 +3087,6 @@ def sort_values(self, by=None, axis=0, ascending=True, inplace=False, ------- sorted_obj : %(klass)s """ - - @Appender(_shared_docs['sort_index'] % dict(axes="axes", klass="NDFrame")) - def sort_index(self, axis=0, level=None, ascending=True, inplace=False, - kind='quicksort', na_position='last', sort_remaining=True): inplace = validate_bool_kwarg(inplace, 'inplace') axis = self._get_axis_number(axis) axis_name = self._get_axis_name(axis) @@ -3135,7 +3104,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, new_axis = labels.take(sort_index) return self.reindex(**{axis_name: new_axis}) - _shared_docs['reindex'] = """ + def reindex(self, *args, **kwargs): + """ Conform %(klass)s to new index with optional filling logic, placing NA/NaN in locations having no value in the previous index. A new object is produced unless the new index is equivalent to the current one and @@ -3331,14 +3301,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False, ------- reindexed : %(klass)s """ - - # TODO: Decide if we care about having different examples for different - # kinds - - @Appender(_shared_docs['reindex'] % dict(axes="axes", klass="NDFrame", - optional_labels="", - optional_axis="")) - def reindex(self, *args, **kwargs): + # TODO: Decide if we care about having different examples for different + # kinds # construct the args axes, kwargs = self._construct_axes_from_arguments(args, kwargs) diff --git a/pandas/core/panel.py b/pandas/core/panel.py index 052d555df76f1..f8d5bd72e7e38 100644 --- a/pandas/core/panel.py +++ b/pandas/core/panel.py @@ -1198,7 +1198,7 @@ def _wrap_result(self, result, axis): return self._construct_return_type(result, axes) - @Appender(_shared_docs['reindex'] % _shared_doc_kwargs) + @Appender(NDFrame.reindex.__doc__ % _shared_doc_kwargs) def reindex(self, *args, **kwargs): major = kwargs.pop("major", None) minor = kwargs.pop('minor', None) @@ -1219,7 +1219,7 @@ def reindex(self, *args, **kwargs): kwargs.pop('labels', None) return super(Panel, self).reindex(**kwargs) - @Appender(_shared_docs['rename'] % _shared_doc_kwargs) + @Appender(NDFrame.rename.__doc__ % _shared_doc_kwargs) def rename(self, items=None, major_axis=None, minor_axis=None, **kwargs): major_axis = (major_axis if major_axis is not None else kwargs.pop('major', None)) @@ -1236,7 +1236,7 @@ def reindex_axis(self, labels, axis=0, method=None, level=None, copy=True, copy=copy, limit=limit, fill_value=fill_value) - @Appender(_shared_docs['transpose'] % _shared_doc_kwargs) + @Appender(NDFrame.transpose.__doc__ % _shared_doc_kwargs) def transpose(self, *args, **kwargs): # check if a list of axes was passed in instead as a # single *args element @@ -1518,6 +1518,13 @@ def _extract_axis(self, data, axis=0, intersect=False): return _ensure_index(index) + def sort_values(self, *args, **kwargs): + """ + NOT IMPLEMENTED: do not call this method, as sorting values is not + supported for Panel objects and will raise an error. + """ + super(Panel, self).sort_values(*args, **kwargs) + Panel._setup_axes(axes=['items', 'major_axis', 'minor_axis'], info_axis=0, stat_axis=1, aliases={'major': 'major_axis', diff --git a/pandas/core/series.py b/pandas/core/series.py index 069f0372ab6e1..52b7c39287045 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -1885,7 +1885,7 @@ def update(self, other): # ---------------------------------------------------------------------- # Reindexing, sorting - @Appender(generic._shared_docs['sort_values'] % _shared_doc_kwargs) + @Appender(generic.NDFrame.sort_values.__doc__ % _shared_doc_kwargs) def sort_values(self, axis=0, ascending=True, inplace=False, kind='quicksort', na_position='last'): @@ -1947,7 +1947,7 @@ def _try_kind_sort(arr): else: return result.__finalize__(self) - @Appender(generic._shared_docs['sort_index'] % _shared_doc_kwargs) + @Appender(generic.NDFrame.sort_index.__doc__ % _shared_doc_kwargs) def sort_index(self, axis=0, level=None, ascending=True, inplace=False, kind='quicksort', na_position='last', sort_remaining=True): @@ -2656,7 +2656,7 @@ def rename(self, index=None, **kwargs): return self._set_name(index, inplace=kwargs.get('inplace')) return super(Series, self).rename(index=index, **kwargs) - @Appender(generic._shared_docs['reindex'] % _shared_doc_kwargs) + @Appender(generic.NDFrame.reindex.__doc__ % _shared_doc_kwargs) def reindex(self, index=None, **kwargs): return super(Series, self).reindex(index=index, **kwargs) @@ -2724,7 +2724,7 @@ def memory_usage(self, index=True, deep=False): v += self.index.memory_usage(deep=deep) return v - @Appender(generic._shared_docs['_take']) + @Appender(generic.NDFrame._take.__doc__) def _take(self, indices, axis=0, convert=True, is_copy=False): if convert: indices = maybe_convert_indices(indices, len(self._get_axis(axis))) diff --git a/pandas/core/sparse/series.py b/pandas/core/sparse/series.py index 714cd09a27294..7d64422f8fe33 100644 --- a/pandas/core/sparse/series.py +++ b/pandas/core/sparse/series.py @@ -562,7 +562,7 @@ def copy(self, deep=True): return self._constructor(new_data, sparse_index=self.sp_index, fill_value=self.fill_value).__finalize__(self) - @Appender(generic._shared_docs['reindex'] % _shared_doc_kwargs) + @Appender(generic.NDFrame.reindex.__doc__ % _shared_doc_kwargs) def reindex(self, index=None, method=None, copy=True, limit=None, **kwargs): @@ -591,7 +591,7 @@ def sparse_reindex(self, new_index): sparse_index=new_index, fill_value=self.fill_value).__finalize__(self) - @Appender(generic._shared_docs['take']) + @Appender(generic.NDFrame.take.__doc__) def take(self, indices, axis=0, convert=None, *args, **kwargs): if convert is not None: msg = ("The 'convert' parameter is deprecated " From bcfa398b9124a329b3054d69f9569c1a5ee61557 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 1 Oct 2018 13:33:58 +0200 Subject: [PATCH 2/3] Use substitution --- pandas/core/frame.py | 9 ++++++--- pandas/core/panel.py | 9 ++++++--- pandas/core/series.py | 3 ++- pandas/core/sparse/series.py | 3 ++- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 6a42afa036419..15cebb88faea7 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -3629,7 +3629,8 @@ def align(self, other, join='outer', axis=None, level=None, copy=True, fill_axis=fill_axis, broadcast_axis=broadcast_axis) - @Appender(NDFrame.reindex.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.reindex.__doc__) @rewrite_axis_style_signature('labels', [('method', None), ('copy', True), ('level', None), @@ -4479,7 +4480,8 @@ def f(vals): # ---------------------------------------------------------------------- # Sorting - @Appender(NDFrame.sort_values.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.sort_values.__doc__) def sort_values(self, by, axis=0, ascending=True, inplace=False, kind='quicksort', na_position='last'): inplace = validate_bool_kwarg(inplace, 'inplace') @@ -4521,7 +4523,8 @@ def sort_values(self, by, axis=0, ascending=True, inplace=False, else: return self._constructor(new_data).__finalize__(self) - @Appender(NDFrame.sort_index.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.sort_index.__doc__) def sort_index(self, axis=0, level=None, ascending=True, inplace=False, kind='quicksort', na_position='last', sort_remaining=True, by=None): diff --git a/pandas/core/panel.py b/pandas/core/panel.py index cb6272060e5e8..1e2d4000413bb 100644 --- a/pandas/core/panel.py +++ b/pandas/core/panel.py @@ -1215,7 +1215,8 @@ def _wrap_result(self, result, axis): return self._construct_return_type(result, axes) - @Appender(NDFrame.reindex.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.reindex.__doc__) def reindex(self, *args, **kwargs): major = kwargs.pop("major", None) minor = kwargs.pop('minor', None) @@ -1236,7 +1237,8 @@ def reindex(self, *args, **kwargs): kwargs.pop('labels', None) return super(Panel, self).reindex(**kwargs) - @Appender(NDFrame.rename.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.rename.__doc__) def rename(self, items=None, major_axis=None, minor_axis=None, **kwargs): major_axis = (major_axis if major_axis is not None else kwargs.pop('major', None)) @@ -1253,7 +1255,8 @@ def reindex_axis(self, labels, axis=0, method=None, level=None, copy=True, copy=copy, limit=limit, fill_value=fill_value) - @Appender(NDFrame.transpose.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(NDFrame.transpose.__doc__) def transpose(self, *args, **kwargs): # check if a list of axes was passed in instead as a # single *args element diff --git a/pandas/core/series.py b/pandas/core/series.py index b34deeabb0563..82198c2b3edd5 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -3496,7 +3496,8 @@ def rename(self, index=None, **kwargs): return self._set_name(index, inplace=kwargs.get('inplace')) return super(Series, self).rename(index=index, **kwargs) - @Appender(generic.NDFrame.reindex.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(generic.NDFrame.reindex.__doc__) def reindex(self, index=None, **kwargs): return super(Series, self).reindex(index=index, **kwargs) diff --git a/pandas/core/sparse/series.py b/pandas/core/sparse/series.py index e814ed13ed9b7..a7b8c401275bb 100644 --- a/pandas/core/sparse/series.py +++ b/pandas/core/sparse/series.py @@ -563,7 +563,8 @@ def copy(self, deep=True): return self._constructor(new_data, sparse_index=self.sp_index, fill_value=self.fill_value).__finalize__(self) - @Appender(generic.NDFrame.reindex.__doc__ % _shared_doc_kwargs) + @Substitution(**_shared_doc_kwargs) + @Appender(generic.NDFrame.reindex.__doc__) def reindex(self, index=None, method=None, copy=True, limit=None, **kwargs): From 384436f5246a886676abc88d196c8d53ff61d763 Mon Sep 17 00:00:00 2001 From: Joris Van den Bossche Date: Mon, 1 Oct 2018 15:59:45 +0200 Subject: [PATCH 3/3] fix import --- pandas/core/sparse/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/sparse/series.py b/pandas/core/sparse/series.py index a7b8c401275bb..97cd3a0a1fb6a 100644 --- a/pandas/core/sparse/series.py +++ b/pandas/core/sparse/series.py @@ -19,7 +19,7 @@ import pandas.core.indexes.base as ibase import pandas.core.ops as ops import pandas._libs.index as libindex -from pandas.util._decorators import Appender +from pandas.util._decorators import Appender, Substitution from pandas.core.sparse.array import ( make_sparse, SparseArray,