diff --git a/doc/source/whatsnew/v1.3.0.rst b/doc/source/whatsnew/v1.3.0.rst index 842b50ce53b21..8458a32f252ce 100644 --- a/doc/source/whatsnew/v1.3.0.rst +++ b/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`) .. --------------------------------------------------------------------------- diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 250ab9e771559..6f3643e80a0fa 100644 --- a/pandas/core/arrays/categorical.py +++ b/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( diff --git a/pandas/tests/arrays/categorical/test_analytics.py b/pandas/tests/arrays/categorical/test_analytics.py index 769ded059b29f..56971af9bcd3f 100644 --- a/pandas/tests/arrays/categorical/test_analytics.py +++ b/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): diff --git a/pandas/tests/arrays/categorical/test_api.py b/pandas/tests/arrays/categorical/test_api.py index 42affbef1a76d..2eeb502d36367 100644 --- a/pandas/tests/arrays/categorical/test_api.py +++ b/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)