From 778c2c16a539ec4af58aad08cf766c258e42228e Mon Sep 17 00:00:00 2001 From: dilex Date: Tue, 24 Mar 2020 11:07:08 +0200 Subject: [PATCH 1/5] DOC: Partial fix SA04 errors in docstrings #28792 --- pandas/core/accessor.py | 13 ++++-- pandas/core/arrays/categorical.py | 72 +++++++++++++++---------------- pandas/core/dtypes/dtypes.py | 2 +- pandas/core/indexes/multi.py | 3 +- pandas/io/html.py | 2 +- pandas/io/sql.py | 2 +- pandas/plotting/_misc.py | 7 +-- pandas/tseries/frequencies.py | 2 +- 8 files changed, 56 insertions(+), 47 deletions(-) diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py index fc40f1db1918a..551c3688e9757 100644 --- a/pandas/core/accessor.py +++ b/pandas/core/accessor.py @@ -282,7 +282,8 @@ def decorator(accessor): @doc( _register_accessor, klass="DataFrame", - others="register_series_accessor, register_index_accessor", + others=("register_series_accessor : Register a custom accessor on Series objects.\n" + "register_index_accessor : Register a custom accessor on Index objects."), ) def register_dataframe_accessor(name): from pandas import DataFrame @@ -293,7 +294,12 @@ def register_dataframe_accessor(name): @doc( _register_accessor, klass="Series", - others="register_dataframe_accessor, register_index_accessor", + others=""" + register_dataframe_accessor : Register a custom accessor on + DataFrame objects. + register_index_accessor : Register a custom accessor on + Index objects. + """, ) def register_series_accessor(name): from pandas import Series @@ -304,7 +310,8 @@ def register_series_accessor(name): @doc( _register_accessor, klass="Index", - others="register_dataframe_accessor, register_series_accessor", + others="""register_dataframe_accessor : Register a custom accessor on DataFrame objects. + register_series_accessor : Register a custom accessor on Series objects.""", ) def register_index_accessor(name): from pandas import Index diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 497a9893e6c66..8969cccbd57df 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -416,12 +416,12 @@ def categories(self): See Also -------- - rename_categories - reorder_categories - add_categories - remove_categories - remove_unused_categories - set_categories + rename_categories : Rename categories. + reorder_categories : Reorder categories. + add_categories : Add new categories. + remove_categories : Remove the specified categories. + remove_unused_categories : Remove categories which are not used. + set_categories : Set the categories to the specified categories. """ return self.dtype.categories @@ -834,11 +834,11 @@ def set_categories(self, new_categories, ordered=None, rename=False, inplace=Fal See Also -------- - rename_categories - reorder_categories - add_categories - remove_categories - remove_unused_categories + rename_categories : Rename categories. + reorder_categories : Reorder categories. + add_categories : Add new categories. + remove_categories : Remove the specified categories. + remove_unused_categories : Remove categories which are not used. """ inplace = validate_bool_kwarg(inplace, "inplace") if ordered is None: @@ -905,11 +905,11 @@ def rename_categories(self, new_categories, inplace=False): See Also -------- - reorder_categories - add_categories - remove_categories - remove_unused_categories - set_categories + reorder_categories : Reorder categories. + add_categories : Add new categories. + remove_categories : Remove the specified categories. + remove_unused_categories : Remove categories which are not used. + set_categories : Set the categories to the specified categories. Examples -------- @@ -973,11 +973,11 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False): See Also -------- - rename_categories - add_categories - remove_categories - remove_unused_categories - set_categories + rename_categories : Rename categories. + add_categories : Add new categories. + remove_categories : Remove the specified categories. + remove_unused_categories : Remove categories which are not used. + set_categories : Set the categories to the specified categories. """ inplace = validate_bool_kwarg(inplace, "inplace") if set(self.dtype.categories) != set(new_categories): @@ -1013,11 +1013,11 @@ def add_categories(self, new_categories, inplace=False): See Also -------- - rename_categories - reorder_categories - remove_categories - remove_unused_categories - set_categories + rename_categories : Rename categories. + reorder_categories : Reorder categories. + remove_categories : Remove the specified categories. + remove_unused_categories : Remove categories which are not used. + set_categories : Set the categories to the specified categories. """ inplace = validate_bool_kwarg(inplace, "inplace") if not is_list_like(new_categories): @@ -1062,11 +1062,11 @@ def remove_categories(self, removals, inplace=False): See Also -------- - rename_categories - reorder_categories - add_categories - remove_unused_categories - set_categories + rename_categories : Rename categories. + reorder_categories : Reorder categories. + add_categories : Add new categories. + remove_unused_categories : Remove categories which are not used. + set_categories : Set the categories to the specified categories. """ inplace = validate_bool_kwarg(inplace, "inplace") if not is_list_like(removals): @@ -1104,11 +1104,11 @@ def remove_unused_categories(self, inplace=False): See Also -------- - rename_categories - reorder_categories - add_categories - remove_categories - set_categories + rename_categories : Rename categories. + reorder_categories : Reorder categories. + add_categories : Add new categories. + remove_categories : Remove the specified categories. + set_categories : Set the categories to the specified categories. """ inplace = validate_bool_kwarg(inplace, "inplace") cat = self if inplace else self.copy() diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index d29102cbd4604..ef681cb204598 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -194,7 +194,7 @@ class CategoricalDtype(PandasExtensionDtype, ExtensionDtype): See Also -------- - Categorical + Categorical : Represent a categorical variable in classic R / S-plus fashion. Notes ----- diff --git a/pandas/core/indexes/multi.py b/pandas/core/indexes/multi.py index d30765217390f..3ab3870fbd466 100644 --- a/pandas/core/indexes/multi.py +++ b/pandas/core/indexes/multi.py @@ -1566,7 +1566,8 @@ def to_frame(self, index=True, name=None): See Also -------- - DataFrame + DataFrame : Two-dimensional, size-mutable, potentially heterogeneous + tabular data. """ from pandas import DataFrame diff --git a/pandas/io/html.py b/pandas/io/html.py index 9efdacadce83e..ce6674ffb9588 100644 --- a/pandas/io/html.py +++ b/pandas/io/html.py @@ -1036,7 +1036,7 @@ def read_html( See Also -------- - read_csv + read_csv : Read a comma-separated values (csv) file into DataFrame. Notes ----- diff --git a/pandas/io/sql.py b/pandas/io/sql.py index 560e7e4781cbb..491c45e95e7e7 100644 --- a/pandas/io/sql.py +++ b/pandas/io/sql.py @@ -313,7 +313,7 @@ def read_sql_query( See Also -------- read_sql_table : Read SQL database table into a DataFrame. - read_sql + read_sql : Read SQL query or database table into a DataFrame. Notes ----- diff --git a/pandas/plotting/_misc.py b/pandas/plotting/_misc.py index 47a4fd8ff0e95..aef8c60f27b2d 100644 --- a/pandas/plotting/_misc.py +++ b/pandas/plotting/_misc.py @@ -29,7 +29,7 @@ def table(ax, data, rowLabels=None, colLabels=None, **kwargs): def register(): """ - Register Pandas Formatters and Converters with matplotlib. + Register pandas Formatters and Converters with matplotlib. This function modifies the global ``matplotlib.units.registry`` dictionary. Pandas adds custom converters for @@ -43,7 +43,7 @@ def register(): See Also -------- - deregister_matplotlib_converters + deregister_matplotlib_converters : Remove pandas’ formatters and converters. """ plot_backend = _get_plot_backend("matplotlib") plot_backend.register() @@ -62,7 +62,8 @@ def deregister(): See Also -------- - register_matplotlib_converters + register_matplotlib_converters : Register pandas Formatters and Converters + with matplotlib. """ plot_backend = _get_plot_backend("matplotlib") plot_backend.deregister() diff --git a/pandas/tseries/frequencies.py b/pandas/tseries/frequencies.py index 2477ff29fbfd5..b1a451d38cb15 100644 --- a/pandas/tseries/frequencies.py +++ b/pandas/tseries/frequencies.py @@ -91,7 +91,7 @@ def to_offset(freq) -> Optional[DateOffset]: See Also -------- - DateOffset + DateOffset : Standard kind of date increment used for a date range. Examples -------- From d46b39c8449a5235695c1e00d697ab8979d9ffb3 Mon Sep 17 00:00:00 2001 From: dilex Date: Tue, 24 Mar 2020 11:52:24 +0200 Subject: [PATCH 2/5] DOC: Partial fix SA04 errors in docstrings #28792 --- pandas/core/accessor.py | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py index 551c3688e9757..62406b7f537d6 100644 --- a/pandas/core/accessor.py +++ b/pandas/core/accessor.py @@ -211,7 +211,9 @@ def _register_accessor(name, cls): See Also -------- - {others} + register_dataframe_accessor : Register a custom accessor on DataFrame objects. + register_series_accessor : Register a custom accessor on Series objects. + register_index_accessor : Register a custom accessor on Index objects. Notes ----- @@ -282,8 +284,6 @@ def decorator(accessor): @doc( _register_accessor, klass="DataFrame", - others=("register_series_accessor : Register a custom accessor on Series objects.\n" - "register_index_accessor : Register a custom accessor on Index objects."), ) def register_dataframe_accessor(name): from pandas import DataFrame @@ -294,12 +294,6 @@ def register_dataframe_accessor(name): @doc( _register_accessor, klass="Series", - others=""" - register_dataframe_accessor : Register a custom accessor on - DataFrame objects. - register_index_accessor : Register a custom accessor on - Index objects. - """, ) def register_series_accessor(name): from pandas import Series @@ -310,8 +304,6 @@ def register_series_accessor(name): @doc( _register_accessor, klass="Index", - others="""register_dataframe_accessor : Register a custom accessor on DataFrame objects. - register_series_accessor : Register a custom accessor on Series objects.""", ) def register_index_accessor(name): from pandas import Index From cb62a811de7adc4747e607e37d4a4937205893d7 Mon Sep 17 00:00:00 2001 From: dilex Date: Tue, 24 Mar 2020 12:28:50 +0200 Subject: [PATCH 3/5] formatting --- pandas/core/accessor.py | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py index 62406b7f537d6..36847b6fcaa37 100644 --- a/pandas/core/accessor.py +++ b/pandas/core/accessor.py @@ -282,8 +282,7 @@ def decorator(accessor): @doc( - _register_accessor, - klass="DataFrame", + _register_accessor, klass="DataFrame", ) def register_dataframe_accessor(name): from pandas import DataFrame @@ -292,8 +291,7 @@ def register_dataframe_accessor(name): @doc( - _register_accessor, - klass="Series", + _register_accessor, klass="Series", ) def register_series_accessor(name): from pandas import Series @@ -302,8 +300,7 @@ def register_series_accessor(name): @doc( - _register_accessor, - klass="Index", + _register_accessor, klass="Index", ) def register_index_accessor(name): from pandas import Index From a9f1bdda5e1fc07ac14860d8cb7a243b6b17f8f0 Mon Sep 17 00:00:00 2001 From: dilex42 Date: Wed, 25 Mar 2020 11:48:24 +0200 Subject: [PATCH 4/5] Apply suggestions from code review Co-Authored-By: Marc Garcia --- pandas/core/arrays/categorical.py | 12 ++++++------ pandas/plotting/_misc.py | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index a6786958b7fee..e13c9954a26fc 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -421,7 +421,7 @@ def categories(self): add_categories : Add new categories. remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. """ return self.dtype.categories @@ -905,7 +905,7 @@ def rename_categories(self, new_categories, inplace=False): add_categories : Add new categories. remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. Examples -------- @@ -973,7 +973,7 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False): add_categories : Add new categories. remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. """ inplace = validate_bool_kwarg(inplace, "inplace") if set(self.dtype.categories) != set(new_categories): @@ -1013,7 +1013,7 @@ def add_categories(self, new_categories, inplace=False): reorder_categories : Reorder categories. remove_categories : Remove the specified categories. remove_unused_categories : Remove categories which are not used. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. """ inplace = validate_bool_kwarg(inplace, "inplace") if not is_list_like(new_categories): @@ -1062,7 +1062,7 @@ def remove_categories(self, removals, inplace=False): reorder_categories : Reorder categories. add_categories : Add new categories. remove_unused_categories : Remove categories which are not used. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. """ inplace = validate_bool_kwarg(inplace, "inplace") if not is_list_like(removals): @@ -1104,7 +1104,7 @@ def remove_unused_categories(self, inplace=False): reorder_categories : Reorder categories. add_categories : Add new categories. remove_categories : Remove the specified categories. - set_categories : Set the categories to the specified categories. + set_categories : Set the categories to the specified ones. """ inplace = validate_bool_kwarg(inplace, "inplace") cat = self if inplace else self.copy() diff --git a/pandas/plotting/_misc.py b/pandas/plotting/_misc.py index aef8c60f27b2d..66da9b7e6f4a8 100644 --- a/pandas/plotting/_misc.py +++ b/pandas/plotting/_misc.py @@ -29,7 +29,7 @@ def table(ax, data, rowLabels=None, colLabels=None, **kwargs): def register(): """ - Register pandas Formatters and Converters with matplotlib. + Register pandas formatters and converters with matplotlib. This function modifies the global ``matplotlib.units.registry`` dictionary. Pandas adds custom converters for @@ -62,7 +62,7 @@ def deregister(): See Also -------- - register_matplotlib_converters : Register pandas Formatters and Converters + register_matplotlib_converters : Register pandas formatters and fonverters with matplotlib. """ plot_backend = _get_plot_backend("matplotlib") From eef2558122d0e760fc6e828607fbba9651e6fe05 Mon Sep 17 00:00:00 2001 From: drollolo Date: Sun, 29 Mar 2020 10:51:31 +0300 Subject: [PATCH 5/5] Apply suggestions from code review --- pandas/core/accessor.py | 12 +++--------- pandas/plotting/_misc.py | 12 ++++++------ 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/pandas/core/accessor.py b/pandas/core/accessor.py index 36847b6fcaa37..b6ca19bde8009 100644 --- a/pandas/core/accessor.py +++ b/pandas/core/accessor.py @@ -281,27 +281,21 @@ def decorator(accessor): return decorator -@doc( - _register_accessor, klass="DataFrame", -) +@doc(_register_accessor, klass="DataFrame") def register_dataframe_accessor(name): from pandas import DataFrame return _register_accessor(name, DataFrame) -@doc( - _register_accessor, klass="Series", -) +@doc(_register_accessor, klass="Series") def register_series_accessor(name): from pandas import Series return _register_accessor(name, Series) -@doc( - _register_accessor, klass="Index", -) +@doc(_register_accessor, klass="Index") def register_index_accessor(name): from pandas import Index diff --git a/pandas/plotting/_misc.py b/pandas/plotting/_misc.py index 66da9b7e6f4a8..905b57f4c76e3 100644 --- a/pandas/plotting/_misc.py +++ b/pandas/plotting/_misc.py @@ -32,7 +32,7 @@ def register(): Register pandas formatters and converters with matplotlib. This function modifies the global ``matplotlib.units.registry`` - dictionary. Pandas adds custom converters for + dictionary. pandas adds custom converters for * pd.Timestamp * pd.Period @@ -43,7 +43,7 @@ def register(): See Also -------- - deregister_matplotlib_converters : Remove pandas’ formatters and converters. + deregister_matplotlib_converters : Remove pandas formatters and converters. """ plot_backend = _get_plot_backend("matplotlib") plot_backend.register() @@ -51,7 +51,7 @@ def register(): def deregister(): """ - Remove pandas' formatters and converters. + Remove pandas formatters and converters. Removes the custom converters added by :func:`register`. This attempts to set the state of the registry back to the state before @@ -62,7 +62,7 @@ def deregister(): See Also -------- - register_matplotlib_converters : Register pandas formatters and fonverters + register_matplotlib_converters : Register pandas formatters and converters with matplotlib. """ plot_backend = _get_plot_backend("matplotlib") @@ -156,7 +156,7 @@ def radviz(frame, class_column, ax=None, color=None, colormap=None, **kwds): Parameters ---------- frame : `DataFrame` - Pandas object holding the data. + pandas object holding the data. class_column : str Column name containing the name of the data point category. ax : :class:`matplotlib.axes.Axes`, optional @@ -271,7 +271,7 @@ def bootstrap_plot(series, fig=None, size=50, samples=500, **kwds): Parameters ---------- series : pandas.Series - Pandas Series from where to get the samplings for the bootstrapping. + pandas Series from where to get the samplings for the bootstrapping. fig : matplotlib.figure.Figure, default None If given, it will use the `fig` reference for plotting instead of creating a new one with default parameters.