Convert DataFrame.rename to keyword only; simplify axis validation

doc/source/whatsnew/v1.0.0.rst

@@ -174,6 +174,68 @@ Backwards incompatible API changes
 
    pd.arrays.IntervalArray.from_tuples([(0, 1), (2, 3)])
 
+``DataFrame.rename`` now only accepts one positional argument
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- :meth:`DataFrame.rename` would previously accept positional arguments that would lead
+  to ambiguous or undefined behavior. From pandas 1.0, only the very first argument, which
+  maps labels to their new names along the default axis, is allowed to be passed by position
+  (:issue:`29136`).
+
+*pandas 0.25.x*
+
+.. code-block:: ipython
+
+   In [1]: df = pd.DataFrame([[1]])
+   In [2]: df.rename({0: 1}, {0: 2})
+   FutureWarning: ...Use named arguments to resolve ambiguity...
+   Out[2]:
+      2
+   1  1
+
+*pandas 1.0.0*
+.. ipython:: python
+
+   df.rename({0: 1}, {0: 2})
+
+Note that errors will now be raised when conflicting or potentially ambiguous arguments are provided.
+
+*pandas 0.25.x*
+
+.. code-block:: ipython
+
+   In [1]: df.rename({0: 1}, index={0: 2})
+   Out[1]:
+      0
+   1  1
+
+   In [2]: df.rename(mapper={0: 1}, index={0: 2})
+   Out[2]:
+      0
+   2  1
+
+*pandas 1.0.0*
+
+.. ipython:: python
+
+   df.rename({0: 1}, index={0: 2})
+   df.rename(mapper={0: 1}, index={0: 2})
+
+You can still change the axis along which the first positional argument is applied by
+supplying the ``axis`` keyword argument.
+
+.. ipython:: python
+
+   df.rename({0: 1})
+   df.rename({0: 1}, axis=1)
+
+If you would like to update both the index and column labels, be sure to use the respective
+keywords.
+
+.. ipython:: python
+
+   df.rename(index={0: 1}, columns={0: 2})
+
 
 .. _whatsnew_1000.api.other:
 

pandas/_typing.py

@@ -24,6 +24,7 @@
 FrameOrSeries = TypeVar("FrameOrSeries", bound="NDFrame")
 Scalar = Union[str, int, float, bool]
 Axis = Union[str, int]
+Level = Union[str, int]
 Ordered = Optional[bool]
 
 # use Collection after we drop support for py35

pandas/core/frame.py

@@ -15,10 +15,12 @@
 import sys
 from textwrap import dedent
 from typing import (
+    Callable,
     FrozenSet,
     Hashable,
     Iterable,
     List,
+    Mapping,
     Optional,
     Sequence,
     Set,
@@ -93,7 +95,7 @@
 )
 from pandas.core.dtypes.missing import isna, notna
 
-from pandas._typing import Axes, Dtype, FilePathOrBuffer
+from pandas._typing import Axis, Axes, Dtype, FilePathOrBuffer, Level
 from pandas.core import algorithms, common as com, nanops, ops
 from pandas.core.accessor import CachedAccessor
 from pandas.core.arrays import Categorical, ExtensionArray
@@ -4031,7 +4033,25 @@ def drop(
         "mapper",
         [("copy", True), ("inplace", False), ("level", None), ("errors", "ignore")],
     )
-    def rename(self, *args, **kwargs):
+    def rename(
+        self,
+        mapper: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+            *,
+        index: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+        columns: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+        axis: Optional[Axis] = None,
+        copy: bool = True,
+        inplace: bool = False,
+        level: Optional[Level] = None,
+        errors: str = "ignore",
+    ) -> "DataFrame":
+
         """
         Alter axes labels.
 
@@ -4140,12 +4160,8 @@ def rename(self, *args, **kwargs):
         2  2  5
         4  3  6
         """
-        axes = validate_axis_style_args(self, args, kwargs, "mapper", "rename")
-        kwargs.update(axes)
-        # Pop these, since the values are in `kwargs` under different names
-        kwargs.pop("axis", None)
-        kwargs.pop("mapper", None)
-        return super().rename(**kwargs)
+        return super().rename(mapper=mapper, index=index, columns=columns, axis=axis, copy=copy,
+                              inplace=inplace, level=level, errors=errors)
 
     @Substitution(**_shared_doc_kwargs)
     @Appender(NDFrame.fillna.__doc__)

pandas/core/generic.py

@@ -14,6 +14,7 @@
     FrozenSet,
     Hashable,
     List,
+    Mapping,
     Optional,
     Sequence,
     Set,
@@ -65,7 +66,7 @@
 from pandas.core.dtypes.missing import isna, notna
 
 import pandas as pd
-from pandas._typing import Dtype, FilePathOrBuffer, Scalar
+from pandas._typing import Axis, Dtype, FilePathOrBuffer, Level, Scalar
 from pandas.core import missing, nanops
 import pandas.core.algorithms as algos
 from pandas.core.base import PandasObject, SelectionMixin
@@ -1013,7 +1014,24 @@ def swaplevel(self, i=-2, j=-1, axis=0):
     # ----------------------------------------------------------------------
     # Rename
 
