DEPR: Deprecate params levels & codes in MultiIndex.copy (#36685)

doc/source/whatsnew/v1.2.0.rst

@@ -258,6 +258,7 @@ Deprecations
 ~~~~~~~~~~~~
 - Deprecated parameter ``inplace`` in :meth:`MultiIndex.set_codes` and :meth:`MultiIndex.set_levels` (:issue:`35626`)
 - Deprecated parameter ``dtype`` in :meth:`~Index.copy` on method all index classes. Use the :meth:`~Index.astype` method instead for changing dtype (:issue:`35853`)
+- Deprecated parameters ``levels`` and ``codes`` in :meth:`~MultiIndex.copy`. Use the :meth:`~MultiIndex.set_levels` and :meth:`~MultiIndex.set_codes` methods instead (:issue:`36685`)
 - Date parser functions :func:`~pandas.io.date_converters.parse_date_time`, :func:`~pandas.io.date_converters.parse_date_fields`, :func:`~pandas.io.date_converters.parse_all_fields` and :func:`~pandas.io.date_converters.generic_parser` from ``pandas.io.date_converters`` are deprecated and will be removed in a future version; use :func:`to_datetime` instead (:issue:`35741`)
 - :meth:`DataFrame.lookup` is deprecated and will be removed in a future version, use :meth:`DataFrame.melt` and :meth:`DataFrame.loc` instead (:issue:`18682`)
 - The :meth:`Index.to_native_types` is deprecated. Use ``.astype(str)`` instead (:issue:`28867`)

pandas/core/indexes/multi.py

@@ -1132,7 +1132,11 @@ def copy(
 
             .. deprecated:: 1.2.0
         levels : sequence, optional
+
+            .. deprecated:: 1.2.0
         codes : sequence, optional
+
+            .. deprecated:: 1.2.0
         deep : bool, default False
         name : Label
             Kept for compatibility with 1-dimensional Index. Should not be used.
@@ -1148,6 +1152,21 @@ def copy(
         This could be potentially expensive on large MultiIndex objects.
         """
         names = self._validate_names(name=name, names=names, deep=deep)
+        if levels is not None:
+            warnings.warn(
+                "parameter levels is deprecated and will be removed in a future "
+                "version. Use the set_levels method instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+        if codes is not None:
+            warnings.warn(
+                "parameter codes is deprecated and will be removed in a future "
+                "version. Use the set_codes method instead.",
+                FutureWarning,
+                stacklevel=2,
+            )
+
         if deep:
             from copy import deepcopy
 
@@ -1575,7 +1594,7 @@ def dropna(self, how="any"):
             raise ValueError(f"invalid how option: {how}")
 
         new_codes = [level_codes[~indexer] for level_codes in self.codes]
-        return self.copy(codes=new_codes, deep=True)
+        return self.set_codes(codes=new_codes)
 
     def _get_level_values(self, level, unique=False):
         """

pandas/tests/indexes/multi/test_copy.py

@@ -69,8 +69,6 @@ def test_copy_method(deep):
     "kwarg, value",
     [
         ("names", ["third", "fourth"]),
-        ("levels", [["foo2", "bar2"], ["fizz2", "buzz2"]]),
-        ("codes", [[1, 0, 0, 0], [1, 1, 0, 0]]),
     ],
 )
 def test_copy_method_kwargs(deep, kwarg, value):
@@ -85,3 +83,24 @@ def test_copy_method_kwargs(deep, kwarg, value):
         assert getattr(idx_copy, kwarg) == value
     else:
         assert [list(i) for i in getattr(idx_copy, kwarg)] == value
+
+
+@pytest.mark.parametrize("deep", [True, False])
+@pytest.mark.parametrize(
+    "param_name, param_value",
+    [
+        ("levels", [["foo2", "bar2"], ["fizz2", "buzz2"]]),
+        ("codes", [[1, 0, 0, 0], [1, 1, 0, 0]]),
+    ],
+)
+def test_copy_deprecated_parameters(deep, param_name, param_value):
+    # gh-36685
+    idx = MultiIndex(
+        levels=[["foo", "bar"], ["fizz", "buzz"]],
+        codes=[[0, 0, 0, 1], [0, 0, 1, 1]],
+        names=["first", "second"],
+    )
+    with tm.assert_produces_warning(FutureWarning):
+        idx_copy = idx.copy(deep=deep, **{param_name: param_value})
+
+    assert [list(i) for i in getattr(idx_copy, param_name)] == param_value