BUG: fix stacklevel munging for deprecation warnings of .resample()

Added a utility class (a context manager), check_deprecated_resample_kwargs,
that sets the correct stacklevel and ensures that within the with statement,
the warnings are emitted at most once. See the docstring for more info.

Author: plammens

pandas/core/frame.py

@@ -9140,20 +9140,23 @@ def resample(
         origin: Union[str, "TimestampConvertibleTypes"] = "start_day",
         offset: Optional["TimedeltaConvertibleTypes"] = None,
     ) -> "Resampler":
-        return super().resample(
-            rule=rule,
-            axis=axis,
-            closed=closed,
-            label=label,
-            convention=convention,
-            kind=kind,
-            loffset=loffset,
-            base=base,
-            on=on,
-            level=level,
-            origin=origin,
-            offset=offset,
-        )
+        from pandas.core.resample import check_deprecated_resample_kwargs
+
+        with check_deprecated_resample_kwargs(dict(base=base, loffset=loffset)):
+            return super().resample(
+                rule=rule,
+                axis=axis,
+                closed=closed,
+                label=label,
+                convention=convention,
+                kind=kind,
+                loffset=loffset,
+                base=base,
+                on=on,
+                level=level,
+                origin=origin,
+                offset=offset,
+            )
 
     def to_timestamp(
         self, freq=None, how: str = "start", axis: Axis = 0, copy: bool = True

pandas/core/generic.py

@@ -8171,24 +8171,25 @@ def resample(
         2000-10-02 00:41:00    24
         Freq: 17T, dtype: int64
         """
-        from pandas.core.resample import get_resampler
+        from pandas.core.resample import check_deprecated_resample_kwargs, get_resampler
 
-        axis = self._get_axis_number(axis)
-        return get_resampler(
-            self,
-            freq=rule,
-            label=label,
-            closed=closed,
-            axis=axis,
-            kind=kind,
-            loffset=loffset,
-            convention=convention,
-            base=base,
-            key=on,
-            level=level,
-            origin=origin,
-            offset=offset,
-        )
+        with check_deprecated_resample_kwargs(dict(base=base, loffset=loffset)):
+            axis = self._get_axis_number(axis)
+            return get_resampler(
+                self,
+                freq=rule,
+                label=label,
+                closed=closed,
+                axis=axis,
+                kind=kind,
+                loffset=loffset,
+                convention=convention,
+                base=base,
+                key=on,
+                level=level,
+                origin=origin,
+                offset=offset,
+            )
 
     def first(self: FrameOrSeries, offset) -> FrameOrSeries:
         """

pandas/core/groupby/groupby.py

@@ -1796,9 +1796,13 @@ def resample(self, rule, *args, **kwargs):
             2000-01-01 00:03:00  0  2
         5   2000-01-01 00:03:00  5  1
         """
-        from pandas.core.resample import get_resampler_for_grouping
+        from pandas.core.resample import (
+            check_deprecated_resample_kwargs,
+            get_resampler_for_grouping,
+        )
 
-        return get_resampler_for_grouping(self, rule, *args, **kwargs)
+        with check_deprecated_resample_kwargs(kwargs):
+            return get_resampler_for_grouping(self, rule, *args, **kwargs)
 
     @Substitution(name="groupby")
     @Appender(_common_see_also)

pandas/core/groupby/grouper.py

@@ -3,7 +3,6 @@
 split-apply-combine paradigm.
 """
 from typing import Dict, Hashable, List, Optional, Tuple
-import warnings
 
 import numpy as np
 
@@ -228,43 +227,8 @@ def __new__(cls, *args, **kwargs):
         if kwargs.get("freq") is not None:
             from pandas.core.resample import TimeGrouper
 
-            # Deprecation warning of `base` and `loffset` since v1.1.0:
-            # we are raising the warning here to be able to set the `stacklevel`
-            # properly since we need to raise the `base` and `loffset` deprecation
-            # warning from three different cases:
-            #   core/generic.py::NDFrame.resample
-            #   core/groupby/groupby.py::GroupBy.resample
-            #   core/groupby/grouper.py::Grouper
-            # raising these warnings from TimeGrouper directly would fail the test:
-            #   tests/resample/test_deprecated.py::test_deprecating_on_loffset_and_base
-            # hacky way to set the stacklevel: if cls is TimeGrouper it means
-            # that the call comes from a pandas internal call of resample,
-            # otherwise it comes from pd.Grouper
-            stacklevel = 4 if cls is TimeGrouper else 2
-            if kwargs.get("base", None) is not None:
-                warnings.warn(
-                    "'base' in .resample() and in Grouper() is deprecated.\n"
-                    "The new arguments that you should use are 'offset' or 'origin'.\n"
-                    '\n>>> df.resample(freq="3s", base=2)\n'
-                    "\nbecomes:\n"
-                    '\n>>> df.resample(freq="3s", offset="2s")\n',
-                    FutureWarning,
-                    stacklevel=stacklevel,
-                )
-
-            if kwargs.get("loffset", None) is not None:
-                warnings.warn(
-                    "'loffset' in .resample() and in Grouper() is deprecated.\n"
-                    '\n>>> df.resample(freq="3s", loffset="8H")\n'
-                    "\nbecomes:\n"
-                    "\n>>> from pandas.tseries.frequencies import to_offset"
-                    '\n>>> df = df.resample(freq="3s").mean()'
-                    '\n>>> df.index = df.index.to_timestamp() + to_offset("8H")\n',
-                    FutureWarning,
-                    stacklevel=stacklevel,
-                )
-
             cls = TimeGrouper
+
         return super().__new__(cls)
 
     def __init__(

pandas/core/resample.py

@@ -2,6 +2,7 @@
 from datetime import timedelta
 from textwrap import dedent
 from typing import Dict, Optional, Union, no_type_check
+import warnings
 
 import numpy as np
 
@@ -17,6 +18,7 @@
 from pandas._typing import TimedeltaConvertibleTypes, TimestampConvertibleTypes
 from pandas.compat.numpy import function as nv
 from pandas.errors import AbstractMethodError
+from pandas.util._call_once import call_once
 from pandas.util._decorators import Appender, Substitution, doc
 
 from pandas.core.dtypes.generic import ABCDataFrame, ABCSeries
@@ -1333,6 +1335,9 @@ def __init__(
         offset: Optional[TimedeltaConvertibleTypes] = None,
         **kwargs,
     ):
+        with check_deprecated_resample_kwargs(dict(base=base, loffset=loffset)):
+            pass
+
         # Check for correctness of the keyword arguments which would
         # otherwise silently use the default if misspelled
         if label not in {None, "left", "right"}:
@@ -1657,7 +1662,6 @@ def _get_period_bins(self, ax: PeriodIndex):
 
 
 def _take_new_index(obj, indexer, new_index, axis=0):
-
     if isinstance(obj, ABCSeries):
         new_values = algos.take_1d(obj._values, indexer)
         return obj._constructor(new_values, index=new_index, name=obj.name)
@@ -1913,3 +1917,54 @@ def _asfreq_compat(index, freq):
     else:
         new_index = Index([], dtype=index.dtype, freq=freq, name=index.name)
     return new_index
+
+
+def check_deprecated_resample_kwargs(kwargs, stacklevel=2):
+    """
+    Utility function to emit the deprecation warnings of `base` and `loffset` (v1.1.0).
+
+    Its purpose is to allow passing `test_deprecating_on_loffset_and_base` without any
+    hacky manipulation of ``stacklevel`` (see L231-L266 of pandas.core.groupby.grouper
+    at commit 4a267c69).
+
+    Uses a :class:`pandas.util._call_once.CallOnceContextManager`. This idempotent
+    context manager ensures that only the outermost instance (which has the correct
+    value for stacklevel) is the one to emit the warnings when it is entered.
+
+    Parameters
+    ----------
+    kwargs
+        Kewyword arguments dict to check.
+    stacklevel
+        The ``stacklevel`` of warnings from the perspective of the caller.
+
+    Returns
+    -------
+    A :class:`pandas.util._call_once.CallOnceContextManager` instance.
+    """
+    stacklevel += 2  # one for __enter__() and one for callback()
+
+    def callback():
+        if kwargs.get("base", None) is not None:
+            warnings.warn(
+                "'base' in .resample() and in Grouper() is deprecated.\n"
+                "The new arguments that you should use are 'offset' or 'origin'.\n"
+                '\n>>> df.resample(freq="3s", base=2)\n'
+                "\nbecomes:\n"
+                '\n>>> df.resample(freq="3s", offset="2s")\n',
+                FutureWarning,
+                stacklevel=stacklevel,
+            )
+        if kwargs.get("loffset", None) is not None:
+            warnings.warn(
+                "'loffset' in .resample() and in Grouper() is deprecated.\n"
+                '\n>>> df.resample(freq="3s", loffset="8H")\n'
+                "\nbecomes:\n"
+                "\n>>> from pandas.tseries.frequencies import to_offset"
+                '\n>>> df = df.resample(freq="3s").mean()'
+                '\n>>> df.index = df.index.to_timestamp() + to_offset("8H")\n',
+                FutureWarning,
+                stacklevel=stacklevel,
+            )
+
+    return call_once(callback, key="check_deprecated_resample_kwargs")

pandas/core/series.py

@@ -4957,20 +4957,23 @@ def resample(
         origin: Union[str, "TimestampConvertibleTypes"] = "start_day",
         offset: Optional["TimedeltaConvertibleTypes"] = None,
     ) -> "Resampler":
-        return super().resample(
-            rule=rule,
-            axis=axis,
-            closed=closed,
-            label=label,
-            convention=convention,
-            kind=kind,
-            loffset=loffset,
-            base=base,
-            on=on,
-            level=level,
-            origin=origin,
-            offset=offset,
-        )
+        from pandas.core.resample import check_deprecated_resample_kwargs
+
+        with check_deprecated_resample_kwargs(dict(base=base, loffset=loffset)):
+            return super().resample(
+                rule=rule,
+                axis=axis,
+                closed=closed,
+                label=label,
+                convention=convention,
+                kind=kind,
+                loffset=loffset,
+                base=base,
+                on=on,
+                level=level,
+                origin=origin,
+                offset=offset,
+            )
 
     def to_timestamp(self, freq=None, how="start", copy=True) -> "Series":
         """