Rework deprecation around future.infer_freq_returns_offset option

Mirror the GH#55504 inferred_freq pattern: respect the option to opt in
to (or out of) the future BaseOffset behavior, only warn when inference
succeeds, fix the migration advice (DatetimeIndex(ser).freq is always
None now that arrays carry no freq), and add dedicated tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: jbrockmendel

doc/source/whatsnew/v3.1.0.rst

@@ -104,7 +104,7 @@ Other API changes
 
 Deprecations
 ~~~~~~~~~~~~
-- Deprecated :attr:`Series.dt.freq` returning a string. In a future version, this will return a :class:`DateOffset` object (or ``None``) to match :attr:`DatetimeIndex.freq` (:issue:`64701`)
+- Deprecated :attr:`Series.dt.freq` returning a string; in a future version this will return a :class:`BaseOffset` instead. Use ``pd.set_option('future.infer_freq_returns_offset', True)`` to opt in to the future behavior (:issue:`64701`)
 - Deprecated :attr:`Timestamp.dayofweek`, :attr:`Timestamp.dayofyear`, :attr:`Timestamp.daysinmonth` in favor of :attr:`Timestamp.day_of_week`, :attr:`Timestamp.day_of_year`, :attr:`Timestamp.days_in_month`, respectively. The same deprecation applies to the corresponding attributes on :class:`Period`, :class:`DatetimeIndex`, :class:`PeriodIndex`, and :attr:`Series.dt` (:issue:`46768`)
 - Deprecated :func:`infer_freq`, :attr:`DatetimeIndex.inferred_freq`, and :attr:`TimedeltaIndex.inferred_freq` returning a string; in a future version these will return a :class:`BaseOffset` instead. Use ``pd.set_option('future.infer_freq_returns_offset', True)`` to opt in to the future behavior (:issue:`55504`)
 - Deprecated :func:`set_eng_float_format`. Use ``pd.set_option("display.precision", N)`` to control decimal precision, or pass a custom callable to ``pd.set_option("display.float_format", func)`` (:issue:`64460`)

pandas/conftest.py

@@ -214,7 +214,10 @@ def pytest_collection_modifyitems(items, config) -> None:
         ("read_parquet", "Passing a BlockManager to DataFrame is deprecated"),
         ("Timestamp.utcfromtimestamp", "Timestamp.utcfromtimestamp is deprecated"),
         ("BaseOffset.name.__get__", "The 'name' property is deprecated"),
-        ("DatetimeProperties.freq", "The behavior of Series.dt.freq is deprecated"),
+        (
+            "DatetimeProperties.freq",
+            "A future version of pandas will return a BaseOffset",
+        ),
     ]
 
     if is_doctest:

pandas/core/indexes/accessors.py

@@ -13,7 +13,10 @@
 
 import numpy as np
 
+from pandas._config import using_infer_freq_offset
+
 from pandas._libs import lib
+from pandas._libs.tslibs import to_offset
 from pandas.errors import Pandas4Warning
 from pandas.util._exceptions import find_stack_level
 
@@ -377,12 +380,13 @@ def freq(self):
         """
         Return a string representing a frequency generated by infer_freq.
 
+        Returns None if it can't autodetect the frequency.
+
         .. deprecated:: 3.1.0
-            The behavior of :attr:`Series.dt.freq` is deprecated. In a future
-            version, this will return the frequency as a :class:`DateOffset`
-            object (or ``None``) instead of as a string. To get the future
-            behavior, use ``Series.dt.freq`` on a Series backed by a
-            :class:`DatetimeIndex` with a set frequency.
+            A future version of pandas will return a :class:`BaseOffset`
+            object (or ``None``) instead of a string. Use
+            ``pd.set_option('future.infer_freq_returns_offset', True)`` to
+            opt in to the future behavior.
 
         See Also
         --------
@@ -401,16 +405,23 @@ def freq(self):
         >>> ser.dt.freq
         '2YS-JAN'
         """
