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,10 +1057,12 @@ 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
-            Categorical with unused categories dropped or None if ``inplace=True``.
+            Categorical with unused categories dropped.
 
         See Also
         --------
@@ -1069,8 +1072,15 @@ def remove_unused_categories(self, inplace=False):
         remove_categories : Remove the specified categories.
         set_categories : Set the categories to the specified ones.
         """
-        inplace = validate_bool_kwarg(inplace, "inplace")
-        cat = self if inplace else self.copy()
+        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,
+            )
+
+        cat = self.copy()
         idx, inv = np.unique(cat._codes, return_inverse=True)
 
         if idx.size != 0 and idx[0] == -1:  # na sentinel
@@ -1083,8 +1093,7 @@ def remove_unused_categories(self, inplace=False):
         cat._dtype = new_dtype
         cat._codes = coerce_indexer_dtype(inv, new_dtype.categories)
 
-        if not inplace:
-            return cat
+        return cat
 
     # ------------------------------------------------------------------
 

pandas/tests/arrays/categorical/test_analytics.py

@@ -354,7 +354,7 @@ def test_validate_inplace_raises(self, value):
         with pytest.raises(ValueError, match=msg):
             cat.remove_categories(removals=["D", "E", "F"], inplace=value)
 
-        with pytest.raises(ValueError, match=msg):
+        with tm.assert_produces_warning(FutureWarning):
             cat.remove_unused_categories(inplace=value)
 
         with pytest.raises(ValueError, match=msg):

pandas/tests/arrays/categorical/test_api.py

@@ -371,9 +371,8 @@ 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)
-        tm.assert_index_equal(c.categories, exp_categories_dropped)
-        assert res is None
+        with tm.assert_produces_warning(FutureWarning):
+            c.remove_unused_categories(inplace=True)
 
         # with NaN values (GH11599)
         c = Categorical(["a", "b", "c", np.nan], categories=["a", "b", "c", "d", "e"])