-    def rename(self, *args, **kwargs):
+    def rename(
+        self,
+        mapper: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+            *,
+        index: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+        columns: Optional[
+            Union[Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+        axis: Optional[Axis] = None,
+        copy: bool = True,
+        inplace: bool = False,
+        level: Optional[Level] = None,
+        errors: str = "ignore",
+    ):
         """
         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
@@ -1126,44 +1144,40 @@ def rename(self, *args, **kwargs):
 
         See the :ref:`user guide <basics.rename>` for more.
         """
-        axes, kwargs = self._construct_axes_from_arguments(args, kwargs)
-        copy = kwargs.pop("copy", True)
-        inplace = kwargs.pop("inplace", False)
-        level = kwargs.pop("level", None)
-        axis = kwargs.pop("axis", None)
-        errors = kwargs.pop("errors", "ignore")
-        if axis is not None:
-            # Validate the axis
-            self._get_axis_number(axis)
-
-        if kwargs:
-            raise TypeError(
-                "rename() got an unexpected keyword "
-                'argument "{0}"'.format(list(kwargs.keys())[0])
-            )
-
-        if com.count_not_none(*axes.values()) == 0:
+        if mapper is None and index is None and columns is None:
             raise TypeError("must pass an index to rename")
 
-        self._consolidate_inplace()
+        if (index is not None or columns is not None):
+            if axis is not None:
+                raise TypeError("Cannot specify both 'axis' and any of 'index' or 'columns'")
+            elif mapper is not None:
+                raise TypeError("Cannot specify both 'mapper' and any of 'index' or 'columns'")
+        else:
+            # use the mapper argument
+            if axis in {1, "columns"}:
+                columns = mapper
+            else:
+                index = mapper
+
         result = self if inplace else self.copy(deep=copy)
 
-        # start in the axis order to eliminate too many copies
-        for axis in range(self._AXIS_LEN):
-            v = axes.get(self._AXIS_NAMES[axis])
-            if v is None:
+        for axis_no, replacements in enumerate((index, columns)):
+            if replacements is None:
                 continue
-            f = com.get_rename_function(v)
-            baxis = self._get_block_manager_axis(axis)
+
+            axis = self._get_axis(axis_no)
+            baxis = self._get_block_manager_axis(axis_no)            
+            f = com.get_rename_function(replacements)
+
             if level is not None:
-                level = self.axes[axis]._get_level_number(level)
+                level = axis._get_level_number(level)
 
             # GH 13473
-            if not callable(v):
-                indexer = self.axes[axis].get_indexer_for(v)
+            if not callable(replacements):
+                indexer = axis.get_indexer_for(replacements)
                 if errors == "raise" and len(indexer[indexer == -1]):
                     missing_labels = [
-                        label for index, label in enumerate(v) if indexer[index] == -1
+                        label for index, label in enumerate(replacements) if indexer[index] == -1
                     ]
                     raise KeyError("{} not found in axis".format(missing_labels))
 

pandas/core/series.py

@@ -5,7 +5,7 @@
 from io import StringIO
 from shutil import get_terminal_size
 from textwrap import dedent
-from typing import Any, Callable
+from typing import Any, Callable, Hashable, Mapping, Optional, Union
 import warnings
 
 import numpy as np
@@ -78,6 +78,7 @@
 from pandas.core.strings import StringMethods
 from pandas.core.tools.datetimes import to_datetime
 
+from pandas._typing import Axis, Level
 import pandas.io.formats.format as fmt
 import pandas.plotting
 
@@ -4079,7 +4080,18 @@ def align(
             broadcast_axis=broadcast_axis,
         )
 
-    def rename(self, index=None, **kwargs):
+    def rename(
+        self,
+        index: Optional[
+            Union[Hashable, Mapping[Hashable, Hashable], Callable[[Hashable], Hashable]]
+        ] = None,
+            *,
+            axis: Optional[Axis] = None,
+        copy: bool = True,
+        inplace: bool = False,
+        level: Optional[Level] = None,
+            errors: str = "ignore"
+    ) -> "Series":
         """
         Alter Series index labels or name.
 
@@ -4093,6 +4105,8 @@ def rename(self, index=None, **kwargs):
 
         Parameters
         ----------
+        axis : int or str
+            Unused. Accepted for compatability with DataFrame method only.
         index : scalar, hashable sequence, dict-like or function, optional
             Functions or dict-like are transformations to apply to
             the index.
@@ -4114,6 +4128,7 @@ def rename(self, index=None, **kwargs):
 
         See Also
         --------
+        DataFrame.rename : Corresponding DataFrame method.
         Series.rename_axis : Set the name of the axis.
 
         Examples
@@ -4140,12 +4155,10 @@ def rename(self, index=None, **kwargs):
         5    3
         dtype: int64
         """
-        kwargs["inplace"] = validate_bool_kwarg(kwargs.get("inplace", False), "inplace")
-
         if callable(index) or is_dict_like(index):
-            return super().rename(index=index, **kwargs)
+            return super().rename(index, copy=copy, inplace=inplace, level=level, errors=errors)
         else:
-            return self._set_name(index, inplace=kwargs.get("inplace"))
+            return self._set_name(index, inplace=inplace)
 
     @Substitution(**_shared_doc_kwargs)
     @Appender(generic.NDFrame.reindex.__doc__)