DEPR: deprecate include/exclude on Series.describe (GH-54193)

doc/source/whatsnew/v3.1.0.rst

@@ -118,6 +118,7 @@ Deprecations
 - Deprecated the ``.name`` property of offset objects (e.g., :class:`~pandas.tseries.offsets.Day`, :class:`~pandas.tseries.offsets.Hour`). Use ``.rule_code`` instead (:issue:`64207`)
 - Deprecated the ``dropna`` keyword in :meth:`DataFrame.to_hdf`, :meth:`HDFStore.put`, :meth:`HDFStore.append`, and :meth:`HDFStore.append_to_multiple`, and the ``io.hdf.dropna_table`` option. Use :meth:`DataFrame.dropna` before writing instead (:issue:`32038`)
 - Deprecated the ``float_precision`` argument in :func:`read_csv`, :func:`read_table`, and :func:`read_fwf`. All float precision modes now use the same converter (:issue:`64395`)
+- Deprecated the ``include`` and ``exclude`` arguments of :meth:`Series.describe`. They had no effect on a Series; filter dtypes upstream of the call instead (:issue:`54193`)
 - Deprecated the ``weekday`` property on :class:`DatetimeIndex`, :class:`.DatetimeArray`, :class:`PeriodIndex`, :class:`.PeriodArray`, and :class:`Period`. Use ``day_of_week`` instead. ``Timestamp.weekday()`` remains a method consistent with :meth:`datetime.datetime.weekday` (:issue:`12816`)
 - Deprecated the ``xlrd`` and ``pyxlsb`` engines in :func:`read_excel`. Use ``engine="calamine"`` instead (:issue:`56542`)
 - Deprecated the default value of ``exact`` in :func:`assert_index_equal`; in a future version this will default to ``True`` instead of "equiv" (:issue:`57436`)

pandas/core/generic.py

