Rework, docstring

Author: TomAugspurger

doc/source/whatsnew/v0.21.0.txt

@@ -119,8 +119,10 @@ alternative to specify the ``axis`` to target (:issue:`12392`).
 
     df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
     df.rename(str.lower, axis='columns')
+    df.rename(id, axis='index')
 
-The ``.rename(columns=str.lower)`` style continues to work as before.
+The ``.rename(index=id, columns=str.lower)`` style continues to work as before.
+We *highly* encourage using named arguments to avoid confusion.
 
 .. _whatsnew_0210.enhancements.categorical_dtype:
 

pandas/core/frame.py

@@ -112,7 +112,10 @@
     optional_by="""
         by : str or list of str
             Name or list of names which refer to the axis items.""",
-    versionadded_to_excel='')
+    versionadded_to_excel='',
+    mapper = """mapper : dict-like or function
+            Applied to the axis specified by `axis`""",
+)
 
 _numeric_only_doc = """numeric_only : boolean, default None
     Include only float, int, boolean data. If None, will attempt to use
@@ -2929,6 +2932,8 @@ def rename(self, mapper=None, index=None, columns=None, axis=None,
                 warnings.warn("Interpreting renaming index and columns. "
                               "Use keyword arguments.", UserWarning)
                 index, columns = mapper, index
+        elif index is None and columns is None:
+            index = mapper
 
         return super(DataFrame, self).rename(index=index, columns=columns,
                                              **kwargs)

pandas/core/generic.py

@@ -742,6 +742,7 @@ def swaplevel(self, i=-2, j=-1, axis=0):
 
         Parameters
         ----------
+        %(mapper)s
         %(axes)s : scalar, list-like, dict-like or function, optional
             Scalar or list-like will alter the ``Series.name`` attribute,
             and raise on DataFrame or Panel.
@@ -787,6 +788,7 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         3    2
         5    3
         dtype: int64
+
         >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
         >>> df.rename(2)
         Traceback (most recent call last):
@@ -802,10 +804,25 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         0  1  4
         1  2  5
         2  3  6
+
+        Using axis-style parameters
+
+        >>> df.rename(str.lower, axis='columns')
+           A  B
+        0  1  4
+        1  2  5
+        2  3  6
+
+        >>> df.rename({1: 2, 2: 4}, axis='index')
+           A  B
+        0  1  4
+        2  2  5
+        4  3  6
         """
 
     @Appender(_shared_docs['rename'] % dict(axes='axes keywords for this'
-                                            ' object', klass='NDFrame'))
+                                            ' object', klass='NDFrame',
+                                            mapper=''))
     def rename(self, *args, **kwargs):
         axes, kwargs = self._construct_axes_from_arguments(args, kwargs)
         copy = kwargs.pop('copy', True)

pandas/core/panel.py

@@ -39,7 +39,8 @@
 _shared_doc_kwargs = dict(
     axes='items, major_axis, minor_axis',
     klass="Panel",
-    axes_single_arg="{0, 1, 2, 'items', 'major_axis', 'minor_axis'}")
+    axes_single_arg="{0, 1, 2, 'items', 'major_axis', 'minor_axis'}",
+    mapper='')
 _shared_doc_kwargs['args_transpose'] = ("three positional arguments: each one"
                                         "of\n%s" %
                                         _shared_doc_kwargs['axes_single_arg'])

pandas/core/series.py

@@ -85,7 +85,7 @@
     inplace="""inplace : boolean, default False
         If True, performs operation inplace and returns None.""",
     unique='np.ndarray', duplicated='Series',
-    optional_by='',
+    optional_by='', mapper='',
     versionadded_to_excel='\n    .. versionadded:: 0.20.0\n')
 
 

pandas/tests/frame/test_alter_axes.py

@@ -867,6 +867,13 @@ def test_rename_columns(self):
         result = df.rename({'X': 'x', 'Y': 'y'}, axis='index')
         assert_frame_equal(result, expected)
 
+    def test_rename_mapper_multi(self):
+        df = pd.DataFrame({"A": ['a', 'b'], "B": ['c', 'd'],
+                           'C': [1, 2]}).set_index(["A", "B"])
+        result = df.rename(str.upper)
+        expected = df.rename(index=str.upper)
+        assert_frame_equal(result, expected)
+
     def test_rename_raises(self):
         df = pd.DataFrame({"A": [1, 2], "B": [1, 2]}, index=['0', '1'])