API: make Day preserve time-of-day across DST transitions

Author: jbrockmendel

doc/source/reference/offset_frequency.rst

@@ -1107,7 +1107,6 @@ Properties
 .. autosummary::
    :toctree: api/
 
-    Day.delta
     Day.freqstr
     Day.kwds
     Day.name

doc/source/user_guide/timedeltas.rst

@@ -63,7 +63,7 @@ Further, operations among the scalars yield another scalar ``Timedelta``.
 
 .. ipython:: python
 
-   pd.Timedelta(pd.offsets.Day(2)) + pd.Timedelta(pd.offsets.Second(2)) + pd.Timedelta(
+   pd.Timedelta(pd.offsets.Hour(48)) + pd.Timedelta(pd.offsets.Second(2)) + pd.Timedelta(
        "00:00:00.000123"
    )
 

pandas/_libs/tslibs/__init__.py

@@ -33,6 +33,7 @@
     "is_supported_unit",
     "npy_unit_to_abbrev",
     "get_supported_reso",
+    "Day",
 ]
 
 from pandas._libs.tslibs import dtypes  # pylint: disable=import-self
@@ -60,6 +61,7 @@
 )
 from pandas._libs.tslibs.offsets import (
     BaseOffset,
+    Day,
     Tick,
     to_offset,
 )

pandas/_libs/tslibs/offsets.pyi

@@ -94,6 +94,7 @@ class BaseOffset:
     @property
     def nanos(self) -> int: ...
     def is_anchored(self) -> bool: ...
+    def _maybe_to_hours(self) -> BaseOffset: ...
 
 def _get_offset(name: str) -> BaseOffset: ...
 
@@ -120,7 +121,9 @@ class Tick(SingleConstructorOffset):
 
 def delta_to_tick(delta: timedelta) -> Tick: ...
 
-class Day(Tick): ...
+class Day(BaseOffset):
+    def _maybe_to_hours(self) -> Hour: ...
+
 class Hour(Tick): ...
 class Minute(Tick): ...
 class Second(Tick): ...

pandas/_libs/tslibs/offsets.pyx

@@ -801,6 +801,11 @@ cdef class BaseOffset:
     def nanos(self):
         raise ValueError(f"{self} is a non-fixed frequency")
 
+    def _maybe_to_hours(self):
+        if not isinstance(self, Day):
+            return self
+        return Hour(self.n * 24)
+
     def is_anchored(self) -> bool:
         # TODO: Does this make sense for the general case?  It would help
         # if there were a canonical docstring for what is_anchored means.
@@ -939,8 +944,6 @@ cdef class Tick(SingleConstructorOffset):
     # Note: Without making this cpdef, we get AttributeError when calling
     #  from __mul__
     cpdef Tick _next_higher_resolution(Tick self):
-        if type(self) is Day:
-            return Hour(self.n * 24)
         if type(self) is Hour:
             return Minute(self.n * 60)
         if type(self) is Minute:
@@ -1099,7 +1102,7 @@ cdef class Tick(SingleConstructorOffset):
         self.normalize = False
 
 
-cdef class Day(Tick):
+cdef class Day(SingleConstructorOffset):
     """
     Offset ``n`` days.
 
@@ -1129,11 +1132,41 @@ cdef class Day(Tick):
     >>> ts + Day(-4)
     Timestamp('2022-12-05 15:00:00')
     """
+    _adjust_dst = True
+    _attributes = tuple(["n", "normalize"])
     _nanos_inc = 24 * 3600 * 1_000_000_000
     _prefix = "D"
     _period_dtype_code = PeriodDtypeCode.D
     _creso = NPY_DATETIMEUNIT.NPY_FR_D
 
