DEPR: Deprecate ravel

doc/source/whatsnew/v2.2.0.rst

@@ -266,6 +266,7 @@ Other Deprecations
 - Deprecated :func:`read_gbq` and :meth:`DataFrame.to_gbq`. Use ``pandas_gbq.read_gbq`` and ``pandas_gbq.to_gbq`` instead https://pandas-gbq.readthedocs.io/en/latest/api.html (:issue:`55525`)
 - Deprecated :meth:`.DataFrameGroupBy.fillna` and :meth:`.SeriesGroupBy.fillna`; use :meth:`.DataFrameGroupBy.ffill`, :meth:`.DataFrameGroupBy.bfill` for forward and backward filling or :meth:`.DataFrame.fillna` to fill with a single value (or the Series equivalents) (:issue:`55718`)
 - Deprecated :meth:`Index.format`, use ``index.astype(str)`` or ``index.map(formatter)`` instead (:issue:`55413`)
+- Deprecated :meth:`Series.ravel`, use ``np.ravel`` instead (:issue:`52511`)
 - Deprecated ``year``, ``month``, ``quarter``, ``day``, ``hour``, ``minute``, and ``second`` keywords in the :class:`PeriodIndex` constructor, use :meth:`PeriodIndex.from_fields` instead (:issue:`55960`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_clipboard`. (:issue:`54229`)
 - Deprecated allowing non-keyword arguments in :meth:`DataFrame.to_csv` except ``path_or_buf``. (:issue:`54229`)

pandas/_testing/asserters.py

@@ -426,6 +426,8 @@ def assert_is_valid_plot_return_object(objs) -> None:
     from matplotlib.axes import Axes
 
     if isinstance(objs, (Series, np.ndarray)):
+        if isinstance(objs, Series):
+            objs = objs._values
         for el in objs.ravel():
             msg = (
                 "one of 'objs' is not a matplotlib Axes instance, "

pandas/core/reshape/pivot.py

@@ -309,15 +309,17 @@ def _add_margins(
 
     row_names = result.index.names
     # check the result column and leave floats
+
+    def _cast_types(x, dtype):
+        return maybe_downcast_to_dtype(x._values, dtype)
+
     for dtype in set(result.dtypes):
         if isinstance(dtype, ExtensionDtype):
             # Can hold NA already
             continue
 
         cols = result.select_dtypes([dtype]).columns
-        margin_dummy[cols] = margin_dummy[cols].apply(
-            maybe_downcast_to_dtype, args=(dtype,)
-        )
+        margin_dummy[cols] = margin_dummy[cols].apply(_cast_types, args=(dtype,))
     result = result._append(margin_dummy)
     result.index.names = row_names
 

pandas/core/series.py

@@ -858,9 +858,14 @@ def ravel(self, order: str = "C") -> ArrayLike:
         Examples
         --------
         >>> s = pd.Series([1, 2, 3])
-        >>> s.ravel()
+        >>> s.ravel()  # doctest: +SKIP
         array([1, 2, 3])
         """
+        warnings.warn(
+            "Series.ravel is deprecated. Use numpy.ravel directly.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
         arr = self._values.ravel(order=order)
         if isinstance(arr, np.ndarray) and using_copy_on_write():
             arr.flags.writeable = False

pandas/tests/copy_view/test_array.py

@@ -116,7 +116,8 @@ def test_series_to_numpy(using_copy_on_write):
 @pytest.mark.parametrize("order", ["F", "C"])
 def test_ravel_read_only(using_copy_on_write, order):
     ser = Series([1, 2, 3])
-    arr = ser.ravel(order=order)
+    with tm.assert_produces_warning(FutureWarning, match="is deprecated"):
+        arr = ser.ravel(order=order)
     if using_copy_on_write:
         assert arr.flags.writeable is False
     assert np.shares_memory(get_array(ser), arr)

pandas/tests/series/test_api.py

@@ -140,7 +140,9 @@ def test_ndarray_compat_like_func(self):
     def test_ndarray_compat_ravel(self):
         # ravel
         s = Series(np.random.default_rng(2).standard_normal(10))
-        tm.assert_almost_equal(s.ravel(order="F"), s.values.ravel(order="F"))
+        with tm.assert_produces_warning(FutureWarning, match="ravel is deprecated"):
+            result = s.ravel(order="F")
+        tm.assert_almost_equal(result, s.values.ravel(order="F"))
 
     def test_empty_method(self):
         s_empty = Series(dtype=object)