Deprecate inplace in Categorical.remove_unused_categories

doc/source/whatsnew/v1.2.0.rst

@@ -458,6 +458,7 @@ Deprecations
 - :meth:`Categorical.is_dtype_equal` and :meth:`CategoricalIndex.is_dtype_equal` are deprecated, will be removed in a future version (:issue:`37545`)
 - :meth:`Series.slice_shift` and :meth:`DataFrame.slice_shift` are deprecated, use :meth:`Series.shift` or :meth:`DataFrame.shift` instead (:issue:`37601`)
 - Partial slicing on unordered :class:`DatetimeIndexes` with keys, which are not in Index is deprecated and will be removed in a future version (:issue:`18531`)
+- The ``inplace`` parameter of :meth:`Categorical.remove_unused_categories` is deprecated and will be removed in a future version (:issue:`37643`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/arrays/categorical.py

@@ -10,6 +10,7 @@
 from pandas._config import get_option
 
 from pandas._libs import NaT, algos as libalgos, hashtable as htable
+from pandas._libs.lib import no_default
 from pandas._typing import ArrayLike, Dtype, Ordered, Scalar
 from pandas.compat.numpy import function as nv
 from pandas.util._decorators import cache_readonly, deprecate_kwarg
@@ -1046,7 +1047,7 @@ def remove_categories(self, removals, inplace=False):
             new_categories, ordered=self.ordered, rename=False, inplace=inplace
         )
 
-    def remove_unused_categories(self, inplace=False):
+    def remove_unused_categories(self, inplace=no_default):
         """
         Remove categories which are not used.
 
@@ -1056,6 +1057,8 @@ def remove_unused_categories(self, inplace=False):
            Whether or not to drop unused categories inplace or return a copy of
            this categorical with unused categories dropped.
 
+           .. deprecated:: 1.2.0
+
         Returns
         -------
         cat : Categorical or None
@@ -1069,6 +1072,17 @@ def remove_unused_categories(self, inplace=False):
         remove_categories : Remove the specified categories.
         set_categories : Set the categories to the specified ones.
         """
+        if inplace is not no_default:
+            warn(
+                "The `inplace` parameter in pandas.Categorical."
+                "remove_unused_categories is deprecated and "
+                "will be removed in a future version.",
+                FutureWarning,
+                stacklevel=2,
+            )
+        else:
+            inplace = False
+
         inplace = validate_bool_kwarg(inplace, "inplace")
         cat = self if inplace else self.copy()
         idx, inv = np.unique(cat._codes, return_inverse=True)

pandas/tests/arrays/categorical/test_analytics.py

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

pandas/tests/arrays/categorical/test_api.py

@@ -371,7 +371,10 @@ def test_remove_unused_categories(self):
         tm.assert_index_equal(res.categories, exp_categories_dropped)
         tm.assert_index_equal(c.categories, exp_categories_all)
 
-        res = c.remove_unused_categories(inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = c.remove_unused_categories(inplace=True)
+
         tm.assert_index_equal(c.categories, exp_categories_dropped)
         assert res is None
 

pandas/tests/series/accessors/test_cat_accessor.py

@@ -81,7 +81,10 @@ def test_cat_accessor_updates_on_inplace(self):
         ser = Series(list("abc")).astype("category")
         return_value = ser.drop(0, inplace=True)
         assert return_value is None
-        return_value = ser.cat.remove_unused_categories(inplace=True)
+
+        with tm.assert_produces_warning(FutureWarning, check_stacklevel=False):
+            return_value = ser.cat.remove_unused_categories(inplace=True)
+
         assert return_value is None
         assert len(ser.cat.categories) == 2