Deprecate inplace in Categorical.rename_categories

doc/source/whatsnew/v1.3.0.rst

@@ -609,7 +609,7 @@ Deprecations
 - Deprecated using :func:`merge` or :func:`join` on a different number of levels (:issue:`34862`)
 - Deprecated the use of ``**kwargs`` in :class:`.ExcelWriter`; use the keyword argument ``engine_kwargs`` instead (:issue:`40430`)
 - Deprecated the ``level`` keyword for :class:`DataFrame` and :class:`Series` aggregations; use groupby instead (:issue:`39983`)
-- The ``inplace`` parameter of :meth:`Categorical.remove_categories`, :meth:`Categorical.add_categories`, :meth:`Categorical.reorder_categories` is deprecated and will be removed in a future version (:issue:`37643`)
+- The ``inplace`` parameter of :meth:`Categorical.remove_categories`, :meth:`Categorical.add_categories`, :meth:`Categorical.reorder_categories`, :meth:`Categorical.rename_categories` is deprecated and will be removed in a future version (:issue:`37643`)
 - Deprecated :func:`merge` producing duplicated columns through the ``suffixes`` keyword  and already existing columns (:issue:`22818`)
 
 .. ---------------------------------------------------------------------------

pandas/core/arrays/categorical.py

@@ -955,7 +955,7 @@ def set_categories(self, new_categories, ordered=None, rename=False, inplace=Fal
         if not inplace:
             return cat
 
-    def rename_categories(self, new_categories, inplace=False):
+    def rename_categories(self, new_categories, inplace=no_default):
         """
         Rename categories.
 
@@ -980,6 +980,8 @@ def rename_categories(self, new_categories, inplace=False):
             Whether or not to rename the categories inplace or return a copy of
             this categorical with renamed categories.
 
+            .. deprecated:: 1.3.0
+
         Returns
         -------
         cat : Categorical or None
@@ -1019,6 +1021,18 @@ def rename_categories(self, new_categories, inplace=False):
         ['A', 'A', 'B']
         Categories (2, object): ['A', 'B']
         """
+        if inplace is not no_default:
+            warn(
+                "The `inplace` parameter in pandas.Categorical."
+                "rename_categories is deprecated and will be removed in "
+                "a future version. Removing unused categories will always "
+                "return a new Categorical object.",
+                FutureWarning,
+                stacklevel=2,
+            )
+        else:
+            inplace = False
+
         inplace = validate_bool_kwarg(inplace, "inplace")
         cat = self if inplace else self.copy()
 
@@ -2417,7 +2431,9 @@ def replace(self, to_replace, value, inplace: bool = False):
                         cat.remove_categories(replace_value, inplace=True)
                 else:
                     categories[index] = new_value
-                    cat.rename_categories(categories, inplace=True)
+                    with catch_warnings():
+                        simplefilter("ignore")
+                        cat.rename_categories(categories, inplace=True)
         if not inplace:
             return cat
 

pandas/tests/arrays/categorical/test_analytics.py

@@ -317,7 +317,9 @@ def test_validate_inplace_raises(self, value):
             cat.set_categories(["X", "Y", "Z"], rename=True, inplace=value)
 
         with pytest.raises(ValueError, match=msg):
-            cat.rename_categories(["X", "Y", "Z"], inplace=value)
+            with tm.assert_produces_warning(FutureWarning):
+                # issue #37643 inplace kwarg deprecated
+                cat.rename_categories(["X", "Y", "Z"], inplace=value)
 
         with pytest.raises(ValueError, match=msg):
             with tm.assert_produces_warning(FutureWarning):

pandas/tests/arrays/categorical/test_api.py

@@ -82,7 +82,10 @@ def test_rename_categories(self):
         tm.assert_categorical_equal(result, expected)
 
         # and now inplace
-        res = cat.rename_categories([1, 2, 3], inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = cat.rename_categories([1, 2, 3], inplace=True)
+
         assert res is None
         tm.assert_numpy_array_equal(
             cat.__array__(), np.array([1, 2, 3, 1], dtype=np.int64)
@@ -114,7 +117,10 @@ def test_rename_categories_dict(self):
         tm.assert_index_equal(res.categories, expected)
 
         # Test for inplace
-        res = cat.rename_categories({"a": 4, "b": 3, "c": 2, "d": 1}, inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = cat.rename_categories({"a": 4, "b": 3, "c": 2, "d": 1}, inplace=True)
+
         assert res is None
         tm.assert_index_equal(cat.categories, expected)