-        warnings.warn(
-            "The behavior of Series.dt.freq is deprecated. "
-            "In a future version, this will return the frequency as a "
-            "DateOffset object (or None) instead of as a string. "
-            "To silence this warning, use "
-            "DatetimeIndex(ser).freq instead of ser.dt.freq",
-            Pandas4Warning,
-            stacklevel=find_stack_level(),
-        )
-        return self._get_values()._inferred_freq_str
+        result = self._get_values()._inferred_freq_str
+        if result is not None:
+            opt = using_infer_freq_offset()
+            if opt is True:
+                return to_offset(result)
+            if opt is None:
+                warnings.warn(
+                    "A future version of pandas will return a BaseOffset "
+                    "object instead of a string from Series.dt.freq. "
+                    "Use pd.set_option("
+                    "'future.infer_freq_returns_offset', True) "
+                    "to get the future behavior, or set to False to keep the "
+                    "old behavior and silence this warning.",
+                    Pandas4Warning,
+                    stacklevel=find_stack_level(),
+                )
+        return result
 
     def isocalendar(self) -> DataFrame:
         """
@@ -570,16 +581,23 @@ def components(self) -> DataFrame:
 
     @property
     def freq(self):
-        warnings.warn(
-            "The behavior of Series.dt.freq is deprecated. "
-            "In a future version, this will return the frequency as a "
-            "DateOffset object (or None) instead of as a string. "
-            "To silence this warning, use "
-            "TimedeltaIndex(ser).freq instead of ser.dt.freq",
-            Pandas4Warning,
-            stacklevel=find_stack_level(),
-        )
-        return self._get_values()._inferred_freq_str
+        result = self._get_values()._inferred_freq_str
+        if result is not None:
+            opt = using_infer_freq_offset()
+            if opt is True:
+                return to_offset(result)
+            if opt is None:
+                warnings.warn(
+                    "A future version of pandas will return a BaseOffset "
+                    "object instead of a string from Series.dt.freq. "
+                    "Use pd.set_option("
+                    "'future.infer_freq_returns_offset', True) "
+                    "to get the future behavior, or set to False to keep the "
+                    "old behavior and silence this warning.",
+                    Pandas4Warning,
+                    stacklevel=find_stack_level(),
+                )
+        return result
 
 
 @delegate_names(

pandas/tests/series/accessors/test_dt_accessor.py

@@ -131,7 +131,7 @@ def test_dt_namespace_accessor_datetime64(self, freq):
 
         tz_result = result.dt.tz
         assert str(tz_result) == "US/Eastern"
-        msg = "The behavior of Series.dt.freq is deprecated"
+        msg = "A future version of pandas will return a BaseOffset"
         with tm.assert_produces_warning(Pandas4Warning, match=msg):
             freq_result = ser.dt.freq
         assert freq_result == DatetimeIndex(ser.values, freq="infer").freq
@@ -170,7 +170,7 @@ def test_dt_namespace_accessor_datetime64tz(self):
 
         tz_result = result.dt.tz
         assert str(tz_result) == "CET"
-        msg = "The behavior of Series.dt.freq is deprecated"
+        msg = "A future version of pandas will return a BaseOffset"
         with tm.assert_produces_warning(Pandas4Warning, match=msg):
             freq_result = ser.dt.freq
         assert freq_result == DatetimeIndex(ser.values, freq="infer").freq
@@ -213,7 +213,7 @@ def test_dt_namespace_accessor_timedelta(self):
             assert isinstance(result, Series)
             assert result.dtype == "float64"
 
-            msg = "The behavior of Series.dt.freq is deprecated"
+            msg = "A future version of pandas will return a BaseOffset"
             with tm.assert_produces_warning(Pandas4Warning, match=msg):
                 freq_result = ser.dt.freq
             assert freq_result == TimedeltaIndex(ser.values, freq="infer").freq
@@ -885,3 +885,35 @@ def test_day_attribute_non_nano_beyond_int32():
     result = ser.dt.days
     expected = Series([1579371003, 1559453522, 2839645203, 2586, 27, 42066, 0])
     tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ser",
+    [
+        Series(date_range("2020-01-01", periods=3)),
+        Series(timedelta_range("1 day", periods=3)),
+    ],
+)
+def test_dt_freq_deprecated(ser):
+    # GH#64701
+    msg = "A future version of pandas will return a BaseOffset"
+    with tm.assert_produces_warning(Pandas4Warning, match=msg):
+        result = ser.dt.freq
+    assert result == "D"
+
+    with pd.option_context("future.infer_freq_returns_offset", True):
+        with tm.assert_produces_warning(None):
+            result = ser.dt.freq
+    assert result == pd.offsets.Day()
+
+    with pd.option_context("future.infer_freq_returns_offset", False):
+        with tm.assert_produces_warning(None):
+            result = ser.dt.freq
+    assert result == "D"
+
+
+def test_dt_freq_no_warning_when_unable_to_infer():
+    # GH#64701 - no behavior change when the result is None, so no warning
+    ser = Series(pd.to_datetime(["2020-01-01", "2020-03-07", "2020-08-15"]))
+    with tm.assert_produces_warning(None):
+        assert ser.dt.freq is None