DEPR: enforce deprecation of Categorical.replace

doc/source/whatsnew/v2.0.0.rst

@@ -159,6 +159,7 @@ Removal of prior version deprecations/changes
 - Removed argument ``try_cast`` from :meth:`DataFrame.mask`, :meth:`DataFrame.where`, :meth:`Series.mask` and :meth:`Series.where` (:issue:`38836`)
 - Disallow passing non-round floats to :class:`Timestamp` with ``unit="M"`` or ``unit="Y"`` (:issue:`47266`)
 - Removed deprecated :meth:`Timedelta.delta`, :meth:`Timedelta.is_populated`, and :attr:`Timedelta.freq` (:issue:`46430`, :issue:`46476`)
+- Removed deprecated :meth:`Categorical.replace`, use :meth:`Series.replace` instead (:issue:`44929`)
 - Removed the ``numeric_only`` keyword from :meth:`Categorical.min` and :meth:`Categorical.max` in favor of ``skipna`` (:issue:`48821`)
 - Removed :func:`is_extension_type` in favor of :func:`is_extension_array_dtype` (:issue:`29457`)
 - Removed :meth:`Index.get_value` (:issue:`33907`)

pandas/core/arrays/categorical.py

@@ -2625,53 +2625,6 @@ def isin(self, values) -> npt.NDArray[np.bool_]:
         code_values = code_values[null_mask | (code_values >= 0)]
         return algorithms.isin(self.codes, code_values)
 
-    @overload
-    def replace(
-        self, to_replace, value, *, inplace: Literal[False] = ...
-    ) -> Categorical:
-        ...
-
-    @overload
-    def replace(self, to_replace, value, *, inplace: Literal[True]) -> None:
-        ...
-
-    @deprecate_nonkeyword_arguments(version=None, allowed_args=["self", "value"])
-    def replace(self, to_replace, value, inplace: bool = False) -> Categorical | None:
-        """
-        Replaces all instances of one value with another
-
-        Parameters
-        ----------
-        to_replace: object
-            The value to be replaced
-
-        value: object
-            The value to replace it with
-
-        inplace: bool
-            Whether the operation is done in-place
-
-        Returns
-        -------
-        None if inplace is True, otherwise the new Categorical after replacement
-
-
-        Examples
-        --------
-        >>> s = pd.Categorical([1, 2, 1, 3])
-        >>> s.replace(1, 3)
-        [3, 2, 3, 3]
-        Categories (2, int64): [2, 3]
-        """
-        # GH#44929 deprecation
-        warn(
-            "Categorical.replace is deprecated and will be removed in a future "
-            "version. Use Series.replace directly instead.",
-            FutureWarning,
-            stacklevel=find_stack_level(),
-        )
-        return self._replace(to_replace=to_replace, value=value, inplace=inplace)
-
     def _replace(self, *, to_replace, value, inplace: bool = False):
         inplace = validate_bool_kwarg(inplace, "inplace")
         cat = self if inplace else self.copy()

pandas/tests/arrays/categorical/test_replace.py

@@ -1,7 +1,6 @@
 import pytest
 
 import pandas as pd
-from pandas import Categorical
 import pandas._testing as tm
 
 
@@ -39,34 +38,3 @@ def test_replace_categorical_series(to_replace, value, expected, flip_categories
 
     tm.assert_series_equal(expected, result, check_category_order=False)
     tm.assert_series_equal(expected, ser, check_category_order=False)
-
-
-@pytest.mark.parametrize(
-    "to_replace, value, result, expected_error_msg",
-    [
-        ("b", "c", ["a", "c"], "Categorical.categories are different"),
-        ("c", "d", ["a", "b"], None),
-        # https://github.com/pandas-dev/pandas/issues/33288
-        ("a", "a", ["a", "b"], None),
-        ("b", None, ["a", None], "Categorical.categories length are different"),
-    ],
-)
-def test_replace_categorical(to_replace, value, result, expected_error_msg):
-    # GH#26988
-    cat = Categorical(["a", "b"])
-    expected = Categorical(result)
-    with tm.assert_produces_warning(FutureWarning, match="Series.replace"):
-        # GH#44929 replace->_replace
-        result = cat.replace(to_replace, value)
-
-    tm.assert_categorical_equal(result, expected)
-    if to_replace == "b":  # the "c" test is supposed to be unchanged
-        with pytest.raises(AssertionError, match=expected_error_msg):
-            # ensure non-inplace call does not affect original
-            tm.assert_categorical_equal(cat, expected)
-
-    with tm.assert_produces_warning(FutureWarning, match="Series.replace"):
-        # GH#44929 replace->_replace
-        cat.replace(to_replace, value, inplace=True)
-
-    tm.assert_categorical_equal(cat, expected)