REF: move more freq management from DatetimeArray/TimedeltaArray to Index (GH#24566) (#65266)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

pandas/core/arrays/datetimelike.py

@@ -52,7 +52,6 @@
     round_nsint64,
 )
 from pandas._libs.tslibs.np_datetime import compare_mismatched_resolutions
-from pandas._libs.tslibs.offsets import FY5253Mixin
 from pandas._libs.tslibs.timedeltas import get_unit_for_round
 from pandas._libs.tslibs.timestamps import integer_op_not_supported
 from pandas._typing import (
@@ -495,10 +494,6 @@ def view(self, dtype: Dtype | None = None) -> ArrayLike:
         #  are present in this file.
         return super().view(dtype)
 
-    def _putmask(self, mask: npt.NDArray[np.bool_], value) -> None:
-        super()._putmask(mask, value)
-        self._freq = None  # GH#24555
-
     # ------------------------------------------------------------------
     # Validation Methods
     # TODO: try to de-duplicate these, ensure identical behavior
@@ -1861,64 +1856,6 @@ def freq(self, value) -> None:
 
         self._freq = value
 
-    @final
-    def _maybe_pin_freq(self, freq, validate_kwds: dict) -> None:
-        """
-        Constructor helper to pin the appropriate `freq` attribute.  Assumes
-        that self._freq is currently set to any freq inferred from input data.
-        """
-        if freq is None:
-            # user explicitly passed None -> override any inferred_freq
-            self._freq = None
-        elif freq == "infer":
-            # if self._freq is *not* None then we already inferred a freq
-            #  and there is nothing left to do
-            if self._freq is None:
-                # Set _freq directly to bypass duplicative _validate_frequency
-                # check.
-                self._freq = to_offset(self.inferred_freq)  # type: ignore[assignment]
-        elif freq is lib.no_default:
-            # user did not specify anything, keep inferred freq if the original
-            #  data had one, otherwise do nothing
-            pass
-        elif self._freq is None:
-            # We cannot inherit a freq from the data, so we need to validate
-            #  the user-passed freq
-            freq = to_offset(freq)
-            type(self)._validate_frequency(self, freq, **validate_kwds)
-            self._freq = freq
-        else:
-            # Otherwise we just need to check that the user-passed freq
-            #  doesn't conflict with the one we already have.
-            freq = to_offset(freq)
-            if freq != self._freq:
-                # GH#61086 freq may be equivalent but not equal (e.g.
-                # QS-FEB vs QS-MAY), so validate against the actual data.
-                if len(self) == 0:
-                    pass
-                elif len(self) == 1:
-                    if not freq.is_on_offset(self[0]):
-                        raise ValueError(
-                            f"Inferred frequency {self._freq} from passed "
-                            "values does not conform to passed frequency "
-                            f"{freq.freqstr}"
-                        )
-                elif self[0] + freq == self[1]:
-                    # For standard offsets, the step is a deterministic
-                    # function of the date, so agreement on one step proves
-                    # equivalence. For Custom/FY5253 offsets, external
-                    # state (holidays, 52/53-week patterns) could cause
-                    # later steps to diverge, so we validate fully.
-                    if hasattr(freq, "_holidays") or isinstance(freq, FY5253Mixin):
-                        type(self)._validate_frequency(self, freq, **validate_kwds)
-                else:
-                    raise ValueError(
-                        f"Inferred frequency {self._freq} from passed "
-                        "values does not conform to passed frequency "
-                        f"{freq.freqstr}"
-                    )
-            self._freq = freq
-
     @final
     @classmethod
     def _validate_frequency(cls, index, freq: BaseOffset, **kwargs) -> None:

pandas/core/arrays/datetimes.py

@@ -1264,7 +1264,7 @@ def to_period(self, freq=None) -> PeriodArray:
             )
 
         if freq is None:
-            freq = self.freqstr or self.inferred_freq
+            freq = self.inferred_freq
 
             if freq is None:
                 raise ValueError(

pandas/core/indexes/datetimelike.py

@@ -38,6 +38,7 @@
     to_offset,
 )
 from pandas._libs.tslibs.dtypes import abbrev_to_npy_unit
