From 80783821b83b9e9ce95a17822687ea5c0fc2f9b0 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Tue, 30 Sep 2025 12:39:53 +0100 Subject: [PATCH 1/8] type `freq` in `shift`, consistently use `Frequency` alias --- pandas-stubs/_libs/tslibs/period.pyi | 9 +++++---- pandas-stubs/_libs/tslibs/timedeltas.pyi | 8 ++++---- pandas-stubs/core/frame.pyi | 5 +++-- pandas-stubs/core/indexes/accessors.pyi | 22 ++++++++++------------ pandas-stubs/core/indexes/datetimes.pyi | 14 ++++++-------- pandas-stubs/core/indexes/interval.pyi | 10 +++++----- pandas-stubs/core/indexes/timedeltas.pyi | 15 ++++++++------- pandas-stubs/core/series.pyi | 5 +++-- 8 files changed, 44 insertions(+), 44 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/period.pyi b/pandas-stubs/_libs/tslibs/period.pyi index a43d57407..c95f754ca 100644 --- a/pandas-stubs/_libs/tslibs/period.pyi +++ b/pandas-stubs/_libs/tslibs/period.pyi @@ -21,6 +21,7 @@ from pandas._libs.tslibs import NaTType from pandas._libs.tslibs.offsets import BaseOffset from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( + Frequency, ShapeT, np_1darray, np_ndarray, @@ -65,7 +66,7 @@ class Period(PeriodMixin): value: ( Period | str | datetime.datetime | datetime.date | Timestamp | None ) = ..., - freq: str | BaseOffset | None = ..., + freq: Frequency | None = ..., ordinal: int | None = ..., year: int | None = ..., month: int | None = ..., @@ -229,12 +230,12 @@ class Period(PeriodMixin): def day_of_year(self) -> int: ... @property def day_of_week(self) -> int: ... - def asfreq(self, freq: str | BaseOffset, how: _PeriodFreqHow = "end") -> Period: ... + def asfreq(self, freq: Frequency, how: _PeriodFreqHow = "end") -> Period: ... @classmethod - def now(cls, freq: str | BaseOffset = ...) -> Period: ... + def now(cls, freq: Frequency = ...) -> Period: ... def strftime(self, fmt: str) -> str: ... def to_timestamp( self, - freq: str | BaseOffset | None = ..., + freq: Frequency | None = ..., how: _PeriodToTimestampHow = "S", ) -> Timestamp: ... diff --git a/pandas-stubs/_libs/tslibs/timedeltas.pyi b/pandas-stubs/_libs/tslibs/timedeltas.pyi index 9ad5e0e68..4fde3b7eb 100644 --- a/pandas-stubs/_libs/tslibs/timedeltas.pyi +++ b/pandas-stubs/_libs/tslibs/timedeltas.pyi @@ -23,12 +23,12 @@ from typing_extensions import ( ) from pandas._libs.tslibs import ( - BaseOffset, NaTType, ) from pandas._libs.tslibs.period import Period from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( + Frequency, ShapeT, TimeUnit, np_1darray, @@ -130,9 +130,9 @@ class Timedelta(timedelta): @property def asm8(self) -> np.timedelta64: ... # TODO: round/floor/ceil could return NaT? - def round(self, freq: str | BaseOffset) -> Self: ... - def floor(self, freq: str | BaseOffset) -> Self: ... - def ceil(self, freq: str | BaseOffset) -> Self: ... + def round(self, freq: Frequency) -> Self: ... + def floor(self, freq: Frequency) -> Self: ... + def ceil(self, freq: Frequency) -> Self: ... @property def resolution_string(self) -> str: ... # Override due to more types supported than dt.timedelta diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi index ce61a30f1..7709a2ef6 100644 --- a/pandas-stubs/core/frame.pyi +++ b/pandas-stubs/core/frame.pyi @@ -106,6 +106,7 @@ from pandas._typing import ( FillnaOptions, FloatFormatType, FormattersType, + Frequency, GroupByObjectNonScalar, HashableT, HashableT1, @@ -2341,7 +2342,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): @overload def rolling( self, - window: int | str | dt.timedelta | BaseOffset | BaseIndexer, + window: int | Frequency | dt.timedelta | BaseIndexer, min_periods: int | None = ..., center: _bool = ..., on: Hashable | None = ..., @@ -2355,7 +2356,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): @overload def rolling( self, - window: int | str | dt.timedelta | BaseOffset | BaseIndexer, + window: int | Frequency | dt.timedelta | BaseIndexer, min_periods: int | None = ..., center: _bool = ..., on: Hashable | None = ..., diff --git a/pandas-stubs/core/indexes/accessors.pyi b/pandas-stubs/core/indexes/accessors.pyi index a9a5f8a54..4e5d48b26 100644 --- a/pandas-stubs/core/indexes/accessors.pyi +++ b/pandas-stubs/core/indexes/accessors.pyi @@ -33,10 +33,10 @@ from pandas.core.series import ( from typing_extensions import Never from pandas._libs.tslibs import BaseOffset -from pandas._libs.tslibs.offsets import DateOffset from pandas._libs.tslibs.period import Period from pandas._typing import ( S1, + Frequency, TimeAmbiguous, TimeNonexistent, TimestampConvention, @@ -174,7 +174,7 @@ _DTTimestampTimedeltaReturnType = TypeVar( class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]): def round( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] @@ -184,7 +184,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]): ) -> _DTTimestampTimedeltaReturnType: ... def floor( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] @@ -194,7 +194,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]): ) -> _DTTimestampTimedeltaReturnType: ... def ceil( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] @@ -220,9 +220,7 @@ class _DatetimeLikeNoTZMethods( _DTToPeriodReturnType, ], ): - def to_period( - self, freq: str | BaseOffset | None = ... - ) -> _DTToPeriodReturnType: ... + def to_period(self, freq: Frequency | None = ...) -> _DTToPeriodReturnType: ... def tz_localize( self, tz: TimeZones, @@ -353,12 +351,12 @@ class _PeriodProperties( def strftime(self, date_format: str) -> _PeriodStrReturnTypes: ... def to_timestamp( self, - freq: str | DateOffset | None = ..., + freq: Frequency | None = ..., how: TimestampConvention = ..., ) -> _PeriodDTAReturnTypes: ... def asfreq( self, - freq: str | DateOffset | None = ..., + freq: Frequency | None = ..., how: Literal["E", "END", "FINISH", "S", "START", "BEGIN"] = ..., ) -> _PeriodPAReturnTypes: ... @@ -453,7 +451,7 @@ class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]): ) -> CombinedDatetimelikeProperties: ... def round( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] @@ -463,7 +461,7 @@ class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]): ) -> Series[S1]: ... def floor( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] @@ -473,7 +471,7 @@ class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]): ) -> Series[S1]: ... def ceil( self, - freq: str | BaseOffset | None, + freq: Frequency | None, ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ..., nonexistent: ( Literal["shift_forward", "shift_backward", "NaT", "raise"] diff --git a/pandas-stubs/core/indexes/datetimes.pyi b/pandas-stubs/core/indexes/datetimes.pyi index 42b2f2d4d..417a2bcdb 100644 --- a/pandas-stubs/core/indexes/datetimes.pyi +++ b/pandas-stubs/core/indexes/datetimes.pyi @@ -16,7 +16,6 @@ import numpy as np from pandas import ( DataFrame, Index, - Timedelta, TimedeltaIndex, Timestamp, ) @@ -26,7 +25,6 @@ from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin from pandas.core.series import Series from typing_extensions import Self -from pandas._libs.tslibs.offsets import DateOffset from pandas._typing import ( AxesData, DateAndDatetimeLike, @@ -103,14 +101,14 @@ class DatetimeIndex( @property def dtype(self) -> np.dtype | DatetimeTZDtype: ... def shift( - self, periods: int = 1, freq: DateOffset | Timedelta | str | None = None + self, periods: int = 1, freq: Frequency | timedelta | None = None ) -> Self: ... @overload def date_range( start: str | DateAndDatetimeLike, end: str | DateAndDatetimeLike, - freq: str | timedelta | Timedelta | BaseOffset | None = None, + freq: Frequency | timedelta | None = None, tz: TimeZones = None, normalize: bool = False, name: Hashable | None = None, @@ -133,7 +131,7 @@ def date_range( start: str | DateAndDatetimeLike, *, periods: int, - freq: str | timedelta | Timedelta | BaseOffset | None = None, + freq: Frequency | timedelta | None = None, tz: TimeZones = None, normalize: bool = False, name: Hashable | None = None, @@ -145,7 +143,7 @@ def date_range( *, end: str | DateAndDatetimeLike, periods: int, - freq: str | timedelta | Timedelta | BaseOffset | None = None, + freq: Frequency | timedelta | None = None, tz: TimeZones = None, normalize: bool = False, name: Hashable | None = None, @@ -157,7 +155,7 @@ def bdate_range( start: str | DateAndDatetimeLike | None = ..., end: str | DateAndDatetimeLike | None = ..., periods: int | None = ..., - freq: str | timedelta | Timedelta | BaseOffset = ..., + freq: Frequency | timedelta = ..., tz: TimeZones = ..., normalize: bool = ..., name: Hashable | None = ..., @@ -171,7 +169,7 @@ def bdate_range( end: str | DateAndDatetimeLike | None = ..., periods: int | None = ..., *, - freq: str | timedelta | Timedelta | BaseOffset, + freq: Frequency | timedelta, tz: TimeZones = ..., normalize: bool = ..., name: Hashable | None = ..., diff --git a/pandas-stubs/core/indexes/interval.pyi b/pandas-stubs/core/indexes/interval.pyi index 2ef586772..c3b50788f 100644 --- a/pandas-stubs/core/indexes/interval.pyi +++ b/pandas-stubs/core/indexes/interval.pyi @@ -19,11 +19,11 @@ from pandas._libs.interval import ( Interval as Interval, IntervalMixin, ) -from pandas._libs.tslibs.offsets import BaseOffset from pandas._typing import ( DatetimeLike, DtypeArg, FillnaOptions, + Frequency, IntervalClosedType, IntervalT, Label, @@ -328,7 +328,7 @@ def interval_range( start: _TimestampLike, end: _TimestampLike | None = ..., periods: int | None = ..., - freq: str | BaseOffset | pd.Timedelta | dt.timedelta | None = ..., + freq: Frequency | dt.timedelta | None = ..., name: Hashable = ..., closed: IntervalClosedType = ..., ) -> IntervalIndex[Interval[pd.Timestamp]]: ... @@ -338,7 +338,7 @@ def interval_range( start: None = ..., end: _TimestampLike, periods: int | None = ..., - freq: str | BaseOffset | pd.Timedelta | dt.timedelta | None = ..., + freq: Frequency | dt.timedelta | None = ..., name: Hashable = ..., closed: IntervalClosedType = ..., ) -> IntervalIndex[Interval[pd.Timestamp]]: ... @@ -347,7 +347,7 @@ def interval_range( start: _TimedeltaLike, end: _TimedeltaLike | None = ..., periods: int | None = ..., - freq: str | BaseOffset | pd.Timedelta | dt.timedelta | None = ..., + freq: Frequency | dt.timedelta | None = ..., name: Hashable = ..., closed: IntervalClosedType = ..., ) -> IntervalIndex[Interval[pd.Timedelta]]: ... @@ -357,7 +357,7 @@ def interval_range( start: None = ..., end: _TimedeltaLike, periods: int | None = ..., - freq: str | BaseOffset | pd.Timedelta | dt.timedelta | None = ..., + freq: Frequency | dt.timedelta | None = ..., name: Hashable = ..., closed: IntervalClosedType = ..., ) -> IntervalIndex[Interval[pd.Timedelta]]: ... diff --git a/pandas-stubs/core/indexes/timedeltas.pyi b/pandas-stubs/core/indexes/timedeltas.pyi index 89866d48f..d39c4b891 100644 --- a/pandas-stubs/core/indexes/timedeltas.pyi +++ b/pandas-stubs/core/indexes/timedeltas.pyi @@ -11,7 +11,6 @@ from typing import ( import numpy as np from pandas import ( - DateOffset, Index, Period, ) @@ -23,9 +22,9 @@ from pandas.core.series import Series from typing_extensions import Self from pandas._libs import Timedelta -from pandas._libs.tslibs import BaseOffset from pandas._typing import ( AxesData, + Frequency, TimedeltaConvertibleTypes, np_ndarray_td, num, @@ -39,7 +38,7 @@ class TimedeltaIndex( data: ( Sequence[dt.timedelta | Timedelta | np.timedelta64 | float] | AxesData ) = ..., - freq: str | BaseOffset = ..., + freq: Frequency = ..., closed: object = ..., dtype: Literal[" str: ... @final def to_series(self, index=..., name: Hashable = ...) -> Series[Timedelta]: ... - def shift(self, periods: int = 1, freq=...) -> Self: ... + def shift( + self, periods: int = 1, freq: Frequency | dt.timedelta | None = None + ) -> Self: ... @overload def timedelta_range( start: TimedeltaConvertibleTypes, end: TimedeltaConvertibleTypes, *, - freq: str | DateOffset | Timedelta | dt.timedelta | None = None, + freq: Frequency | Timedelta | dt.timedelta | None = None, name: Hashable | None = None, closed: Literal["left", "right"] | None = None, unit: None | str = ..., @@ -103,7 +104,7 @@ def timedelta_range( *, end: TimedeltaConvertibleTypes, periods: int, - freq: str | DateOffset | Timedelta | dt.timedelta | None = None, + freq: Frequency | Timedelta | dt.timedelta | None = None, name: Hashable | None = None, closed: Literal["left", "right"] | None = None, unit: None | str = ..., @@ -113,7 +114,7 @@ def timedelta_range( start: TimedeltaConvertibleTypes, *, periods: int, - freq: str | DateOffset | Timedelta | dt.timedelta | None = None, + freq: Frequency | Timedelta | dt.timedelta | None = None, name: Hashable | None = None, closed: Literal["left", "right"] | None = None, unit: None | str = ..., diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi index 5ebd3d407..ed99aede9 100644 --- a/pandas-stubs/core/series.pyi +++ b/pandas-stubs/core/series.pyi @@ -142,6 +142,7 @@ from pandas._typing import ( FillnaOptions, FloatDtypeArg, FloatFormatType, + Frequency, GenericT, GenericT_co, GroupByObjectNonScalar, @@ -4520,7 +4521,7 @@ class Series(IndexOpsMixin[S1], NDFrame): @overload def rolling( self, - window: int | _str | timedelta | BaseOffset | BaseIndexer, + window: int | Frequency | timedelta | BaseIndexer, min_periods: int | None = ..., center: _bool = ..., on: _str | None = ..., @@ -4533,7 +4534,7 @@ class Series(IndexOpsMixin[S1], NDFrame): @overload def rolling( self, - window: int | _str | timedelta | BaseOffset | BaseIndexer, + window: int | Frequency | timedelta | BaseIndexer, min_periods: int | None = ..., center: _bool = ..., on: _str | None = ..., From 83dd9c513a2c7501f99143ab104cf0dfa7a71397 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 12:06:22 +0100 Subject: [PATCH 2/8] add some missing freq annotations# --- pandas-stubs/core/frame.pyi | 4 ++-- pandas-stubs/core/groupby/groupby.pyi | 2 +- pandas-stubs/core/series.pyi | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi index 7709a2ef6..d33c6c1a3 100644 --- a/pandas-stubs/core/frame.pyi +++ b/pandas-stubs/core/frame.pyi @@ -1684,14 +1684,14 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): ) -> Self: ... def to_timestamp( self, - freq=..., + freq: Frequency | None = None, how: ToTimestampHow = ..., axis: Axis = 0, copy: _bool = True, ) -> Self: ... def to_period( self, - freq: _str | None = None, + freq: Frequency | None = None, axis: Axis = 0, copy: _bool = True, ) -> Self: ... diff --git a/pandas-stubs/core/groupby/groupby.pyi b/pandas-stubs/core/groupby/groupby.pyi index 174d16ef9..dc87cce1f 100644 --- a/pandas-stubs/core/groupby/groupby.pyi +++ b/pandas-stubs/core/groupby/groupby.pyi @@ -319,7 +319,7 @@ class GroupBy(BaseGroupBy[NDFrameT]): periods: int = ..., fill_method: Literal["bfill", "ffill"] | None | _NoDefaultDoNotUse = ..., limit: int | None | _NoDefaultDoNotUse = ..., - freq=..., + freq: Frequency | None = None, axis: Axis | _NoDefaultDoNotUse = ..., ) -> NDFrameT: ... @final diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi index 27618ec16..4c2ffea78 100644 --- a/pandas-stubs/core/series.pyi +++ b/pandas-stubs/core/series.pyi @@ -1237,7 +1237,7 @@ class Series(IndexOpsMixin[S1], NDFrame): ) -> Series[S1]: ... def to_timestamp( self, - freq=..., + freq: Frequency | None = None, how: ToTimestampHow = "start", copy: _bool = True, ) -> Series[S1]: ... From 1bfd52a3bd5ebe4776f73b2e7526c4670e1d7025 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:12:34 +0100 Subject: [PATCH 3/8] restore DateOffset --- pandas-stubs/core/frame.pyi | 2 +- pandas-stubs/core/indexes/accessors.pyi | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi index d33c6c1a3..5e2741e20 100644 --- a/pandas-stubs/core/frame.pyi +++ b/pandas-stubs/core/frame.pyi @@ -1684,7 +1684,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): ) -> Self: ... def to_timestamp( self, - freq: Frequency | None = None, + freq: str | DateOffset | None = None, how: ToTimestampHow = ..., axis: Axis = 0, copy: _bool = True, diff --git a/pandas-stubs/core/indexes/accessors.pyi b/pandas-stubs/core/indexes/accessors.pyi index bac5c2e29..01e408fc6 100644 --- a/pandas-stubs/core/indexes/accessors.pyi +++ b/pandas-stubs/core/indexes/accessors.pyi @@ -34,6 +34,7 @@ from typing_extensions import Never from pandas._libs.interval import Interval from pandas._libs.tslibs import BaseOffset +from pandas._libs.tslibs.offsets import DateOffset from pandas._libs.tslibs.period import Period from pandas._libs.tslibs.timedeltas import Timedelta from pandas._libs.tslibs.timestamps import Timestamp @@ -355,12 +356,12 @@ class _PeriodProperties( def strftime(self, date_format: str) -> _PeriodStrReturnTypes: ... def to_timestamp( self, - freq: Frequency | None = ..., + freq: str | DateOffset | None = ..., how: TimestampConvention = ..., ) -> _PeriodDTAReturnTypes: ... def asfreq( self, - freq: Frequency | None = ..., + freq: str | DateOffset | None = ..., how: Literal["E", "END", "FINISH", "S", "START", "BEGIN"] = ..., ) -> _PeriodPAReturnTypes: ... From 046e696a1d1a52195d6bf9da5c92fc273c43be61 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:18:11 +0100 Subject: [PATCH 4/8] restore DateOffset --- pandas-stubs/_libs/tslibs/period.pyi | 7 +++++-- pandas-stubs/core/arrays/period.pyi | 5 ++++- pandas-stubs/core/series.pyi | 2 +- 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/period.pyi b/pandas-stubs/_libs/tslibs/period.pyi index 884ee96d9..22676c2bc 100644 --- a/pandas-stubs/_libs/tslibs/period.pyi +++ b/pandas-stubs/_libs/tslibs/period.pyi @@ -15,7 +15,10 @@ from pandas import ( from typing_extensions import TypeAlias from pandas._libs.tslibs import NaTType -from pandas._libs.tslibs.offsets import BaseOffset +from pandas._libs.tslibs.offsets import ( + BaseOffset, + DateOffset, +) from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( Frequency, @@ -233,6 +236,6 @@ class Period(PeriodMixin): def strftime(self, fmt: str) -> str: ... def to_timestamp( self, - freq: Frequency | None = ..., + freq: str | DateOffset | None = ..., how: _PeriodToTimestampHow = "S", ) -> Timestamp: ... diff --git a/pandas-stubs/core/arrays/period.pyi b/pandas-stubs/core/arrays/period.pyi index ca5c79944..e10df6aa7 100644 --- a/pandas-stubs/core/arrays/period.pyi +++ b/pandas-stubs/core/arrays/period.pyi @@ -6,6 +6,7 @@ from pandas.core.arrays.datetimelike import ( ) from pandas._libs.tslibs import Timestamp +from pandas._libs.tslibs.offsets import DateOffset from pandas._libs.tslibs.period import Period class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps): @@ -37,6 +38,8 @@ class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps): def start_time(self) -> Timestamp: ... @property def end_time(self) -> Timestamp: ... - def to_timestamp(self, freq: str | None = ..., how: str = ...) -> Timestamp: ... + def to_timestamp( + self, freq: str | DateOffset | None = None, how: str = ... + ) -> Timestamp: ... def asfreq(self, freq: str | None = ..., how: str = "E") -> Period: ... def astype(self, dtype, copy: bool = True): ... diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi index 4c2ffea78..5e473131c 100644 --- a/pandas-stubs/core/series.pyi +++ b/pandas-stubs/core/series.pyi @@ -1237,7 +1237,7 @@ class Series(IndexOpsMixin[S1], NDFrame): ) -> Series[S1]: ... def to_timestamp( self, - freq: Frequency | None = None, + freq: str | DateOffset | None = None, how: ToTimestampHow = "start", copy: _bool = True, ) -> Series[S1]: ... From 7b4194b6cca258d9be8bd77648d254a8dd6147b2 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 14:28:32 +0100 Subject: [PATCH 5/8] fixup --- pandas-stubs/_libs/tslibs/timestamps.pyi | 4 ++-- pandas-stubs/core/frame.pyi | 2 +- pandas-stubs/core/indexes/accessors.pyi | 4 +++- pandas-stubs/core/series.pyi | 4 +++- 4 files changed, 9 insertions(+), 5 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/timestamps.pyi b/pandas-stubs/_libs/tslibs/timestamps.pyi index fd34007d4..9e1513d62 100644 --- a/pandas-stubs/_libs/tslibs/timestamps.pyi +++ b/pandas-stubs/_libs/tslibs/timestamps.pyi @@ -30,11 +30,11 @@ from typing_extensions import ( ) from pandas._libs.tslibs import ( - BaseOffset, Period, Tick, Timedelta, ) +from pandas._libs.tslibs.offsets import DateOffset from pandas._typing import ( ShapeT, TimestampNonexistent, @@ -282,7 +282,7 @@ class Timestamp(datetime, SupportsIndex): def is_year_end(self) -> bool: ... def to_pydatetime(self, warn: bool = ...) -> datetime: ... def to_datetime64(self) -> np.datetime64: ... - def to_period(self, freq: BaseOffset | str | None = ...) -> Period: ... + def to_period(self, freq: DateOffset | str | None = ...) -> Period: ... def to_julian_date(self) -> np.float64: ... @property def asm8(self) -> np.datetime64: ... diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi index 5e2741e20..a86b616c1 100644 --- a/pandas-stubs/core/frame.pyi +++ b/pandas-stubs/core/frame.pyi @@ -1691,7 +1691,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): ) -> Self: ... def to_period( self, - freq: Frequency | None = None, + freq: str | DateOffset | None = None, axis: Axis = 0, copy: _bool = True, ) -> Self: ... diff --git a/pandas-stubs/core/indexes/accessors.pyi b/pandas-stubs/core/indexes/accessors.pyi index 01e408fc6..df5be9849 100644 --- a/pandas-stubs/core/indexes/accessors.pyi +++ b/pandas-stubs/core/indexes/accessors.pyi @@ -225,7 +225,9 @@ class _DatetimeLikeNoTZMethods( _DTToPeriodReturnType, ], ): - def to_period(self, freq: Frequency | None = ...) -> _DTToPeriodReturnType: ... + def to_period( + self, freq: str | DateOffset | None = ... + ) -> _DTToPeriodReturnType: ... def tz_localize( self, tz: TimeZones, diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi index 5e473131c..7c33da27a 100644 --- a/pandas-stubs/core/series.pyi +++ b/pandas-stubs/core/series.pyi @@ -1241,7 +1241,9 @@ class Series(IndexOpsMixin[S1], NDFrame): how: ToTimestampHow = "start", copy: _bool = True, ) -> Series[S1]: ... - def to_period(self, freq: _str | None = None, copy: _bool = True) -> DataFrame: ... + def to_period( + self, freq: _str | DateOffset | None = None, copy: _bool = True + ) -> DataFrame: ... @property def str( self, From 643741722e5069b6e6a7531345dd0fdf3e7f8890 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 16:05:16 +0100 Subject: [PATCH 6/8] separate more --- pandas-stubs/_libs/tslibs/period.pyi | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/period.pyi b/pandas-stubs/_libs/tslibs/period.pyi index 22676c2bc..c259f31f7 100644 --- a/pandas-stubs/_libs/tslibs/period.pyi +++ b/pandas-stubs/_libs/tslibs/period.pyi @@ -66,7 +66,7 @@ class Period(PeriodMixin): value: ( Period | str | datetime.datetime | datetime.date | Timestamp | None ) = ..., - freq: Frequency | None = ..., + freq: str | DateOffset | None = ..., ordinal: int | None = ..., year: int | None = ..., month: int | None = ..., @@ -230,7 +230,7 @@ class Period(PeriodMixin): def day_of_year(self) -> int: ... @property def day_of_week(self) -> int: ... - def asfreq(self, freq: Frequency, how: _PeriodFreqHow = "end") -> Period: ... + def asfreq(self, freq: str | DateOffset, how: _PeriodFreqHow = "end") -> Period: ... @classmethod def now(cls, freq: Frequency = ...) -> Period: ... def strftime(self, fmt: str) -> str: ... From a47ead6bebf03911d203e7c2646fbce46553d523 Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 16:08:28 +0100 Subject: [PATCH 7/8] Period.now --- pandas-stubs/_libs/tslibs/period.pyi | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/period.pyi b/pandas-stubs/_libs/tslibs/period.pyi index c259f31f7..4ff8d456d 100644 --- a/pandas-stubs/_libs/tslibs/period.pyi +++ b/pandas-stubs/_libs/tslibs/period.pyi @@ -21,7 +21,6 @@ from pandas._libs.tslibs.offsets import ( ) from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( - Frequency, ShapeT, np_1darray, np_ndarray, @@ -232,7 +231,7 @@ class Period(PeriodMixin): def day_of_week(self) -> int: ... def asfreq(self, freq: str | DateOffset, how: _PeriodFreqHow = "end") -> Period: ... @classmethod - def now(cls, freq: Frequency = ...) -> Period: ... + def now(cls, freq: str | DateOffset | None = None) -> Period: ... def strftime(self, fmt: str) -> str: ... def to_timestamp( self, From 7af641fae21cc47f1ca34034c5f0a694fddaa70e Mon Sep 17 00:00:00 2001 From: Marco Gorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Wed, 1 Oct 2025 18:05:25 +0100 Subject: [PATCH 8/8] use PeriodFrequency --- pandas-stubs/_libs/tslibs/period.pyi | 10 ++++----- pandas-stubs/_libs/tslibs/timestamps.pyi | 4 ++-- pandas-stubs/_typing.pyi | 27 ++++++++++++++++++++++++ pandas-stubs/core/arrays/period.pyi | 4 ++-- pandas-stubs/core/frame.pyi | 8 +++---- pandas-stubs/core/indexes/accessors.pyi | 8 +++---- pandas-stubs/core/series.pyi | 10 ++++----- pandas-stubs/tseries/frequencies.pyi | 4 ++-- tests/test_timefuncs.py | 2 +- tests/test_windowing.py | 4 ++-- 10 files changed, 54 insertions(+), 27 deletions(-) diff --git a/pandas-stubs/_libs/tslibs/period.pyi b/pandas-stubs/_libs/tslibs/period.pyi index 4ff8d456d..c4739e0cd 100644 --- a/pandas-stubs/_libs/tslibs/period.pyi +++ b/pandas-stubs/_libs/tslibs/period.pyi @@ -17,10 +17,10 @@ from typing_extensions import TypeAlias from pandas._libs.tslibs import NaTType from pandas._libs.tslibs.offsets import ( BaseOffset, - DateOffset, ) from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( + PeriodFrequency, ShapeT, np_1darray, np_ndarray, @@ -65,7 +65,7 @@ class Period(PeriodMixin): value: ( Period | str | datetime.datetime | datetime.date | Timestamp | None ) = ..., - freq: str | DateOffset | None = ..., + freq: PeriodFrequency | None = None, ordinal: int | None = ..., year: int | None = ..., month: int | None = ..., @@ -229,12 +229,12 @@ class Period(PeriodMixin): def day_of_year(self) -> int: ... @property def day_of_week(self) -> int: ... - def asfreq(self, freq: str | DateOffset, how: _PeriodFreqHow = "end") -> Period: ... + def asfreq(self, freq: PeriodFrequency, how: _PeriodFreqHow = "end") -> Period: ... @classmethod - def now(cls, freq: str | DateOffset | None = None) -> Period: ... + def now(cls, freq: PeriodFrequency | None = None) -> Period: ... def strftime(self, fmt: str) -> str: ... def to_timestamp( self, - freq: str | DateOffset | None = ..., + freq: PeriodFrequency | None = None, how: _PeriodToTimestampHow = "S", ) -> Timestamp: ... diff --git a/pandas-stubs/_libs/tslibs/timestamps.pyi b/pandas-stubs/_libs/tslibs/timestamps.pyi index 9e1513d62..8ad686f39 100644 --- a/pandas-stubs/_libs/tslibs/timestamps.pyi +++ b/pandas-stubs/_libs/tslibs/timestamps.pyi @@ -34,8 +34,8 @@ from pandas._libs.tslibs import ( Tick, Timedelta, ) -from pandas._libs.tslibs.offsets import DateOffset from pandas._typing import ( + PeriodFrequency, ShapeT, TimestampNonexistent, TimeUnit, @@ -282,7 +282,7 @@ class Timestamp(datetime, SupportsIndex): def is_year_end(self) -> bool: ... def to_pydatetime(self, warn: bool = ...) -> datetime: ... def to_datetime64(self) -> np.datetime64: ... - def to_period(self, freq: DateOffset | str | None = ...) -> Period: ... + def to_period(self, freq: PeriodFrequency | None = ...) -> Period: ... def to_julian_date(self) -> np.float64: ... @property def asm8(self) -> np.datetime64: ... diff --git a/pandas-stubs/_typing.pyi b/pandas-stubs/_typing.pyi index b852fcc65..74b17c900 100644 --- a/pandas-stubs/_typing.pyi +++ b/pandas-stubs/_typing.pyi @@ -56,6 +56,19 @@ from pandas.core.dtypes.dtypes import ( ) from pandas.io.formats.format import EngFormatter +from pandas.tseries.offsets import ( + Day, + Hour, + Micro, + Milli, + Minute, + MonthEnd, + Nano, + QuarterEnd, + Second, + Week, + YearEnd, +) P = ParamSpec("P") @@ -162,6 +175,20 @@ Suffixes: TypeAlias = tuple[str | None, str | None] | list[str | None] Ordered: TypeAlias = bool | None JSONSerializable: TypeAlias = PythonScalar | list | dict Frequency: TypeAlias = str | BaseOffset +PeriodFrequency: TypeAlias = ( + str + | Day + | Hour + | Minute + | Second + | Milli + | Micro + | Nano + | YearEnd + | QuarterEnd + | MonthEnd + | Week +) Axes: TypeAlias = ListLike RandomState: TypeAlias = ( diff --git a/pandas-stubs/core/arrays/period.pyi b/pandas-stubs/core/arrays/period.pyi index e10df6aa7..07bd92fb8 100644 --- a/pandas-stubs/core/arrays/period.pyi +++ b/pandas-stubs/core/arrays/period.pyi @@ -6,8 +6,8 @@ from pandas.core.arrays.datetimelike import ( ) from pandas._libs.tslibs import Timestamp -from pandas._libs.tslibs.offsets import DateOffset from pandas._libs.tslibs.period import Period +from pandas._typing import PeriodFrequency class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps): __array_priority__: int = ... @@ -39,7 +39,7 @@ class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps): @property def end_time(self) -> Timestamp: ... def to_timestamp( - self, freq: str | DateOffset | None = None, how: str = ... + self, freq: PeriodFrequency | None = None, how: str = ... ) -> Timestamp: ... def asfreq(self, freq: str | None = ..., how: str = "E") -> Period: ... def astype(self, dtype, copy: bool = True): ... diff --git a/pandas-stubs/core/frame.pyi b/pandas-stubs/core/frame.pyi index a86b616c1..77420dcde 100644 --- a/pandas-stubs/core/frame.pyi +++ b/pandas-stubs/core/frame.pyi @@ -81,7 +81,6 @@ from pandas._libs.lib import _NoDefaultDoNotUse from pandas._libs.missing import NAType from pandas._libs.tslibs import BaseOffset from pandas._libs.tslibs.nattype import NaTType -from pandas._libs.tslibs.offsets import DateOffset from pandas._typing import ( S2, AggFuncTypeBase, @@ -136,6 +135,7 @@ from pandas._typing import ( NDFrameT, NsmallestNlargestKeep, ParquetEngine, + PeriodFrequency, QuantileInterpolation, RandomState, ReadBuffer, @@ -1684,14 +1684,14 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): ) -> Self: ... def to_timestamp( self, - freq: str | DateOffset | None = None, + freq: PeriodFrequency | None = None, how: ToTimestampHow = ..., axis: Axis = 0, copy: _bool = True, ) -> Self: ... def to_period( self, - freq: str | DateOffset | None = None, + freq: PeriodFrequency | None = None, axis: Axis = 0, copy: _bool = True, ) -> Self: ... @@ -2225,7 +2225,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack): self, periods: int = 1, fill_method: None = None, - freq: DateOffset | dt.timedelta | _str | None = ..., + freq: Frequency | dt.timedelta | None = ..., fill_value: Scalar | NAType | None = ..., ) -> Self: ... def pop(self, item: _str) -> Series: ... diff --git a/pandas-stubs/core/indexes/accessors.pyi b/pandas-stubs/core/indexes/accessors.pyi index df5be9849..b87872d78 100644 --- a/pandas-stubs/core/indexes/accessors.pyi +++ b/pandas-stubs/core/indexes/accessors.pyi @@ -34,12 +34,12 @@ from typing_extensions import Never from pandas._libs.interval import Interval from pandas._libs.tslibs import BaseOffset -from pandas._libs.tslibs.offsets import DateOffset from pandas._libs.tslibs.period import Period from pandas._libs.tslibs.timedeltas import Timedelta from pandas._libs.tslibs.timestamps import Timestamp from pandas._typing import ( Frequency, + PeriodFrequency, TimeAmbiguous, TimeNonexistent, TimestampConvention, @@ -226,7 +226,7 @@ class _DatetimeLikeNoTZMethods( ], ): def to_period( - self, freq: str | DateOffset | None = ... + self, freq: PeriodFrequency | None = None ) -> _DTToPeriodReturnType: ... def tz_localize( self, @@ -358,12 +358,12 @@ class _PeriodProperties( def strftime(self, date_format: str) -> _PeriodStrReturnTypes: ... def to_timestamp( self, - freq: str | DateOffset | None = ..., + freq: PeriodFrequency | None = None, how: TimestampConvention = ..., ) -> _PeriodDTAReturnTypes: ... def asfreq( self, - freq: str | DateOffset | None = ..., + freq: PeriodFrequency | None = None, how: Literal["E", "END", "FINISH", "S", "START", "BEGIN"] = ..., ) -> _PeriodPAReturnTypes: ... diff --git a/pandas-stubs/core/series.pyi b/pandas-stubs/core/series.pyi index 7c33da27a..8d6924675 100644 --- a/pandas-stubs/core/series.pyi +++ b/pandas-stubs/core/series.pyi @@ -108,7 +108,6 @@ from pandas._libs.lib import _NoDefaultDoNotUse from pandas._libs.missing import NAType from pandas._libs.tslibs import BaseOffset from pandas._libs.tslibs.nattype import NaTType -from pandas._libs.tslibs.offsets import DateOffset from pandas._typing import ( S1, S1_CO, @@ -167,6 +166,7 @@ from pandas._typing import ( NaPosition, NsmallestNlargestKeep, ObjectDtypeArg, + PeriodFrequency, QuantileInterpolation, RandomState, ReindexMethod, @@ -1237,12 +1237,12 @@ class Series(IndexOpsMixin[S1], NDFrame): ) -> Series[S1]: ... def to_timestamp( self, - freq: str | DateOffset | None = None, + freq: PeriodFrequency | None = None, how: ToTimestampHow = "start", copy: _bool = True, ) -> Series[S1]: ... def to_period( - self, freq: _str | DateOffset | None = None, copy: _bool = True + self, freq: PeriodFrequency | None = None, copy: _bool = True ) -> DataFrame: ... @property def str( @@ -1496,7 +1496,7 @@ class Series(IndexOpsMixin[S1], NDFrame): @final def asfreq( self, - freq: DateOffset | _str, + freq: Frequency, method: FillnaOptions | None = None, how: Literal["start", "end"] | None = None, normalize: _bool = False, @@ -1646,7 +1646,7 @@ class Series(IndexOpsMixin[S1], NDFrame): self, periods: int = 1, fill_method: None = None, - freq: DateOffset | timedelta | _str | None = None, + freq: Frequency | timedelta | None = None, ) -> Series[float]: ... @final def first_valid_index(self) -> Scalar: ... diff --git a/pandas-stubs/tseries/frequencies.pyi b/pandas-stubs/tseries/frequencies.pyi index a1f8360d1..4c1494758 100644 --- a/pandas-stubs/tseries/frequencies.pyi +++ b/pandas-stubs/tseries/frequencies.pyi @@ -8,10 +8,10 @@ from pandas import ( from pandas._typing import Frequency -from pandas.tseries.offsets import DateOffset +from pandas.tseries.offsets import BaseOffset @overload def to_offset(freq: None, is_period: bool = ...) -> None: ... @overload -def to_offset(freq: Frequency, is_period: bool = ...) -> DateOffset: ... +def to_offset(freq: Frequency, is_period: bool = ...) -> BaseOffset: ... def infer_freq(index: Series | DatetimeIndex | TimedeltaIndex) -> str | None: ... diff --git a/tests/test_timefuncs.py b/tests/test_timefuncs.py index 2fdf6a138..ac7c61c32 100644 --- a/tests/test_timefuncs.py +++ b/tests/test_timefuncs.py @@ -1911,7 +1911,7 @@ def test_DatetimeIndex_sub_timedelta() -> None: def test_to_offset() -> None: check(assert_type(to_offset(None), None), type(None)) - check(assert_type(to_offset("1D"), DateOffset), DateOffset) + check(assert_type(to_offset("1D"), BaseOffset), BaseOffset) def test_timestamp_sub_series() -> None: diff --git a/tests/test_windowing.py b/tests/test_windowing.py index c8b041ce5..8abd91f9d 100644 --- a/tests/test_windowing.py +++ b/tests/test_windowing.py @@ -14,7 +14,7 @@ ) from typing_extensions import assert_type -from pandas._libs.tslibs.offsets import DateOffset +from pandas._libs.tslibs.offsets import BaseOffset from tests import ( PD_LTE_23, @@ -58,7 +58,7 @@ def test_rolling_basic_math() -> None: def test_rolling_datetime_index() -> None: offset_1d = to_offset("1D") - check(assert_type(offset_1d, DateOffset), DateOffset) + check(assert_type(offset_1d, BaseOffset), BaseOffset) check(assert_type(DF_DTI.rolling("1D"), "Rolling[DataFrame]"), Rolling, DataFrame) check(