ENH: Implement dict-like support for rename and set_names in MultiIndex

doc/source/whatsnew/v1.2.0.rst

@@ -257,6 +257,7 @@ Other enhancements
 - Improve numerical stability for :meth:`.Rolling.skew`, :meth:`.Rolling.kurt`, :meth:`Expanding.skew` and :meth:`Expanding.kurt` through implementation of Kahan summation (:issue:`6929`)
 - Improved error reporting for subsetting columns of a :class:`.DataFrameGroupBy` with ``axis=1`` (:issue:`37725`)
 - Implement method ``cross`` for :meth:`DataFrame.merge` and :meth:`DataFrame.join` (:issue:`5401`)
+- Add support for dict-like names in :class:`MultiIndex.set_names` and :class:`MultiIndex.rename` (:issue:`20421`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/indexes/base.py

@@ -73,6 +73,7 @@
     ABCSeries,
     ABCTimedeltaIndex,
 )
+from pandas.core.dtypes.inference import is_dict_like
 from pandas.core.dtypes.missing import array_equivalent, isna
 
 from pandas.core import missing, ops
@@ -1319,11 +1320,18 @@ def set_names(self, names, level=None, inplace: bool = False):
 
         Parameters
         ----------
-        names : label or list of label
+
+        names : label or list of label or dict-like for MultiIndex
             Name(s) to set.
+
+            .. versionchanged:: 1.2.0
+
         level : int, label or list of int or label, optional
-            If the index is a MultiIndex, level(s) to set (None for all
-            levels). Otherwise level must be None.
+            If the index is a MultiIndex and names is not dict-like, level(s) to set
+            (None for all levels). Otherwise level must be None.
+
+            .. versionchanged:: 1.2.0
+
         inplace : bool, default False
             Modifies the object directly, instead of creating a new Index or
             MultiIndex.
@@ -1366,6 +1374,15 @@ def set_names(self, names, level=None, inplace: bool = False):
                     ( 'cobra', 2018),
                     ( 'cobra', 2019)],
                    names=['species', 'year'])
+
+        When renaming levels through a dictionary no level can't be passed.
+
+        >>> idx.set_names({'kind': 'snake'})
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   names=['snake', 'year'])
         """
         if level is not None and not isinstance(self, ABCMultiIndex):
             raise ValueError("Level must be None for non-MultiIndex")
@@ -1376,6 +1393,12 @@ def set_names(self, names, level=None, inplace: bool = False):
         if not is_list_like(names) and level is None and self.nlevels > 1:
             raise TypeError("Must pass list-like as `names`.")
 
+        if is_dict_like(names) and not isinstance(self, ABCMultiIndex):
+            raise TypeError("Can only pass dict-like as `names` for MultiIndex.")
+
+        if is_dict_like(names) and level is not None:
+            raise TypeError("Can not pass level when passing dict-like as `names`.")
+
         if not is_list_like(names):
             names = [names]
         if level is not None and not is_list_like(level):
@@ -1385,6 +1408,16 @@ def set_names(self, names, level=None, inplace: bool = False):
             idx = self
         else:
             idx = self._shallow_copy()
+
+        if isinstance(self, ABCMultiIndex) and is_dict_like(names):
+            # Transform dict to list of new names and corresponding levels
+            level, names_adjusted = [], []
+            for i, name in enumerate(self.names):
+                if name in names.keys():
+                    level.append(i)
+                    names_adjusted.append(names[name])
+            names = names_adjusted
+
         idx._set_names(names, level=level)
         if not inplace:
             return idx

pandas/tests/indexes/multi/test_names.py

@@ -148,3 +148,37 @@ def test_setting_names_from_levels_raises():
     assert pd.Index._no_setting_name is False
     assert pd.Int64Index._no_setting_name is False
     assert pd.RangeIndex._no_setting_name is False
+
+
+@pytest.mark.parametrize("func", ["rename", "set_names"])
+@pytest.mark.parametrize(
+    "rename_dict, exp_names",
+    [
+        ({"x": "z"}, ["z", "y", "z"]),
+        ({"x": "z", "y": "x"}, ["z", "x", "z"]),
+        ({"y": "z"}, ["x", "z", "x"]),
+        ({}, ["x", "y", "x"]),
+        ({"z": "a"}, ["x", "y", "x"]),
+        ({"y": "z", "a": "b"}, ["x", "z", "x"]),
+    ],
+)
+def test_name_mi_with_dict_like(func, rename_dict, exp_names):
+    # GH#20421
+    mi = MultiIndex.from_arrays([[1, 2], [3, 4], [5, 6]], names=["x", "y", "x"])
+    result = getattr(mi, func)(rename_dict)
+    expected = MultiIndex.from_arrays([[1, 2], [3, 4], [5, 6]], names=exp_names)
+    tm.assert_index_equal(result, expected)
+
+
+def test_name_with_dict_like_raising():
+    # GH#20421
+    mi = MultiIndex.from_arrays([[1, 2], [3, 4]], names=["x", "y"])
+
+    msg = "Can not pass level when passing dict-like as `names`."
+    with pytest.raises(TypeError, match=msg):
+        mi.set_names({"x": "z"}, level=[0, 1])
+
+    ix = pd.Index([1, 2])
+    msg = "Can only pass dict-like as `names` for MultiIndex."
+    with pytest.raises(TypeError, match=msg):
+        ix.set_names({"x": "z"})