+    def __init__(self, n=1, normalize=False):
+        BaseOffset.__init__(self, n)
+        if normalize:
+            # GH#21427
+            raise ValueError(
+                "Day offset with `normalize=True` are not allowed."
+            )
+
+    def is_on_offset(self, dt) -> bool:
+        return True
+
+    @apply_wraps
+    def _apply(self, other):
+        if isinstance(other, Day):
+            # TODO: why isn't this handled in __add__?
+            return Day(self.n + other.n)
+        return other + np.timedelta64(self.n, "D")
+
+    @apply_array_wraps
+    def _apply_array(self, dtarr):
+        return dtarr + np.timedelta64(self.n, "D")
+
+    @cache_readonly
+    def freqstr(self) -> str:
+        if self.n != 1:
+            return str(self.n) + "D"
+        return "D"
+
 
 cdef class Hour(Tick):
     """
@@ -1267,16 +1300,13 @@ cdef class Nano(Tick):
 def delta_to_tick(delta: timedelta) -> Tick:
     if delta.microseconds == 0 and getattr(delta, "nanoseconds", 0) == 0:
         # nanoseconds only for pd.Timedelta
-        if delta.seconds == 0:
-            return Day(delta.days)
+        seconds = delta.days * 86400 + delta.seconds
+        if seconds % 3600 == 0:
+            return Hour(seconds / 3600)
+        elif seconds % 60 == 0:
+            return Minute(seconds / 60)
         else:
-            seconds = delta.days * 86400 + delta.seconds
-            if seconds % 3600 == 0:
-                return Hour(seconds / 3600)
-            elif seconds % 60 == 0:
-                return Minute(seconds / 60)
-            else:
-                return Second(seconds)
+            return Second(seconds)
     else:
         nanos = delta_to_nanoseconds(delta)
         if nanos % 1_000_000 == 0:
@@ -4674,7 +4704,7 @@ cpdef to_offset(freq, bint is_period=False):
     <2 * BusinessDays>
 
     >>> to_offset(pd.Timedelta(days=1))
-    <Day>
+    <24 * Hours>
 
     >>> to_offset(pd.offsets.Hour())
     <Hour>
@@ -4741,7 +4771,7 @@ cpdef to_offset(freq, bint is_period=False):
                     )
                     prefix = c_DEPR_ABBREVS[prefix]
 
-                if prefix in {"D", "h", "min", "s", "ms", "us", "ns"}:
+                if prefix in {"h", "min", "s", "ms", "us", "ns"}:
                     # For these prefixes, we have something like "3h" or
                     #  "2.5min", so we can construct a Timedelta with the
                     #  matching unit and get our offset from delta_to_tick
@@ -4759,6 +4789,12 @@ cpdef to_offset(freq, bint is_period=False):
 
                 if delta is None:
                     delta = offset
+                elif isinstance(delta, Day) and isinstance(offset, Tick):
+                    # e.g. "1D1H" is treated like "25H"
+                    delta = Hour(delta.n * 24) + offset
+                elif isinstance(offset, Day) and isinstance(delta, Tick):
+                    # e.g. "1H1D" is treated like "25H"
+                    delta = delta + Hour(offset.n * 24)
                 else:
                     delta = delta + offset
         except (ValueError, TypeError) as err:

pandas/_libs/tslibs/period.pyx

@@ -118,6 +118,7 @@ from pandas._libs.tslibs.offsets cimport (
 from pandas._libs.tslibs.offsets import (
     INVALID_FREQ_ERR_MSG,
     BDay,
+    Day,
 )
 
 cdef:
@@ -1827,6 +1828,10 @@ cdef class _Period(PeriodMixin):
             # i.e. np.timedelta64("nat")
             return NaT
 
+        if isinstance(other, Day):
+            # Periods are timezone-naive, so we treat Day as Tick-like
+            other = np.timedelta64(other.n, "D")
+
         try:
             inc = delta_to_nanoseconds(other, reso=self._dtype._creso, round_ok=False)
         except ValueError as err:
@@ -1854,7 +1859,7 @@ cdef class _Period(PeriodMixin):
                 return NaT
             return other.__add__(self)
 
-        if is_any_td_scalar(other):
+        if is_any_td_scalar(other) or isinstance(other, Day):
             return self._add_timedeltalike_scalar(other)
         elif is_offset_object(other):
             return self._add_offset(other)

pandas/_libs/tslibs/timedeltas.pyx

@@ -1922,15 +1922,18 @@ class Timedelta(_Timedelta):
 
         from pandas._libs.tslibs.offsets import to_offset
 
-        to_offset(freq).nanos  # raises on non-fixed freq
+        orig = freq
+        # In this context it is sufficiently clear that "D" this means 24H
+        freq = to_offset(freq)._maybe_to_hours()
+        freq.nanos  # raises on non-fixed freq
         unit = delta_to_nanoseconds(to_offset(freq), self._creso)
 
         arr = np.array([self._value], dtype="i8")
         try:
             result = round_nsint64(arr, mode, unit)[0]
         except OverflowError as err:
             raise OutOfBoundsTimedelta(
-                f"Cannot round {self} to freq={freq} without overflow"
+                f"Cannot round {self} to freq={orig} without overflow"
             ) from err
         return Timedelta._from_value_and_reso(result, self._creso)
 

pandas/_libs/tslibs/timestamps.pyx

@@ -1895,7 +1895,8 @@ class Timestamp(_Timestamp):
         cdef:
             int64_t nanos
 
-        freq = to_offset(freq, is_period=False)
+        # In this context it is sufficiently clear that "D" this means 24H
+        freq = to_offset(freq, is_period=False)._maybe_to_hours()
         freq.nanos  # raises on non-fixed freq
         nanos = delta_to_nanoseconds(freq, self._creso)
         if nanos == 0:

pandas/core/arrays/datetimelike.py

@@ -27,6 +27,7 @@
 from pandas._libs.arrays import NDArrayBacked
 from pandas._libs.tslibs import (
     BaseOffset,
+    Day,
     IncompatibleFrequency,
     NaT,
     NaTType,
@@ -897,9 +898,16 @@ def inferred_freq(self) -> str | None:
         if self.ndim != 1:
             return None
         try:
-            return frequencies.infer_freq(self)
+            res = frequencies.infer_freq(self)
         except ValueError:
             return None
+        if self.dtype.kind == "m" and res is not None and res.endswith("D"):
+            # TimedeltaArray freq must be a Tick, so we convert the inferred
+            #  daily freq to hourly.
+            if res == "D":
+                return "24h"
+            res = str(int(res[:-1]) * 24) + "h"
+        return res
 
     @property  # NB: override with cache_readonly in immutable subclasses
     def _resolution_obj(self) -> Resolution | None:
@@ -1040,6 +1048,10 @@ def _get_arithmetic_result_freq(self, other) -> BaseOffset | None:
         elif isinstance(self.freq, Tick):
             # In these cases
             return self.freq
+        elif isinstance(self.freq, Day) and getattr(self, "tz", None) is None:
+            return self.freq
+            # TODO: are there tzaware cases when we can reliably preserve freq?
+            # We have a bunch of tests that seem to think so
         return None
 
     @final
@@ -1139,6 +1151,10 @@ def _sub_datetimelike(self, other: Timestamp | DatetimeArray) -> TimedeltaArray:
         res_m8 = res_values.view(f"timedelta64[{self.unit}]")
 
         new_freq = self._get_arithmetic_result_freq(other)
+        if new_freq is not None:
+            # TODO: are we sure this is right?
+            new_freq = new_freq._maybe_to_hours()
+
         new_freq = cast("Tick | None", new_freq)
         return TimedeltaArray._simple_new(res_m8, dtype=res_m8.dtype, freq=new_freq)
 
@@ -1979,9 +1995,13 @@ def __init__(
         if copy:
             values = values.copy()
         if freq:
+            if values.dtype.kind == "m" and isinstance(freq, Day):
+                raise TypeError("TimedeltaArray freq must be a Tick or None")
             freq = to_offset(freq)
-            if values.dtype.kind == "m" and not isinstance(freq, Tick):
-                raise TypeError("TimedeltaArray/Index freq must be a Tick")
+            if values.dtype.kind == "m":
+                freq = freq._maybe_to_hours()
+                if not isinstance(freq, Tick):
+                    raise TypeError("TimedeltaArray/Index freq must be a Tick")
 
         NDArrayBacked.__init__(self, values=values, dtype=dtype)
         self._freq = freq
@@ -2014,7 +2034,7 @@ def freq(self, value) -> None:
         self._freq = value
 
     @classmethod
-    def _validate_frequency(cls, index, freq, **kwargs):
+    def _validate_frequency(cls, index, freq: BaseOffset, **kwargs):
         """
         Validate that a frequency is compatible with the values of a given
         Datetime Array/Index or Timedelta Array/Index
