Deprecate inplace in Categorical.reorder_categories. (pandas-dev#41133)

Author: OlehKSS

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` 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` 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

@@ -1031,7 +1031,7 @@ def rename_categories(self, new_categories, inplace=False):
         if not inplace:
             return cat
 
-    def reorder_categories(self, new_categories, ordered=None, inplace=False):
+    def reorder_categories(self, new_categories, ordered=None, inplace=no_default):
         """
         Reorder categories as specified in new_categories.
 
@@ -1049,6 +1049,8 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
            Whether or not to reorder the categories inplace or return a copy of
            this categorical with reordered categories.
 
+           .. deprecated:: 1.3.0
+
         Returns
         -------
         cat : Categorical or None
@@ -1068,6 +1070,18 @@ def reorder_categories(self, new_categories, ordered=None, 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."
+                "reorder_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")
         if set(self.dtype.categories) != set(new_categories):
             raise ValueError(

pandas/tests/arrays/categorical/test_analytics.py

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

pandas/tests/arrays/categorical/test_api.py

@@ -153,7 +153,10 @@ def test_reorder_categories(self):
         tm.assert_categorical_equal(res, new)
 
         # inplace == True
-        res = cat.reorder_categories(["c", "b", "a"], inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = cat.reorder_categories(["c", "b", "a"], inplace=True)
+
         assert res is None
         tm.assert_categorical_equal(cat, new)