Skip to content

Commit

Permalink
Refactor Series.rename_axis and NDFrame.rename_axis to have separate …
Browse files Browse the repository at this point in the history 
…docstrings
  • Loading branch information
@jordan-d-murphy
jordan-d-murphy committed Feb 4, 2024
1 parent d4a0ddb commit eb09d39
Show file tree
Hide file tree
Showing 2 changed files with 73 additions and 70 deletions.
77 changes: 26 additions & 51 deletions pandas/core/generic.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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.
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
66 changes: 47 additions & 19 deletions pandas/core/series.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -207,8 +207,6 @@
from pandas.core.frame import DataFrame
from pandas.core.groupby.generic import SeriesGroupBy

import textwrap

__all__ = ["Series"]

_shared_doc_kwargs = {
Expand Down Expand Up @@ -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.
Expand All @@ -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,
Expand Down

0 comments on commit eb09d39

Please sign in to comment.