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

doc/source/whatsnew/v1.3.0.rst

@@ -51,6 +51,7 @@ Other enhancements
 - :func:`pandas.read_sql_query` now accepts a ``dtype`` argument to cast the columnar data from the SQL database based on user input (:issue:`10285`)
 - Improved integer type mapping from pandas to SQLAlchemy when using :meth:`DataFrame.to_sql` (:issue:`35076`)
 - :func:`to_numeric` now supports downcasting of nullable ``ExtensionDtype`` objects (:issue:`33013`)
+- Add support for dict-like names in :class:`MultiIndex.set_names` and :class:`MultiIndex.rename` (:issue:`20421`)
 - :func:`pandas.read_excel` can now auto detect .xlsb files (:issue:`35416`)
 
 .. ---------------------------------------------------------------------------

pandas/core/indexes/base.py

@@ -80,6 +80,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
@@ -1378,11 +1379,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.3.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.3.0
+
         inplace : bool, default False
             Modifies the object directly, instead of creating a new Index or
             MultiIndex.
@@ -1425,16 +1433,40 @@ def set_names(self, names, level=None, inplace: bool = False):
                     ( 'cobra', 2018),
                     ( 'cobra', 2019)],
                    names=['species', 'year'])
+
+        When renaming levels with a dict, levels can not 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")
 
-        if level is not None and not is_list_like(level) and is_list_like(names):
+        elif level is not None and not is_list_like(level) and is_list_like(names):
             raise TypeError("Names must be a string when a single level is provided.")
 
-        if not is_list_like(names) and level is None and self.nlevels > 1:
+        elif not is_list_like(names) and level is None and self.nlevels > 1:
             raise TypeError("Must pass list-like as `names`.")
 
+        elif is_dict_like(names) and not isinstance(self, ABCMultiIndex):
+            raise TypeError("Can only pass dict-like as `names` for MultiIndex.")
+
+        elif is_dict_like(names) and level is not None:
+            raise TypeError("Can not pass level for dictlike `names`.")
+
+        if isinstance(self, ABCMultiIndex) and is_dict_like(names) and level is None:
+            # 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
+
         if not is_list_like(names):
             names = [names]
         if level is not None and not is_list_like(level):
@@ -1444,6 +1476,7 @@ def set_names(self, names, level=None, inplace: bool = False):
             idx = self
         else:
             idx = self._shallow_copy()
+
         idx._set_names(names, level=level)
         if not inplace:
             return idx

pandas/tests/indexes/multi/test_names.py

@@ -150,3 +150,56 @@ 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_duplicate_names(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)
+
+
+@pytest.mark.parametrize("func", ["rename", "set_names"])
+@pytest.mark.parametrize(
+    "rename_dict, exp_names",
+    [
+        ({"x": "z"}, ["z", "y"]),
+        ({"x": "z", "y": "x"}, ["z", "x"]),
+        ({"a": "z"}, ["x", "y"]),
+        ({}, ["x", "y"]),
+    ],
+)
+def test_name_mi_with_dict_like(func, rename_dict, exp_names):
+    # GH#20421
+    mi = MultiIndex.from_arrays([[1, 2], [3, 4]], names=["x", "y"])
+    result = getattr(mi, func)(rename_dict)
+    expected = MultiIndex.from_arrays([[1, 2], [3, 4]], names=exp_names)
+    tm.assert_index_equal(result, expected)
+
+
+def test_index_name_with_dict_like_raising():
+    # GH#20421
+    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"})
+
+
+def test_multiindex_name_and_level_raising():
+    # GH#20421
+    mi = MultiIndex.from_arrays([[1, 2], [3, 4]], names=["x", "y"])
+    with pytest.raises(TypeError, match="Can not pass level for dictlike `names`."):
+        mi.set_names(names={"x": "z"}, level={"x": "z"})