DEPR: make Categorical.ravel() return Categorical (#27199)

Author: jbrockmendel

doc/source/whatsnew/v0.25.0.rst

@@ -862,6 +862,7 @@ Other deprecations
 - The default value ``ordered=None`` in :class:`~pandas.api.types.CategoricalDtype` has been deprecated in favor of ``ordered=False``. When converting between categorical types ``ordered=True`` must be explicitly passed in order to be preserved. (:issue:`26336`)
 - :meth:`Index.contains` is deprecated. Use ``key in index`` (``__contains__``) instead (:issue:`17753`).
 - :meth:`DataFrame.get_dtype_counts` is deprecated. (:issue:`18262`)
+- :meth:`Categorical.ravel` will return a :class:`Categorical` instead of a ``np.ndarray`` (:issue:`27199`)
 
 .. _whatsnew_0250.prior_deprecations:
 

pandas/core/arrays/base.py

@@ -909,6 +909,21 @@ def _formatting_values(self) -> np.ndarray:
     # Reshaping
     # ------------------------------------------------------------------------
 
+    def ravel(self, order="C") -> ABCExtensionArray:
+        """
+        Return a flattened view on this array.
+
+        Parameters
+        ----------
+        order : {None, 'C', 'F', 'A', 'K'}, default 'C'
+
+        Notes
+        -----
+        - Because ExtensionArrays are 1D-only, this is a no-op.
+        - The "order" argument is ignored, is for compatibility with NumPy.
+        """
+        return self
+
     @classmethod
     def _concat_same_type(
             cls,

pandas/core/arrays/categorical.py

@@ -1713,6 +1713,9 @@ def ravel(self, order='C'):
         -------
         numpy.array
         """
+        warn("Categorical.ravel will return a Categorical object instead "
+             "of an ndarray in a future version.",
+             FutureWarning, stacklevel=2)
         return np.array(self)
 
     def view(self):

pandas/tests/extension/base/base.py

@@ -2,6 +2,7 @@
 
 
 class BaseExtensionTests:
+
     assert_equal = staticmethod(tm.assert_equal)
     assert_series_equal = staticmethod(tm.assert_series_equal)
     assert_frame_equal = staticmethod(tm.assert_frame_equal)

pandas/tests/extension/base/reshaping.py

@@ -269,3 +269,12 @@ def test_unstack(self, data, index, obj):
             result = result.astype(object)
 
             self.assert_frame_equal(result, expected)
+
+    def test_ravel(self, data):
+        # as long as EA is 1D-only, ravel is a no-op
+        result = data.ravel()
+        assert type(result) == type(data)
+
+        # Check that we have a view, not a copy
+        result[0] = result[1]
+        assert data[0] == data[1]

pandas/tests/extension/test_categorical.py

@@ -22,6 +22,7 @@
 from pandas import Categorical
 from pandas.api.types import CategoricalDtype
 from pandas.tests.extension import base
+import pandas.util.testing as tm
 
 
 def make_data():
@@ -94,7 +95,11 @@ class TestConstructors(base.BaseConstructorsTests):
 
 
 class TestReshaping(base.BaseReshapingTests):
-    pass
+
+    def test_ravel(self, data):
+        # GH#27199 Categorical.ravel returns self until after deprecation cycle
+        with tm.assert_produces_warning(FutureWarning):
+            data.ravel()
 
 
 class TestGetitem(base.BaseGetitemTests):

pandas/tests/extension/test_sparse.py

@@ -82,11 +82,14 @@ def data_for_grouping(request):
 
 
 class BaseSparseTests:
-
     def _check_unsupported(self, data):
         if data.dtype == SparseDtype(int, 0):
             pytest.skip("Can't store nan in int array.")
 
+    @pytest.mark.xfail(reason="SparseArray does not support setitem")
+    def test_ravel(self, data):
+        super().test_ravel(data)
+
 
 class TestDtype(BaseSparseTests, base.BaseDtypeTests):