Deprecate inplace in Categorical.remove_categories

doc/source/whatsnew/v1.3.0.rst

@@ -540,6 +540,8 @@ Deprecations
 - Deprecated allowing partial failure in :meth:`Series.transform` and :meth:`DataFrame.transform` when ``func`` is list-like or dict-like and raises anything but ``TypeError``; ``func`` raising anything but a ``TypeError`` will raise in a future version (:issue:`40211`)
 - Deprecated support for ``np.ma.mrecords.MaskedRecords`` in the :class:`DataFrame` constructor, pass ``{name: data[name] for name in data.dtype.names}`` instead (:issue:`40363`)
 - Deprecated the use of ``**kwargs`` in :class:`.ExcelWriter`; use the keyword argument ``engine_kwargs`` instead (:issue:`40430`)
+- The ``inplace`` parameter of :meth:`Categorical.remove_categories` is deprecated and will be removed in a future version (:issue:`37643`)
+-
 
 .. ---------------------------------------------------------------------------
 

pandas/core/arrays/categorical.py

@@ -17,7 +17,11 @@
     Union,
     cast,
 )
-from warnings import warn
+from warnings import (
+    catch_warnings,
+    simplefilter,
+    warn,
+)
 
 import numpy as np
 
@@ -1125,7 +1129,7 @@ def add_categories(self, new_categories, inplace=False):
         if not inplace:
             return cat
 
-    def remove_categories(self, removals, inplace=False):
+    def remove_categories(self, removals, inplace=no_default):
         """
         Remove the specified categories.
 
@@ -1140,6 +1144,8 @@ def remove_categories(self, removals, inplace=False):
            Whether or not to remove the categories inplace or return a copy of
            this categorical with removed categories.
 
+           .. deprecated:: 1.2.0
+
         Returns
         -------
         cat : Categorical or None
@@ -1158,6 +1164,17 @@ def remove_categories(self, removals, inplace=False):
         remove_unused_categories : Remove categories which are not used.
         set_categories : Set the categories to the specified ones.
         """
+        if inplace is not no_default:
+            warn(
+                "The `inplace` parameter in pandas.Categorical."
+                "remove_categories is deprecated and "
+                "will be removed in a future version.",
+                FutureWarning,
+                stacklevel=2,
+            )
+        else:
+            inplace = False
+
         inplace = validate_bool_kwarg(inplace, "inplace")
         if not is_list_like(removals):
             removals = [removals]
@@ -2357,14 +2374,20 @@ def replace(self, to_replace, value, inplace: bool = False):
                 continue
             if replace_value in cat.categories:
                 if isna(new_value):
-                    cat.remove_categories(replace_value, inplace=True)
+                    with catch_warnings():
+                        simplefilter("ignore")
+                        cat.remove_categories(replace_value, inplace=True)
                     continue
+
                 categories = cat.categories.tolist()
                 index = categories.index(replace_value)
+
                 if new_value in cat.categories:
                     value_index = categories.index(new_value)
                     cat._codes[cat._codes == index] = value_index
-                    cat.remove_categories(replace_value, inplace=True)
+                    with catch_warnings():
+                        simplefilter("ignore")
+                        cat.remove_categories(replace_value, inplace=True)
                 else:
                     categories[index] = new_value
                     cat.rename_categories(categories, inplace=True)

pandas/tests/arrays/categorical/test_analytics.py

@@ -360,7 +360,9 @@ def test_validate_inplace_raises(self, value):
             cat.add_categories(new_categories=["D", "E", "F"], inplace=value)
 
         with pytest.raises(ValueError, match=msg):
-            cat.remove_categories(removals=["D", "E", "F"], inplace=value)
+            with tm.assert_produces_warning(FutureWarning):
+                # issue #37643 inplace kwarg deprecated
+                cat.remove_categories(removals=["D", "E", "F"], inplace=value)
 
         with pytest.raises(ValueError, match=msg):
             with tm.assert_produces_warning(FutureWarning):

pandas/tests/arrays/categorical/test_api.py

@@ -354,7 +354,10 @@ def test_remove_categories(self):
         tm.assert_categorical_equal(res, new)
 
         # inplace == True
-        res = cat.remove_categories("c", inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = cat.remove_categories("c", inplace=True)
+
         tm.assert_categorical_equal(cat, new)
         assert res is None