@@ -11305,7 +11305,8 @@ def describe(
             return the 25th, 50th, and 75th percentiles.
         include : 'all', list-like of dtypes or None (default), optional
             A white list of data types to include in the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - 'all' : All columns of the input will be included in the output.
             - A list-like of dtypes : Limits the results to the
@@ -11319,7 +11320,8 @@ def describe(
             - None (default) : The result will include all numeric columns.
         exclude : list-like of dtypes or None (default), optional,
             A black list of data types to omit from the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - A list-like of dtypes : Excludes the provided data types
               from the result. To exclude numeric types submit
@@ -11370,7 +11372,8 @@ def describe(
 
         The `include` and `exclude` parameters can be used to limit
         which columns in a ``DataFrame`` are analyzed for the output.
-        The parameters are ignored when analyzing a ``Series``.
+        Passing them when analyzing a ``Series`` is deprecated and will
+        raise in a future version; the parameters are ignored today.
 
         Examples
         --------

pandas/core/groupby/generic.py

@@ -970,7 +970,8 @@ def describe(self, percentiles=None, include=None, exclude=None) -> Series:
             return the 25th, 50th, and 75th percentiles.
         include : 'all', list-like of dtypes or None (default), optional
             A white list of data types to include in the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - 'all' : All columns of the input will be included in the output.
             - A list-like of dtypes : Limits the results to the
@@ -984,7 +985,8 @@ def describe(self, percentiles=None, include=None, exclude=None) -> Series:
             - None (default) : The result will include all numeric columns.
         exclude : list-like of dtypes or None (default), optional,
             A black list of data types to omit from the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - A list-like of dtypes : Excludes the provided data types
               from the result. To exclude numeric types submit
@@ -1035,7 +1037,8 @@ def describe(self, percentiles=None, include=None, exclude=None) -> Series:
 
         The `include` and `exclude` parameters can be used to limit
         which columns in a ``DataFrame`` are analyzed for the output.
-        The parameters are ignored when analyzing a ``Series``.
+        Passing them when analyzing a ``Series`` is deprecated and will
+        raise in a future version; the parameters are ignored today.
 
         Examples
         --------

pandas/core/groupby/groupby.py

@@ -3461,7 +3461,8 @@ def describe(
             return the 25th, 50th, and 75th percentiles.
         include : 'all', list-like of dtypes or None (default), optional
             A white list of data types to include in the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - 'all' : All columns of the input will be included in the output.
             - A list-like of dtypes : Limits the results to the
@@ -3475,7 +3476,8 @@ def describe(
             - None (default) : The result will include all numeric columns.
         exclude : list-like of dtypes or None (default), optional,
             A black list of data types to omit from the result. Ignored
-            for ``Series``. Here are the options:
+            for ``Series`` (deprecated; will be removed in a future
+            version). Here are the options:
 
             - A list-like of dtypes : Excludes the provided data types
               from the result. To exclude numeric types submit
@@ -3526,7 +3528,8 @@ def describe(
 
         The `include` and `exclude` parameters can be used to limit
         which columns in a ``DataFrame`` are analyzed for the output.
-        The parameters are ignored when analyzing a ``Series``.
+        Passing them when analyzing a ``Series`` is deprecated and will
+        raise in a future version; the parameters are ignored today.
 
         Examples
         --------

pandas/core/methods/describe.py

@@ -14,9 +14,12 @@
     TYPE_CHECKING,
     cast,
 )
+import warnings
 
 import numpy as np
 
+from pandas.errors import Pandas4Warning
+from pandas.util._exceptions import find_stack_level
 from pandas.util._validators import validate_percentile
 
 from pandas.core.dtypes.common import (
@@ -85,6 +88,15 @@ def describe_ndframe(
 
     describer: NDFrameDescriberAbstract
     if obj.ndim == 1:
+        if include is not None or exclude is not None:
+            # GH#54193
+            warnings.warn(
+                "The 'include' and 'exclude' arguments are deprecated for "
+                "Series.describe and will be removed in a future version. "
+                "These arguments have no effect on Series and will be removed.",
+                Pandas4Warning,
+                stacklevel=find_stack_level(),
+            )
         describer = SeriesDescriber(
             obj=cast("Series", obj),
         )

pandas/tests/groupby/methods/test_describe.py

@@ -1,6 +1,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 import pandas as pd
 from pandas import (
     DataFrame,
@@ -265,7 +267,11 @@ def test_groupby_empty_dataset(dtype, kwargs):
     expected = df.groupby("A").describe(**kwargs).reset_index(drop=True).iloc[:0]
     tm.assert_frame_equal(result, expected)
 
-    result = df.iloc[:0].groupby("A").B.describe(**kwargs)
-    expected = df.groupby("A").B.describe(**kwargs).reset_index(drop=True).iloc[:0]
+    # GH#54193: include/exclude on Series.describe is deprecated
+    msg = "'include' and 'exclude' arguments are deprecated for Series.describe"
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result = df.iloc[:0].groupby("A").B.describe(**kwargs)
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        expected = df.groupby("A").B.describe(**kwargs).reset_index(drop=True).iloc[:0]
     expected.index = Index([], dtype=df.columns.dtype)
     tm.assert_frame_equal(result, expected)

pandas/tests/series/methods/test_describe.py

@@ -1,6 +1,8 @@
 import numpy as np
 import pytest
 
+from pandas.errors import Pandas4Warning
+
 from pandas.core.dtypes.common import (
     is_complex_dtype,
     is_extension_array_dtype,
@@ -199,3 +201,21 @@ def test_describe_one_element_ea(self):
             index=["count", "mean", "std", "min", "25%", "50%", "75%", "max"],
         )
         tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "kwargs",
+        [
+            {"include": [np.number]},
+            {"exclude": [object]},
+            {"include": "all"},
+            {"include": [np.number], "exclude": [object]},
+        ],
+    )
+    def test_describe_include_exclude_deprecated(self, kwargs):
+        # GH#54193 - include/exclude have no effect on Series; deprecate them.
+        ser = Series([1, 2, 3], name="int_data")
+        msg = "'include' and 'exclude' arguments are deprecated for Series.describe"
+        with tm.assert_produces_warning(Pandas4Warning, match=msg):
+            result = ser.describe(**kwargs)
+        expected = ser.describe()
+        tm.assert_series_equal(result, expected)