From d4a0ddb51fef0e0239581a6a41f091d524279426 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 3 Feb 2024 18:10:25 -0700 Subject: [PATCH 1/4] DOC: fix PR02 errors in docstring for pandas.Series.rename_axis --- ci/code_checks.sh | 1 - pandas/core/generic.py | 54 +++++++++++++++++++++++++----------------- pandas/core/series.py | 34 +++++++++++++++++++++++++- 3 files changed, 65 insertions(+), 24 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index a09c4662a1fd9..7ad3dd509a041 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -93,7 +93,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.TimedeltaIndex.ceil\ pandas.PeriodIndex\ pandas.PeriodIndex.strftime\ - pandas.Series.rename_axis\ pandas.Series.dt.to_period\ pandas.Series.dt.tz_localize\ pandas.Series.dt.tz_convert\ diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 78fbb66635dd1..6d3379b0f2430 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -220,6 +220,8 @@ from pandas.core.indexers.objects import BaseIndexer from pandas.core.resample import Resampler +import textwrap + # goal is to be able to define the docs close to function, while still being # able to share _shared_docs = {**_shared_docs} @@ -1153,34 +1155,24 @@ def rename_axis( ) -> Self | None: ... - def rename_axis( - self, - mapper: IndexLabel | lib.NoDefault = lib.no_default, - *, - index=lib.no_default, - columns=lib.no_default, - axis: Axis = 0, - copy: bool_t | None = None, - inplace: bool_t = False, - ) -> Self | None: - """ - Set the name of the axis for the index or columns. - - Parameters - ---------- + @doc( + extra_parameters=textwrap.dedent( + """\ mapper : scalar, list-like, optional Value to set the axis name attribute. - index, columns : scalar, list-like, dict-like or function, optional + index : scalar, list-like, dict-like or function, optional + A scalar, list-like, dict-like or functions transformations to + apply to that axis' values. + columns : scalar, list-like, dict-like or function, optional A scalar, list-like, dict-like or functions transformations to apply to that axis' values. Note that the ``columns`` parameter is not allowed if the object is a Series. This parameter only apply for DataFrame type objects. - Use either ``mapper`` and ``axis`` to specify the axis to target with ``mapper``, or ``index`` and/or ``columns``. - axis : {0 or 'index', 1 or 'columns'}, default 0 + axis : {{0 or 'index', 1 or 'columns'}}, default 0 The axis to rename. For `Series` this parameter is unused and defaults to 0. copy : bool, default None Also copy underlying data. @@ -1199,7 +1191,25 @@ def rename_axis( inplace : bool, default False Modifies the object directly, instead of creating a new Series or DataFrame. + """ + ), + ) + def rename_axis( + self, + mapper: IndexLabel | lib.NoDefault = lib.no_default, + *, + index=lib.no_default, + columns=lib.no_default, + axis: Axis = 0, + copy: bool_t | None = None, + inplace: bool_t = False, + ) -> Self | None: + """ + Set the name of the axis for the index or columns. + Parameters + ---------- + {extra_parameters} Returns ------- Series, DataFrame, or None @@ -1216,7 +1226,7 @@ def rename_axis( ``DataFrame.rename_axis`` supports two calling conventions * ``(index=index_mapper, columns=columns_mapper, ...)`` - * ``(mapper, axis={'index', 'columns'}, ...)`` + * ``(mapper, axis={{'index', 'columns'}}, ...)`` The first calling convention will only modify the names of the index and/or the names of the Index object that is the columns. @@ -1249,8 +1259,8 @@ def rename_axis( **DataFrame** - >>> df = pd.DataFrame({"num_legs": [4, 4, 2], - ... "num_arms": [0, 0, 2]}, + >>> df = pd.DataFrame({{"num_legs": [4, 4, 2], + ... "num_arms": [0, 0, 2]}}, ... ["dog", "cat", "monkey"]) >>> df num_legs num_arms @@ -1284,7 +1294,7 @@ def rename_axis( cat 4 0 monkey 2 2 - >>> df.rename_axis(index={'type': 'class'}) + >>> df.rename_axis(index={{'type': 'class'}}) limbs num_legs num_arms class name mammal dog 4 0 diff --git a/pandas/core/series.py b/pandas/core/series.py index 657b384c57235..f073c2ec33062 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -207,6 +207,8 @@ from pandas.core.frame import DataFrame from pandas.core.groupby.generic import SeriesGroupBy +import textwrap + __all__ = ["Series"] _shared_doc_kwargs = { @@ -5173,7 +5175,37 @@ def rename_axis( ) -> Self | None: ... - @doc(NDFrame.rename_axis) + @doc( + NDFrame.rename_axis, + extra_parameters=textwrap.dedent( + """\ + mapper : scalar, list-like, optional + Value to set the axis name attribute. + index : scalar, list-like, dict-like or function, optional + A scalar, list-like, dict-like or functions transformations to + apply to that axis' values. + axis : {{0 or 'index', 1 or 'columns'}}, default 0 + The axis to rename. For `Series` this parameter is unused and defaults to 0. + copy : bool, default None + Also copy underlying data. + + .. note:: + The `copy` keyword will change behavior in pandas 3.0. + `Copy-on-Write + `__ + will be enabled by default, which means that all methods with a + `copy` keyword will use a lazy copy mechanism to defer the copy and + ignore the `copy` keyword. The `copy` keyword will be removed in a + future version of pandas. + + You can already get the future behavior and improvements through + enabling copy on write ``pd.options.mode.copy_on_write = True`` + inplace : bool, default False + Modifies the object directly, instead of creating a new Series + or DataFrame. + """ + ), + ) def rename_axis( self, mapper: IndexLabel | lib.NoDefault = lib.no_default, From eb09d39be07f1292fec6808a7606a63c98164072 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 3 Feb 2024 22:12:08 -0700 Subject: [PATCH 2/4] Refactor Series.rename_axis and NDFrame.rename_axis to have separate docstrings --- pandas/core/generic.py | 77 ++++++++++++++---------------------------- pandas/core/series.py | 66 +++++++++++++++++++++++++----------- 2 files changed, 73 insertions(+), 70 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 6d3379b0f2430..f53dddb25861f 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -220,8 +220,6 @@ from pandas.core.indexers.objects import BaseIndexer from pandas.core.resample import Resampler -import textwrap - # goal is to be able to define the docs close to function, while still being # able to share _shared_docs = {**_shared_docs} @@ -1155,25 +1153,35 @@ def rename_axis( ) -> Self | None: ... - @doc( - extra_parameters=textwrap.dedent( - """\ + def rename_axis( + self, + mapper: IndexLabel | lib.NoDefault = lib.no_default, + *, + index=lib.no_default, + columns=lib.no_default, + axis: Axis = 0, + copy: bool_t | None = None, + inplace: bool_t = False, + ) -> Self | None: + """ + Set the name of the axis for the index or columns. + + Parameters + ---------- mapper : scalar, list-like, optional Value to set the axis name attribute. + + Use either ``mapper`` and ``axis`` to + specify the axis to target with ``mapper``, or ``index`` + and/or ``columns``. index : scalar, list-like, dict-like or function, optional A scalar, list-like, dict-like or functions transformations to apply to that axis' values. columns : scalar, list-like, dict-like or function, optional A scalar, list-like, dict-like or functions transformations to apply to that axis' values. - Note that the ``columns`` parameter is not allowed if the - object is a Series. This parameter only apply for DataFrame - type objects. - Use either ``mapper`` and ``axis`` to - specify the axis to target with ``mapper``, or ``index`` - and/or ``columns``. - axis : {{0 or 'index', 1 or 'columns'}}, default 0 - The axis to rename. For `Series` this parameter is unused and defaults to 0. + axis : {0 or 'index', 1 or 'columns'}, default 0 + The axis to rename. copy : bool, default None Also copy underlying data. @@ -1191,28 +1199,10 @@ def rename_axis( inplace : bool, default False Modifies the object directly, instead of creating a new Series or DataFrame. - """ - ), - ) - def rename_axis( - self, - mapper: IndexLabel | lib.NoDefault = lib.no_default, - *, - index=lib.no_default, - columns=lib.no_default, - axis: Axis = 0, - copy: bool_t | None = None, - inplace: bool_t = False, - ) -> Self | None: - """ - Set the name of the axis for the index or columns. - Parameters - ---------- - {extra_parameters} Returns ------- - Series, DataFrame, or None + DataFrame, or None The same type as the caller or None if ``inplace=True``. See Also @@ -1226,7 +1216,7 @@ def rename_axis( ``DataFrame.rename_axis`` supports two calling conventions * ``(index=index_mapper, columns=columns_mapper, ...)`` - * ``(mapper, axis={{'index', 'columns'}}, ...)`` + * ``(mapper, axis={'index', 'columns'}, ...)`` The first calling convention will only modify the names of the index and/or the names of the Index object that is the columns. @@ -1242,25 +1232,10 @@ def rename_axis( Examples -------- - **Series** - - >>> s = pd.Series(["dog", "cat", "monkey"]) - >>> s - 0 dog - 1 cat - 2 monkey - dtype: object - >>> s.rename_axis("animal") - animal - 0 dog - 1 cat - 2 monkey - dtype: object - **DataFrame** - >>> df = pd.DataFrame({{"num_legs": [4, 4, 2], - ... "num_arms": [0, 0, 2]}}, + >>> df = pd.DataFrame({"num_legs": [4, 4, 2], + ... "num_arms": [0, 0, 2]}, ... ["dog", "cat", "monkey"]) >>> df num_legs num_arms @@ -1294,7 +1269,7 @@ def rename_axis( cat 4 0 monkey 2 2 - >>> df.rename_axis(index={{'type': 'class'}}) + >>> df.rename_axis(index={'type': 'class'}) limbs num_legs num_arms class name mammal dog 4 0 diff --git a/pandas/core/series.py b/pandas/core/series.py index f073c2ec33062..25d25b84c1d82 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -207,8 +207,6 @@ from pandas.core.frame import DataFrame from pandas.core.groupby.generic import SeriesGroupBy -import textwrap - __all__ = ["Series"] _shared_doc_kwargs = { @@ -5175,16 +5173,30 @@ def rename_axis( ) -> Self | None: ... - @doc( - NDFrame.rename_axis, - extra_parameters=textwrap.dedent( - """\ + def rename_axis( + self, + mapper: IndexLabel | lib.NoDefault = lib.no_default, + *, + index=lib.no_default, + axis: Axis = 0, + copy: bool = True, + inplace: bool = False, + ) -> Self | None: + """ + Set the name of the axis for the index or columns. + + Parameters + ---------- mapper : scalar, list-like, optional Value to set the axis name attribute. + + Use either ``mapper`` and ``axis`` to + specify the axis to target with ``mapper``, or ``index`` + and/or ``columns``. index : scalar, list-like, dict-like or function, optional A scalar, list-like, dict-like or functions transformations to apply to that axis' values. - axis : {{0 or 'index', 1 or 'columns'}}, default 0 + axis : {0 or 'index'}, default 0 The axis to rename. For `Series` this parameter is unused and defaults to 0. copy : bool, default None Also copy underlying data. @@ -5203,18 +5215,34 @@ def rename_axis( inplace : bool, default False Modifies the object directly, instead of creating a new Series or DataFrame. - """ - ), - ) - def rename_axis( - self, - mapper: IndexLabel | lib.NoDefault = lib.no_default, - *, - index=lib.no_default, - axis: Axis = 0, - copy: bool = True, - inplace: bool = False, - ) -> Self | None: + + Returns + ------- + Series, or None + The same type as the caller or None if ``inplace=True``. + + See Also + -------- + Series.rename : Alter Series index labels or name. + DataFrame.rename : Alter DataFrame index labels or name. + Index.rename : Set new names on index. + + Examples + -------- + + >>> s = pd.Series(["dog", "cat", "monkey"]) + >>> s + 0 dog + 1 cat + 2 monkey + dtype: object + >>> s.rename_axis("animal") + animal + 0 dog + 1 cat + 2 monkey + dtype: object + """ return super().rename_axis( mapper=mapper, index=index, From 7d1769e5ea79393d1a81c5b0d05ef199dc981d3e Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 3 Feb 2024 22:19:13 -0700 Subject: [PATCH 3/4] removed unnecessary columns ref in docstring for Series --- pandas/core/series.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 25d25b84c1d82..32fedba70b660 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -5183,7 +5183,7 @@ def rename_axis( inplace: bool = False, ) -> Self | None: """ - Set the name of the axis for the index or columns. + Set the name of the axis for the index. Parameters ---------- From 0008b0e99a439c6ad2b439541062220d6e486cf0 Mon Sep 17 00:00:00 2001 From: Jordan Murphy <35613487+jordan-d-murphy@users.noreply.github.com> Date: Sat, 3 Feb 2024 22:22:12 -0700 Subject: [PATCH 4/4] removed another unnecessary columns ref in docstring for Series --- pandas/core/series.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/series.py b/pandas/core/series.py index 32fedba70b660..ba198a27b98f3 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -5191,8 +5191,8 @@ def rename_axis( Value to set the axis name attribute. Use either ``mapper`` and ``axis`` to - specify the axis to target with ``mapper``, or ``index`` - and/or ``columns``. + specify the axis to target with ``mapper``, or ``index``. + index : scalar, list-like, dict-like or function, optional A scalar, list-like, dict-like or functions transformations to apply to that axis' values.