@@ -2130,6 +2150,10 @@ def _round(self, freq, mode, ambiguous, nonexistent):
         values = self.view("i8")
         values = cast(np.ndarray, values)
         offset = to_offset(freq)
+
+        # In this context it is clear "D" means "24H"
+        offset = offset._maybe_to_hours()
+
         offset.nanos  # raises on non-fixed frequencies
         nanos = delta_to_nanoseconds(offset, self._creso)
         if nanos == 0:
@@ -2210,6 +2234,9 @@ def _with_freq(self, freq) -> Self:
             assert freq == "infer"
             freq = to_offset(self.inferred_freq)
 
+        if self.dtype.kind == "m" and freq is not None:
+            assert isinstance(freq, Tick)
+
         arr = self.view()
         arr._freq = freq
         return arr

pandas/core/arrays/datetimes.py

@@ -451,8 +451,10 @@ def _generate_range(  # type: ignore[override]
                 if end is not None:
                     end = end.tz_localize(None)
 
-            if isinstance(freq, Tick):
-                i8values = generate_regular_range(start, end, periods, freq, unit=unit)
+            if isinstance(freq, Tick) or (tz is None and isinstance(freq, Day)):
+                i8values = generate_regular_range(
+                    start, end, periods, freq._maybe_to_hours(), unit=unit
+                )
             else:
                 xdr = _generate_range(
                     start=start, end=end, periods=periods, offset=freq, unit=unit
@@ -899,7 +901,14 @@ def tz_convert(self, tz) -> Self:
 
         # No conversion since timestamps are all UTC to begin with
         dtype = tz_to_dtype(tz, unit=self.unit)
-        return self._simple_new(self._ndarray, dtype=dtype, freq=self.freq)
+        new_freq = self.freq
+        if self.freq is not None and self.freq._adjust_dst:
+            # TODO: in some cases we may be able to retain, e.g. if old and new
+            # tz are both fixed offsets, or if no DST-crossings occur.
+            # The latter is value-dependent behavior that we may want to avoid.
+            # Or could convert e.g. "D" to "24h", see GH#51716
+            new_freq = None
+        return self._simple_new(self._ndarray, dtype=dtype, freq=new_freq)
 
     @dtl.ravel_compat
     def tz_localize(