+from pandas._libs.tslibs.offsets import FY5253Mixin
 from pandas.compat.numpy import function as nv
 from pandas.errors import (
     InvalidIndexError,
@@ -682,6 +683,72 @@ def astype(self, dtype, copy: bool = True):
             result._data._freq = self.freq
         return result
 
+    def putmask(self, mask, value) -> Index:
+        # GH#24555 putmask may modify values out-of-sequence; drop freq
+        result = super().putmask(mask, value)
+        if isinstance(result, type(self)):
+            result._data._freq = None
+        return result
+
+    def _pin_freq(self, freq, validate_kwds: dict) -> None:
+        """
+        Constructor helper to pin the appropriate ``freq`` attribute on
+        ``self._data``.  Assumes ``self._data._freq`` is currently set to any
+        freq inferred from input data.
+        """
+        arr = self._data
+        if freq is None:
+            # user explicitly passed None -> override any inferred_freq
+            arr._freq = None
+        elif freq == "infer":
+            # if arr._freq is *not* None then we already inferred a freq
+            #  and there is nothing left to do
+            if arr._freq is None:
+                # Set _freq directly to bypass duplicative _validate_frequency
+                # check.
+                arr._freq = to_offset(self.inferred_freq)
+        elif freq is lib.no_default:
+            # user did not specify anything, keep inferred freq if the original
+            #  data had one, otherwise do nothing
+            pass
+        elif arr._freq is None:
+            # We cannot inherit a freq from the data, so we need to validate
+            #  the user-passed freq
+            freq = to_offset(freq)
+            type(arr)._validate_frequency(self, freq, **validate_kwds)
+            arr._freq = freq
+        else:
+            # Otherwise we just need to check that the user-passed freq
+            #  doesn't conflict with the one we already have.
+            freq = to_offset(freq)
+            if freq != arr._freq:
+                # GH#61086 freq may be equivalent but not equal (e.g.
+                # QS-FEB vs QS-MAY), so validate against the actual data.
+                if len(self) == 0:
+                    pass
+                elif len(self) == 1:
+                    if not freq.is_on_offset(self[0]):
+                        raise ValueError(
+                            f"Inferred frequency {arr._freq} from passed "
+                            "values does not conform to passed frequency "
+                            f"{freq.freqstr}"
+                        )
+                elif self[0] + freq == self[1]:
+                    # For standard offsets, the step is a deterministic
+                    # function of the date, so agreement on one step proves
+                    # equivalence. For Custom/FY5253 offsets, external
+                    # state (holidays, 52/53-week patterns) could cause
+                    # later steps to diverge, so we validate fully.
+                    if hasattr(freq, "_holidays") or isinstance(freq, FY5253Mixin):
+                        type(arr)._validate_frequency(self, freq, **validate_kwds)
+                else:
+                    raise ValueError(
+                        f"Inferred frequency {arr._freq} from passed "
+                        "values does not conform to passed frequency "
+                        f"{freq.freqstr}"
+                    )
+            arr._freq = freq
+
     def _get_arithmetic_result_freq(self, other) -> BaseOffset | None:
         """
         Check if we can preserve self.freq in addition or subtraction.
@@ -850,13 +917,10 @@ def as_unit(self, unit: TimeUnit) -> Self:
 
     def _with_freq(self, freq):
         # GH#29843
-        if freq is None:
-            # Always valid
+        if freq is None or (len(self) == 0 and isinstance(freq, BaseOffset)):
+            # None is always valid. For offsets on empty index the array's
+            # _with_freq below performs the m-dtype Tick validation.
             pass
-        elif len(self) == 0 and isinstance(freq, BaseOffset):
-            # Always valid.  In the TimedeltaArray case, we require a Tick offset
-            if self.dtype.kind == "m" and not isinstance(freq, (Tick, Day)):
-                raise TypeError("TimedeltaArray/Index freq must be a Tick")
         else:
             # As an internal method, we can ensure this assertion always holds
             assert freq == "infer"
@@ -1231,9 +1295,6 @@ def _get_getitem_freq(self, key) -> BaseOffset | None:
         """
         Find the `freq` attribute to assign to the result of a __getitem__ lookup.
         """
-        if self.ndim != 1:
-            return None
-
         key = check_array_indexer(self._data, key)  # maybe ndarray[bool] -> slice
         freq = None
         if isinstance(key, slice):

pandas/core/indexes/datetimes.py

@@ -922,13 +922,13 @@ def __new__(
 
         if inferred_freq is not None:
             dtarr._freq = inferred_freq
-        dtarr._maybe_pin_freq(freq, {"ambiguous": ambiguous})
 
         refs = None
         if not copy and isinstance(data, (Index, ABCSeries)):
             refs = data._references
 
         subarr = cls._simple_new(dtarr, name=name, refs=refs)
+        subarr._pin_freq(freq, {"ambiguous": ambiguous})
         return subarr
 
     # --------------------------------------------------------------------

pandas/core/indexes/timedeltas.py

@@ -208,12 +208,13 @@ def __new__(
         # - Cases checked above all return/raise before reaching here - #
 
         tdarr = TimedeltaArray._from_sequence(data, dtype=dtype, copy=copy)
-        tdarr._maybe_pin_freq(freq, {})
         refs = None
         if not copy and isinstance(data, (ABCSeries, Index)):
             refs = data._references
 
-        return cls._simple_new(tdarr, name=name, refs=refs)
+        result = cls._simple_new(tdarr, name=name, refs=refs)
+        result._pin_freq(freq, {})
+        return result
 
     # -------------------------------------------------------------------
 

pandas/tests/arrays/test_datetimelike.py

@@ -1109,7 +1109,7 @@ def test_to_timestamp(self, how, arr1d):
     def test_to_timestamp_roundtrip_bday(self):
         # Case where infer_freq inside would choose "D" instead of "B"
         dta = pd.date_range("2021-10-18", periods=3, freq="B", unit="ns")._data
-        parr = dta.to_period()
+        parr = dta.to_period("B")
         result = parr.to_timestamp()
         assert result.freq == "B"
         tm.assert_extension_array_equal(result, dta.as_unit("us"))