DEPR: setting Categorical._codes (#41429)

doc/source/whatsnew/v1.3.0.rst

@@ -644,6 +644,7 @@ Deprecations
 - 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`, :meth:`Categorical.reorder_categories`, :meth:`Categorical.rename_categories`, :meth:`Categorical.set_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`)
+- Deprecated setting :attr:`Categorical._codes`, create a new :class:`Categorical` with the desired codes instead (:issue:`40606`)
 
 .. ---------------------------------------------------------------------------
 

pandas/core/arrays/categorical.py

@@ -1861,6 +1861,12 @@ def _codes(self) -> np.ndarray:
 
     @_codes.setter
     def _codes(self, value: np.ndarray):
+        warn(
+            "Setting the codes on a Categorical is deprecated and will raise in "
+            "a future version. Create a new Categorical object instead",
+            FutureWarning,
+            stacklevel=2,
+        )  # GH#40606
         NDArrayBacked.__init__(self, value, self.dtype)
 
     def _box_func(self, i: int):

pandas/tests/arrays/categorical/test_api.py

@@ -489,6 +489,15 @@ def test_set_categories_inplace(self):
 
         tm.assert_index_equal(cat.categories, Index(["a", "b", "c", "d"]))
 
+    def test_codes_setter_deprecated(self):
+        cat = Categorical([1, 2, 3, 1, 2, 3, 3, 2, 1, 1, 1])
+        new_codes = cat._codes + 1
+        with tm.assert_produces_warning(FutureWarning):
+            # GH#40606
+            cat._codes = new_codes
+
+        assert cat._codes is new_codes
+
 
 class TestPrivateCategoricalAPI:
     def test_codes_immutable(self):