DEPR: args and kwargs in rolling, expanding, and ewm ops (#47851)

Author: rhshadrach

doc/source/whatsnew/v1.5.0.rst

@@ -773,6 +773,7 @@ Other Deprecations
 - Deprecated :class:`Series` and :class:`Resampler` reducers (e.g. ``min``, ``max``, ``sum``, ``mean``) raising a ``NotImplementedError`` when the dtype is non-numric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
 - Deprecated :meth:`Series.rank` returning an empty result when the dtype is non-numeric and ``numeric_only=True`` is provided; this will raise a ``TypeError`` in a future version (:issue:`47500`)
 - Deprecated argument ``errors`` for :meth:`Series.mask`, :meth:`Series.where`, :meth:`DataFrame.mask`, and :meth:`DataFrame.where` as ``errors`` had no effect on this methods (:issue:`47728`)
+- Deprecated arguments ``*args`` and ``**kwargs`` in :class:`Rolling`, :class:`Expanding`, and :class:`ExponentialMovingWindow` ops. (:issue:`47836`)
 
 .. ---------------------------------------------------------------------------
 .. _whatsnew_150.performance:

pandas/core/window/common.py

@@ -3,9 +3,12 @@
 
 from collections import defaultdict
 from typing import cast
+import warnings
 
 import numpy as np
 
+from pandas.util._exceptions import find_stack_level
+
 from pandas.core.dtypes.generic import (
     ABCDataFrame,
     ABCSeries,
@@ -167,3 +170,38 @@ def prep_binary(arg1, arg2):
     X = arg1 + 0 * arg2
     Y = arg2 + 0 * arg1
     return X, Y
+
+
+def maybe_warn_args_and_kwargs(cls, kernel: str, args, kwargs) -> None:
+    """
+    Warn for deprecation of args and kwargs in rolling/expanding functions.
+
+    Parameters
+    ----------
+    cls : type
+        Class to warn about.
+    kernel : str
+        Operation name.
+    args : tuple or None
+        args passed by user. Will be None if and only if kernel does not have args.
+    kwargs : dict or None
+        kwargs passed by user. Will be None if and only if kernel does not have kwargs.
+    """
+    warn_args = args is not None and len(args) > 0
+    warn_kwargs = kwargs is not None and len(kwargs) > 0
+    if warn_args and warn_kwargs:
+        msg = "args and kwargs"
+    elif warn_args:
+        msg = "args"
+    elif warn_kwargs:
+        msg = "kwargs"
+    else:
+        msg = ""
+    if msg != "":
+        warnings.warn(
+            f"Passing additional {msg} to {cls.__name__}.{kernel} has "
+            "no impact on the result and is deprecated. This will "
+            "raise a TypeError in a future version of pandas.",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )

pandas/core/window/doc.py

@@ -43,14 +43,18 @@ def create_section_header(header: str) -> str:
 args_compat = dedent(
     """
     *args
-        For NumPy compatibility and will not have an effect on the result.\n
+        For NumPy compatibility and will not have an effect on the result.
+
+        .. deprecated:: 1.5.0\n
     """
 ).replace("\n", "", 1)
 
 kwargs_compat = dedent(
     """
     **kwargs
-        For NumPy compatibility and will not have an effect on the result.\n
+        For NumPy compatibility and will not have an effect on the result.
+
+        .. deprecated:: 1.5.0\n
     """
 ).replace("\n", "", 1)
 

pandas/core/window/ewm.py

@@ -42,7 +42,10 @@
     get_jit_arguments,
     maybe_use_numba,
 )
-from pandas.core.window.common import zsqrt
+from pandas.core.window.common import (
+    maybe_warn_args_and_kwargs,
+    zsqrt,
+)
 from pandas.core.window.doc import (
     _shared_docs,
     args_compat,
@@ -546,6 +549,7 @@ def mean(
         engine_kwargs=None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "mean", args, kwargs)
         if maybe_use_numba(engine):
             if self.method == "single":
                 func = generate_numba_ewm_func
@@ -603,6 +607,7 @@ def sum(
         engine_kwargs=None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "sum", args, kwargs)
         if not self.adjust:
             raise NotImplementedError("sum is not implemented with adjust=False")
         if maybe_use_numba(engine):
@@ -658,6 +663,7 @@ def sum(
         agg_method="std",
     )
     def std(self, bias: bool = False, numeric_only: bool = False, *args, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "std", args, kwargs)
         nv.validate_window_func("std", args, kwargs)
         if (
             numeric_only
@@ -702,6 +708,7 @@ def vol(self, bias: bool = False, *args, **kwargs):
         agg_method="var",
     )
     def var(self, bias: bool = False, numeric_only: bool = False, *args, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "var", args, kwargs)
         nv.validate_window_func("var", args, kwargs)
         window_func = window_aggregations.ewmcov
         wfunc = partial(
@@ -756,6 +763,7 @@ def cov(
     ):
         from pandas import Series
 
+        maybe_warn_args_and_kwargs(type(self), "cov", None, kwargs)
         self._validate_numeric_only("cov", numeric_only)
 
         def cov_func(x, y):
@@ -829,6 +837,7 @@ def corr(
     ):
         from pandas import Series
 
+        maybe_warn_args_and_kwargs(type(self), "corr", None, kwargs)
         self._validate_numeric_only("corr", numeric_only)
 
         def cov_func(x, y):

pandas/core/window/expanding.py

@@ -25,6 +25,7 @@
     ExpandingIndexer,
     GroupbyIndexer,
 )
+from pandas.core.window.common import maybe_warn_args_and_kwargs
 from pandas.core.window.doc import (
     _shared_docs,
     args_compat,
@@ -252,6 +253,7 @@ def sum(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "sum", args, kwargs)
         nv.validate_expanding_func("sum", args, kwargs)
         return super().sum(
             numeric_only=numeric_only,
@@ -285,6 +287,7 @@ def max(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "max", args, kwargs)
         nv.validate_expanding_func("max", args, kwargs)
         return super().max(
             numeric_only=numeric_only,
@@ -318,6 +321,7 @@ def min(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "min", args, kwargs)
         nv.validate_expanding_func("min", args, kwargs)
         return super().min(
             numeric_only=numeric_only,
@@ -351,6 +355,7 @@ def mean(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "mean", args, kwargs)
         nv.validate_expanding_func("mean", args, kwargs)
         return super().mean(
             numeric_only=numeric_only,
@@ -382,6 +387,7 @@ def median(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "median", None, kwargs)
         return super().median(
             numeric_only=numeric_only,
             engine=engine,
@@ -446,6 +452,7 @@ def std(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "std", args, kwargs)
         nv.validate_expanding_func("std", args, kwargs)
         return super().std(
             ddof=ddof,
@@ -512,6 +519,7 @@ def var(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "var", args, kwargs)
         nv.validate_expanding_func("var", args, kwargs)
         return super().var(
             ddof=ddof,
@@ -557,8 +565,9 @@ def var(
         aggregation_description="standard error of mean",
         agg_method="sem",
     )
-    def sem(self, ddof: int = 1, *args, **kwargs):
-        return super().sem(ddof=ddof, **kwargs)
+    def sem(self, ddof: int = 1, numeric_only: bool = False, *args, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "sem", args, kwargs)
+        return super().sem(ddof=ddof, numeric_only=numeric_only, **kwargs)
 
     @doc(
         template_header,
@@ -577,6 +586,7 @@ def sem(self, ddof: int = 1, *args, **kwargs):
         agg_method="skew",
     )
     def skew(self, numeric_only: bool = False, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "skew", None, kwargs)
         return super().skew(numeric_only=numeric_only, **kwargs)
 
     @doc(
@@ -618,6 +628,7 @@ def skew(self, numeric_only: bool = False, **kwargs):
         agg_method="kurt",
     )
     def kurt(self, numeric_only: bool = False, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "kurt", None, kwargs)
         return super().kurt(numeric_only=numeric_only, **kwargs)
 
     @doc(
@@ -656,6 +667,7 @@ def quantile(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "quantile", None, kwargs)
         return super().quantile(
             quantile=quantile,
             interpolation=interpolation,
@@ -733,6 +745,7 @@ def rank(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "rank", None, kwargs)
         return super().rank(
             method=method,
             ascending=ascending,
@@ -779,6 +792,7 @@ def cov(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "cov", None, kwargs)
         return super().cov(
             other=other,
             pairwise=pairwise,
@@ -852,6 +866,7 @@ def corr(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "corr", None, kwargs)
         return super().corr(
             other=other,
             pairwise=pairwise,

pandas/core/window/rolling.py

@@ -79,6 +79,7 @@
 )
 from pandas.core.window.common import (
     flex_binary_moment,
+    maybe_warn_args_and_kwargs,
     zsqrt,
 )
 from pandas.core.window.doc import (
@@ -2080,6 +2081,7 @@ def sum(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "sum", args, kwargs)
         nv.validate_rolling_func("sum", args, kwargs)
         return super().sum(
             numeric_only=numeric_only,
@@ -2113,6 +2115,7 @@ def max(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "max", args, kwargs)
         nv.validate_rolling_func("max", args, kwargs)
         return super().max(
             numeric_only=numeric_only,
@@ -2161,6 +2164,7 @@ def min(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "min", args, kwargs)
         nv.validate_rolling_func("min", args, kwargs)
         return super().min(
             numeric_only=numeric_only,
@@ -2216,6 +2220,7 @@ def mean(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "mean", args, kwargs)
         nv.validate_rolling_func("mean", args, kwargs)
         return super().mean(
             numeric_only=numeric_only,
@@ -2262,6 +2267,7 @@ def median(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "median", None, kwargs)
         return super().median(
             numeric_only=numeric_only,
             engine=engine,
@@ -2325,6 +2331,7 @@ def std(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "std", args, kwargs)
         nv.validate_rolling_func("std", args, kwargs)
         return super().std(
             ddof=ddof,
@@ -2390,6 +2397,7 @@ def var(
         engine_kwargs: dict[str, bool] | None = None,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "var", args, kwargs)
         nv.validate_rolling_func("var", args, kwargs)
         return super().var(
             ddof=ddof,
@@ -2416,6 +2424,7 @@ def var(
         agg_method="skew",
     )
     def skew(self, numeric_only: bool = False, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "skew", None, kwargs)
         return super().skew(numeric_only=numeric_only, **kwargs)
 
     @doc(
@@ -2454,6 +2463,7 @@ def skew(self, numeric_only: bool = False, **kwargs):
         agg_method="sem",
     )
     def sem(self, ddof: int = 1, numeric_only: bool = False, *args, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "sem", args, kwargs)
         nv.validate_rolling_func("sem", args, kwargs)
         # Raise here so error message says sem instead of std
         self._validate_numeric_only("sem", numeric_only)
@@ -2500,6 +2510,7 @@ def sem(self, ddof: int = 1, numeric_only: bool = False, *args, **kwargs):
         agg_method="kurt",
     )
     def kurt(self, numeric_only: bool = False, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "kurt", None, kwargs)
         return super().kurt(numeric_only=numeric_only, **kwargs)
 
     @doc(
@@ -2557,6 +2568,7 @@ def quantile(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "quantile", None, kwargs)
         return super().quantile(
             quantile=quantile,
             interpolation=interpolation,
@@ -2634,6 +2646,7 @@ def rank(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "rank", None, kwargs)
         return super().rank(
             method=method,
             ascending=ascending,
@@ -2680,6 +2693,7 @@ def cov(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "cov", None, kwargs)
         return super().cov(
             other=other,
             pairwise=pairwise,
@@ -2813,6 +2827,7 @@ def corr(
         numeric_only: bool = False,
         **kwargs,
     ):
+        maybe_warn_args_and_kwargs(type(self), "corr", None, kwargs)
         return super().corr(
             other=other,
             pairwise=pairwise,