fixup! API: Accept 'axis' keyword argument for reindex

Author: TomAugspurger

doc/source/whatsnew/v0.21.0.txt

@@ -115,9 +115,8 @@ For example:
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The :meth:`DataFrame.rename` and :meth:`DataFrame.reindex` methods have gained
-the ``axis`` keyword to specify the axis to target with the operation. This
-harmonizes the method signature of these methods with most of the rest of the
-library (:issue:`12392`).
+the ``axis`` keyword to specify the axis to target with the operation
+(:issue:`12392`).
 
 Here's ``rename``:
 
@@ -134,11 +133,12 @@ And ``reindex``:
    df.reindex(['A', 'B', 'C'], axis='columns')
    df.reindex([0, 1, 3], axis='index')
 
-The ``.rename(index=id, columns=str.lower)`` style continues to work as before.
+The "index, columns" style continues to work as before.
 
 .. ipython:: python
 
    df.rename(index=id, columns=str.lower)
+   df.reindex(index=[0, 1, 3], columns=['A', 'B', 'C'])
 
 We *highly* encourage using named arguments to avoid confusion when using either
 style.

pandas/core/frame.py

@@ -113,8 +113,6 @@
         by : str or list of str
             Name or list of names which refer to the axis items.""",
     versionadded_to_excel='',
-    optional_mapper="""mapper : dict-like or function
-            Applied to the axis specified by `axis`""",
     optional_labels="""labels : array-like, optional
             New labels / index to conform the axis specified by 'axis' to.""",
     optional_axis="""axis : int or str, optional
@@ -2776,7 +2774,7 @@ def reindexer(value):
 
     def _validate_axis_style_args(self, arg, arg_name, index, columns,
                                   axis, method_name):
-        if axis != 0:
+        if axis is not None:
             # Using "axis" style, along with a positional arg
             # Both index and columns should be None then
             axis = self._get_axis_name(axis)
