API: Added axis argument to rename, reindex by TomAugspurger · Pull Request #17800 · pandas-dev/pandas (original) (raw)
DataFrame docstring:
Signature: df.rename(mapper=None, index=None, columns=None, axis=None, **kwargs)
Docstring:
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
``Series.name`` with a scalar value (Series only).
Parameters
----------
mapper : dict-like or function
Applied to the axis specified by `axis`
index, columns : 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
copy : boolean, default True
Also copy underlying data
inplace : boolean, default False
Whether to return a new DataFrame. If True then value of copy is
ignored.
level : int or level name, default None
In case of a MultiIndex, only rename labels in the specified
level.
Returns
-------
renamed : DataFrame (new object)
...
Examples:
In [1]: import pandas as pd
In [2]: df = pd.DataFrame({"A": [1, 2], "B": ['a', 'b'], 'C': [1, 2]})
In [4]: df.rename(id)
Out[4]:
A B C
4370471600 1 a 1
4370471632 2 b 2
In [5]: df.rename(id, axis=1)
Out[5]:
4373200824 4372848512 4372782920
0 1 a 1
1 2 b 2
In [6]: df.rename(id, id)
/Users/taugspurger/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py:2936: UserWarning: Interpreting call to '.rename(a, b)' as '.rename(index=a, columns=b)'. Use keyword arguments to remove ambiguity.
UserWarning)
Out[6]:
4373200824 4372848512 4372782920
4370471600 1 a 1
4370471632 2 b 2
In [7]: df.rename(index=id, columns=id)
Out[7]:
4373200824 4372848512 4372782920
4370471600 1 a 1
4370471632 2 b 2
In [8]: df.rename(index=id, axis=1)
---------------------------------------------------------------------------
TypeError Traceback (most recent call last)
<ipython-input-8-8a1d2adfffdf> in <module>()
----> 1 df.rename(index=id, axis=1)
~/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py in rename(self, mapper, index, columns, axis, **kwargs)
2916 axis = self._get_axis_name(axis)
2917 if index is not None or columns is not None:
-> 2918 raise TypeError("Can't specify both 'axis' and 'index' or "
2919 "'columns' Specify either\n"
2920 "\t.rename(mapper, axis=axis), or\n"
TypeError: Can't specify both 'axis' and 'index' or 'columns' Specify either
.rename(mapper, axis=axis), or
.rename(index=index, columns=columns)
In [9]: df.rename(columns=id, axis=1)
---------------------------------------------------------------------------
TypeError Traceback (most recent call last)
<ipython-input-9-2dd7c9eb0abf> in <module>()
----> 1 df.rename(columns=id, axis=1)
~/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py in rename(self, mapper, index, columns, axis, **kwargs)
2916 axis = self._get_axis_name(axis)
2917 if index is not None or columns is not None:
-> 2918 raise TypeError("Can't specify both 'axis' and 'index' or "
2919 "'columns' Specify either\n"
2920 "\t.rename(mapper, axis=axis), or\n"
TypeError: Can't specify both 'axis' and 'index' or 'columns' Specify either
.rename(mapper, axis=axis), or
.rename(index=index, columns=columns)
In [10]: df.rename(index=id, columns=id, axis=1)
---------------------------------------------------------------------------
TypeError Traceback (most recent call last)
<ipython-input-10-a15c6c06cf1d> in <module>()
----> 1 df.rename(index=id, columns=id, axis=1)
~/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py in rename(self, mapper, index, columns, axis, **kwargs)
2916 axis = self._get_axis_name(axis)
2917 if index is not None or columns is not None:
-> 2918 raise TypeError("Can't specify both 'axis' and 'index' or "
2919 "'columns' Specify either\n"
2920 "\t.rename(mapper, axis=axis), or\n"
TypeError: Can't specify both 'axis' and 'index' or 'columns' Specify either
.rename(mapper, axis=axis), or
.rename(index=index, columns=columns)
In [11]: df.rename(mapper=id, index=id, columns=id)
---------------------------------------------------------------------------
TypeError Traceback (most recent call last)
<ipython-input-11-0175716afaa0> in <module>()
----> 1 df.rename(mapper=id, index=id, columns=id)
~/Envs/pandas-dev/lib/python3.6/site-packages/pandas/pandas/core/frame.py in rename(self, mapper, index, columns, axis, **kwargs)
2925 columns = mapper
2926 elif all(x is not None for x in (mapper, index, columns)):
-> 2927 raise TypeError("Cannot specify all of 'mapper', 'index', and "
2928 "'columns'. Specify 'mapper' and 'axis', or "
2929 "'index' and 'columns'.")
TypeError: Cannot specify all of 'mapper', 'index', and 'columns'. Specify 'mapper' and 'axis', or 'index' and 'columns'.
The most concerning part (to me) is the one emitting a warning. I interpret df.rename(id, id), as df.rename(index=id, columns=id), which was the previous signature. This means we also interpret df.rename(mapper=id, index=id) as df.rename(index=id, columns=id), which feels wrong, but I think is unavoidable.