Deprecate inplace in Categorical.add_categories. (pandas-dev#41118)

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` is deprecated and will be removed in a future version (:issue:`37643`)
+- The ``inplace`` parameter of :meth:`Categorical.remove_categories`, :meth:`Categorical.add_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

@@ -1075,7 +1075,7 @@ def reorder_categories(self, new_categories, ordered=None, inplace=False):
             )
         return self.set_categories(new_categories, ordered=ordered, inplace=inplace)
 
-    def add_categories(self, new_categories, inplace=False):
+    def add_categories(self, new_categories, inplace=no_default):
         """
         Add new categories.
 
@@ -1090,6 +1090,8 @@ def add_categories(self, new_categories, inplace=False):
            Whether or not to add the categories inplace or return a copy of
            this categorical with added categories.
 
+           .. deprecated:: 1.3.0
+
         Returns
         -------
         cat : Categorical or None
@@ -1109,6 +1111,18 @@ def add_categories(self, new_categories, 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."
+                "add_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 not is_list_like(new_categories):
             new_categories = [new_categories]

pandas/tests/arrays/categorical/test_analytics.py

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

pandas/tests/arrays/categorical/test_api.py

@@ -188,7 +188,10 @@ def test_add_categories(self):
         tm.assert_categorical_equal(res, new)
 
         # inplace == True
-        res = cat.add_categories("d", inplace=True)
+        with tm.assert_produces_warning(FutureWarning):
+            # issue #37643 inplace kwarg deprecated
+            res = cat.add_categories("d", inplace=True)
+
         tm.assert_categorical_equal(cat, new)
         assert res is None