@@ -2811,6 +2809,7 @@ def _validate_axis_style_args(self, arg, arg_name, index, columns,
             warnings.warn(msg, stacklevel=3)
             index, columns = arg, index
         elif index is None:
+            # This is for the default axis, like reindex([0, 1])
             index = arg
         return index, columns
 
@@ -2940,7 +2939,7 @@ def align(self, other, join='outer', axis=None, level=None, copy=True,
                                             broadcast_axis=broadcast_axis)
 
     @Appender(_shared_docs['reindex'] % _shared_doc_kwargs)
-    def reindex(self, labels=None, index=None, columns=None, axis=0,
+    def reindex(self, labels=None, index=None, columns=None, axis=None,
                 **kwargs):
         index, columns = self._validate_axis_style_args(labels, 'labels',
                                                         index, columns,
@@ -2956,9 +2955,81 @@ def reindex_axis(self, labels, axis=0, method=None, level=None, copy=True,
                                         method=method, level=level, copy=copy,
                                         limit=limit, fill_value=fill_value)
 
-    @Appender(_shared_docs['rename'] % _shared_doc_kwargs)
-    def rename(self, mapper=None, index=None, columns=None, axis=0,
+    def rename(self, mapper=None, index=None, columns=None, axis=None,
                **kwargs):
+        """Alter axes labels.
+
+        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.
+
+        See the :ref:`user guide <basics.rename>` for more.
+
+        Parameters
+        ----------
+        mapper : dict-like or function, optional
+            Applied to the axis specified by ``axis``
+        index, columns : scalar, list-like, dict-like or function, optional
+            dict-like or functions transformations to apply to
+            that axis' values
+        axis : int or str, optional
+            Axis to target with ``mapper``. Can be either the axis name
+            ('index', 'columns') or number (0, 1). The default is 'index'.
+        copy : boolean, default True
+            Also copy underlying data
+        inplace : boolean, default False
+            Whether to return a new %(klass)s. 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
+
+        See Also
+        --------
+        pandas.NDFrame.rename_axis
+
+        Examples
+        --------
+
+        ``DataFrame.rename`` supports two calling conventions
+
+        * ``(index=index_mapper, columns=columns_mapper, ...)
+        * ``(mapper, axis={'index', 'columns'}, ...)
+
+        We *highly* recommend using keyword arguments to clarify your
+        intent.
+
+        >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+        >>> df.rename(index=str, columns={"A": "a", "B": "c"})
+           a  c
+        0  1  4
+        1  2  5
+        2  3  6
+
+        >>> df.rename(index=str, columns={"A": "a", "C": "c"})
+           a  B
+        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
+        """
         index, columns = self._validate_axis_style_args(mapper, 'mapper',
                                                         index, columns,
                                                         axis, 'rename')

pandas/core/series.py

@@ -2525,8 +2525,66 @@ def align(self, other, join='outer', axis=None, level=None, copy=True,
                                          limit=limit, fill_axis=fill_axis,
                                          broadcast_axis=broadcast_axis)
 
-    @Appender(generic._shared_docs['rename'] % _shared_doc_kwargs)
     def rename(self, index=None, **kwargs):
+        """Alter Series row labels or name
+
+        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.
+
+        See the :ref:`user guide <basics.rename>` for more.
+
+        Parameters
+        ----------
+        index : scalar, list-like, dict-like or function, optional
+            dict-like or functions are transformations to apply to
+            the index.
+            Scalar or list-like will alter the ``Series.name`` attribute.
+        copy : boolean, default True
+            Also copy underlying data
+        inplace : boolean, default False
+            Whether to return a new %(klass)s. 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 : Series (new object)
+
+        See Also
+        --------
+        pandas.DataFrame.rename_axis
+
+        Examples
+        --------
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s
+        0    1
+        1    2
+        2    3
+        dtype: int64
+        >>> s.rename("my_name") # scalar, changes Series.name
+        0    1
+        1    2
+        2    3
+        Name: my_name, dtype: int64
+        >>> s.rename(lambda x: x ** 2)  # function, changes labels
+        0    1
+        1    2
+        4    3
+        dtype: int64
+        >>> s.rename({1: 3, 2: 5})  # mapping, changes labels
+        0    1
+        3    2
+        5    3
+        dtype: int64
+
+        """
         kwargs['inplace'] = validate_bool_kwarg(kwargs.get('inplace', False),
                                                 'inplace')
 

pandas/tests/frame/test_alter_axes.py

@@ -868,9 +868,6 @@ def test_rename_axis_style(self):
         result = df.rename({'X': 'x', 'Y': 'y'}, axis='index')
         assert_frame_equal(result, expected)
 
-        result = df.rename(index=str.lower, axis=0)
-        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"])
@@ -902,6 +899,9 @@ def test_rename_axis_style_raises(self):
         with tm.assert_raises_regex(TypeError, None):
             df.rename(columns=str.lower, axis='columns')
 
+        with tm.assert_raises_regex(TypeError, None):
+            df.rename(index=str.lower, axis=0)
+
         # Multiple targets and axis
         with tm.assert_raises_regex(TypeError, None):
             df.rename(str.lower, str.lower, axis='columns')
@@ -910,37 +910,32 @@ def test_rename_axis_style_raises(self):
         with tm.assert_raises_regex(TypeError, None):
             df.rename(str.lower, str.lower, str.lower)
 
-    def test_drop_api_equivalence(self):
-        # https://github.com/pandas-dev/pandas/issues/12392
+    def test_reindex_api_equivalence(self):
         # equivalence of the labels/axis and index/columns API's
         df = DataFrame([[1, 2, 3], [3, 4, 5], [5, 6, 7]],
                        index=['a', 'b', 'c'],
                        columns=['d', 'e', 'f'])
 
-        res1 = df.drop('a')
-        res2 = df.drop(index='a')
-        tm.assert_frame_equal(res1, res2)
-
-        res1 = df.drop('d', 1)
-        res2 = df.drop(columns='d')
-        tm.assert_frame_equal(res1, res2)
-
-        res1 = df.drop(labels='e', axis=1)
-        res2 = df.drop(columns='e')
-        tm.assert_frame_equal(res1, res2)
-
-        res1 = df.drop(['a'], axis=0)
-        res2 = df.drop(index=['a'])
-        tm.assert_frame_equal(res1, res2)
-
-        res1 = df.drop(['a'], axis=0).drop(['d'], axis=1)
-        res2 = df.drop(index=['a'], columns=['d'])
-
-        with pytest.raises(ValueError):
-            df.drop(labels='a', index='b')
-
-        with pytest.raises(ValueError):
-            df.drop(axis=1)
+        res1 = df.reindex(['b', 'a'])
+        res2 = df.reindex(index=['b', 'a'])
+        res3 = df.reindex(labels=['b', 'a'])
+        res4 = df.reindex(labels=['b', 'a'], axis=0)
+        res5 = df.reindex(['b', 'a'], axis=0)
+        for res in [res2, res3, res4, res5]:
+            tm.assert_frame_equal(res1, res)
+
+        res1 = df.reindex(columns=['e', 'd'])
+        res2 = df.reindex(['e', 'd'], axis=1)
+        res3 = df.reindex(labels=['e', 'd'], axis=1)
+        for res in [res2, res3]:
+            tm.assert_frame_equal(res1, res)
+
+        res1 = df.reindex(index=['b', 'a'], columns=['e', 'd'])
+        res2 = df.reindex(columns=['e', 'd'], index=['b', 'a'])
+        res3 = df.reindex(labels=['b', 'a'], axis=0).reindex(labels=['e', 'd'],
+                                                             axis=1)
+        for res in [res2, res3]:
+            tm.assert_frame_equal(res1, res)
 
     def test_assign_columns(self):
         self.frame['hi'] = 'there'

pandas/tests/frame/test_axis_select_reindex.py

@@ -474,27 +474,34 @@ def test_reindex_positional_warns(self):
     def test_reindex_axis_style_raises(self):
         # https://github.com/pandas-dev/pandas/issues/12392
         df = pd.DataFrame({"A": [1, 2, 3], 'B': [4, 5, 6]})
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex([0, 1], ['A'], axis=1)
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex([0, 1], ['A'], axis='index')
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex(index=[0, 1], axis='index')
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex(index=[0, 1], axis='columns')
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex(columns=[0, 1], axis='columns')
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'reindex'):
             df.reindex(index=[0, 1], columns=[0, 1], axis='columns')
 
-        with tm.assert_raises_regex(TypeError, ''):
+        with tm.assert_raises_regex(TypeError, 'Cannot specify all'):
             df.reindex([0, 1], [0], ['A'])
 
+        # Mixing styles
+        with tm.assert_raises_regex(TypeError, 'reindex'):
+            df.reindex(index=[0, 1], axis='index')
+
+        with tm.assert_raises_regex(TypeError, 'reindex'):
+            df.reindex(index=[0, 1], axis='columns')
+
     def test_reindex_single_named_indexer(self):
         # https://github.com/pandas-dev/pandas/issues/12392
         df = pd.DataFrame({"A": [1, 2, 3], "B": [1, 2, 3]})