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

Author: TomAugspurger

doc/source/basics.rst

@@ -1217,6 +1217,15 @@ following can be done:
 This means that the reindexed Series's index is the same Python object as the
 DataFrame's index.
 
+.. versionadded:: 0.21.0
+
+:meth:`DataFrame.reindex` also supports an "axis-style" calling convention,
+where you specify a single ``labels`` argument and the ``axis`` it applies to.
+
+.. ipython:: python
+
+   df.reindex(['c', 'f', 'b'], axis='index')
+   df.reindex(['three', 'two', 'one'], axis='columns')
 
 .. seealso::
 
@@ -1413,12 +1422,23 @@ Series can also be used:
 
 .. ipython:: python
 
-   df.rename(columns={'one' : 'foo', 'two' : 'bar'},
-             index={'a' : 'apple', 'b' : 'banana', 'd' : 'durian'})
+   df.rename(columns={'one': 'foo', 'two': 'bar'},
+             index={'a': 'apple', 'b': 'banana', 'd': 'durian'})
 
 If the mapping doesn't include a column/index label, it isn't renamed. Also
 extra labels in the mapping don't throw an error.
 
+.. versionadded:: 0.21.0
+
+:meth:`DataFrame.rename` also supports an "axis-style" calling convention, where
+you specify a single ``mapper`` and the ``axis`` to apply that mapping to.
+
+.. ipython:: python
+
+   df.rename({'one': 'foo', 'two': 'bar'}, axis='columns'})
+   df.rename({'a': 'apple', 'b': 'banana', 'd': 'durian'}, axis='columns'})
+
+
 The :meth:`~DataFrame.rename` method also provides an ``inplace`` named
 parameter that is by default ``False`` and copies the underlying data. Pass
 ``inplace=True`` to rename the data in place.

doc/source/whatsnew/v0.21.0.txt

@@ -121,22 +121,22 @@ library (:issue:`12392`).
 
 Here's ``rename``:
 
-.. ipython:: 
+.. ipython:: python
 
    df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
    df.rename(str.lower, axis='columns')
    df.rename(id, axis='index')
 
 And ``reindex``:
 
-.. ipython::
+.. ipython:: python
 
    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.
 
-.. ipython::
+.. ipython:: python
 
    df.rename(index=id, columns=str.lower)
 

pandas/core/generic.py

@@ -768,6 +768,7 @@ def swaplevel(self, i=-2, j=-1, axis=0):
 
         Examples
         --------
+
         >>> s = pd.Series([1, 2, 3])
         >>> s
         0    1
@@ -790,16 +791,29 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         5    3
         dtype: int64
 
+        Since ``DataFrame`` doesn't have a ``.name`` attribute,
+        only mapping-type arguments are allowed.
+
         >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
         >>> df.rename(2)
         Traceback (most recent call last):
         ...
         TypeError: 'int' object is not callable
+
+        ``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.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
@@ -819,6 +833,8 @@ def swaplevel(self, i=-2, j=-1, axis=0):
         0  1  4
         2  2  5
         4  3  6
+
+        See the :ref:`user guide <basics.rename>` for more.
         """
 
     @Appender(_shared_docs['rename'] % dict(axes='axes keywords for this'
@@ -904,6 +920,7 @@ def rename_axis(self, mapper, axis=0, copy=True, inplace=False):
 
         Examples
         --------
+
         >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
         >>> df.rename_axis("foo")  # scalar, alters df.index.name
              A  B
@@ -2794,10 +2811,13 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
         Examples
         --------
 
-        Note that ``.reindex`` can be called by specifying either
+        ``DataFrame.reindex`` supports two calling conventions
 
-        * One or both of ``index`` and ``columns``
-        * ``labels`` and ``axis``
+        * ``(index=index_labels, columns=column_labels, ...)
+        * ``(labels, axis={'index', 'columns'}, ...)
+
+        We *highly* recommend using keyword arguments to clarify your
+        intent.
 
         Create a dataframe with some fictional data.
 
@@ -2931,6 +2951,8 @@ def sort_index(self, axis=0, level=None, ascending=True, inplace=False,
         desired indexes. If you do want to fill in the ``NaN`` values present
         in the original dataframe, use the ``fillna()`` method.
 
+        See the :ref:`user guide <basics.reindexing>` for more.
+
         Returns
         -------
         reindexed : %(klass)s