DOC: rename_axis 'columns' param

[Toussaic]

Example :

import pandas as pd
import numpy as np

s1 = pd.Series(np.random.randn(3), name="First", index=['a', 'b', 'c'])
s1.rename(columns="My Column")

Except :
TypeError: rename_axis() got an unexpected keyword argument "columns"

Description :
The documentation shows a "columns" param which is not allowed for a Series. There should be a note to explain this parameter only apply for DataFrame.

Link :

pandas/pandas/core/generic.py

Lines 1110 to 1279 in 3adf334

	@rewrite_axis_style_signature("mapper", [("copy", True), ("inplace", False)])
	def rename_axis(self, mapper=lib.no_default, **kwargs):
	"""
	Set the name of the axis for the index or columns.
	Parameters
	----------
	mapper : scalar, list-like, optional
	Value to set the axis name attribute.
	index, columns : scalar, list-like, dict-like or function, optional
	A scalar, list-like, dict-like or functions transformations to
	apply to that axis' values.
	Use either ``mapper`` and ``axis`` to
	specify the axis to target with ``mapper``, or ``index``
	and/or ``columns``.
	.. versionchanged:: 0.24.0
	axis : {0 or 'index', 1 or 'columns'}, default 0
	The axis to rename.
	copy : bool, default True
	Also copy underlying data.
	inplace : bool, default False
	Modifies the object directly, instead of creating a new Series
	or DataFrame.
	Returns
	-------
	Series, DataFrame, or None
	The same type as the caller or None if `inplace` is 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.
	Notes
	-----
	``DataFrame.rename_axis`` supports two calling conventions
	* ``(index=index_mapper, columns=columns_mapper, ...)``
	* ``(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.
	In this case, the parameter ``copy`` is ignored.
	The second calling convention will modify the names of the
	the corresponding index if mapper is a list or a scalar.
	However, if mapper is dict-like or a function, it will use the
	deprecated behavior of modifying the axis *labels*.
	We *highly* recommend using keyword arguments to clarify your
	intent.
	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]},
	... ["dog", "cat", "monkey"])
	>>> df
	num_legs num_arms
	dog 4 0
	cat 4 0
	monkey 2 2
	>>> df = df.rename_axis("animal")
	>>> df
	num_legs num_arms
	animal
	dog 4 0
	cat 4 0
	monkey 2 2
	>>> df = df.rename_axis("limbs", axis="columns")
	>>> df
	limbs num_legs num_arms
	animal
	dog 4 0
	cat 4 0
	monkey 2 2
	**MultiIndex**
	>>> df.index = pd.MultiIndex.from_product([['mammal'],
	... ['dog', 'cat', 'monkey']],
	... names=['type', 'name'])
	>>> df
	limbs num_legs num_arms
	type name
	mammal dog 4 0
	cat 4 0
	monkey 2 2
	>>> df.rename_axis(index={'type': 'class'})
	limbs num_legs num_arms
	class name
	mammal dog 4 0
	cat 4 0
	monkey 2 2
	>>> df.rename_axis(columns=str.upper)
	LIMBS num_legs num_arms
	type name
	mammal dog 4 0
	cat 4 0
	monkey 2 2
	"""
	axes, kwargs = self._construct_axes_from_arguments(
	(), kwargs, sentinel=lib.no_default
	)
	copy = kwargs.pop("copy", True)
	inplace = kwargs.pop("inplace", False)
	axis = kwargs.pop("axis", 0)
	if axis is not None:
	axis = self._get_axis_number(axis)
	if kwargs:
	raise TypeError(
	"rename_axis() got an unexpected keyword "
	f'argument "{list(kwargs.keys())[0]}"'
	)
	inplace = validate_bool_kwarg(inplace, "inplace")
	if mapper is not lib.no_default:
	# Use v0.23 behavior if a scalar or list
	non_mapper = is_scalar(mapper) or (
	is_list_like(mapper) and not is_dict_like(mapper)
	)
	if non_mapper:
	return self._set_axis_name(mapper, axis=axis, inplace=inplace)
	else:
	raise ValueError("Use `.rename` to alter labels with a mapper.")
	else:
	# Use new behavior. Means that index and/or columns
	# is specified
	result = self if inplace else self.copy(deep=copy)
	for axis in range(self._AXIS_LEN):
	v = axes.get(self._AXIS_NAMES[axis])
	if v is lib.no_default:
	continue
	non_mapper = is_scalar(v) or (is_list_like(v) and not is_dict_like(v))
	if non_mapper:
	newnames = v
	else:
	f = com.get_rename_function(v)
	curnames = self._get_axis(axis).names
	newnames = [f(name) for name in curnames]
	result._set_axis_name(newnames, axis=axis, inplace=True)
	if not inplace:
	return result

INSTALLED VERSIONS

commit : None
python : 3.8.2.final.0
python-bits : 64
OS : Windows
OS-release : 10
machine : AMD64
processor : Intel64 Family 6 Model 158 Stepping 10, GenuineIntel
byteorder : little
LC_ALL : None
LANG : None
LOCALE : fr_FR.cp1252

pandas : 1.0.3
numpy : 1.18.1
pytz : 2019.3
dateutil : 2.8.1
pip : 20.0.2
setuptools : 46.1.3.post20200330
Cython : None
pytest : None
hypothesis : None
sphinx : 2.4.4
blosc : None
feather : None
xlsxwriter : None
lxml.etree : None
html5lib : None
pymysql : None
psycopg2 : None
jinja2 : 2.11.1
IPython : 7.13.0
pandas_datareader: None
bs4 : None
bottleneck : None
fastparquet : None
gcsfs : None
lxml.etree : None
matplotlib : 3.1.3
numexpr : None
odfpy : None
openpyxl : None
pandas_gbq : None
pyarrow : None
pytables : None
pytest : None
pyxlsb : None
s3fs : None
scipy : 1.4.1
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlwt : None
xlsxwriter : None
numba : None

[MarcoGorelli]

Thanks @Toussaic for the report - are you insterested in submitting a pull request? https://pandas.pydata.org/pandas-docs/stable/development/contributing.html

[benrhodeland]

take

[Toussaic]

Thanks @Toussaic for the report - are you insterested in submitting a pull request? https://pandas.pydata.org/pandas-docs/stable/development/contributing.html

Sorry, I'm not a real dev.

But after reading other docstring, maybe there should be a wrapper in "series.py" with a different docstring, like for "series.py:rename". Don't know...

[TapanGujjar]

I would like to work on this issue if possible

[MarcoGorelli]

@TapanGujjar it seems @benrhodeland is already working on this, but there are other good first issues you're welcome to submit a pull request for!

[gabsmoreira]

Hello, is @benrhodeland on this issue? Because I would like to work on this as well.

[MarcoGorelli]

Given the silence, you're probably OK to take it - PRs are welcome!

[gabsmoreira]

Ok, thanks @MarcoGorelli . Should I add the explanation inside "Notes" or just after the parameter "index, columns" text?