Skip to content

Commit 9d3eb9f

Browse files
MarcoGorelliloicdiridollou
MarcoGorelli
and
loicdiridollou
authored
type freq in shift, consistently use Frequency alias (#1394)
* type `freq` in `shift`, consistently use `Frequency` alias * add some missing freq annotations# * restore DateOffset * restore DateOffset * fixup * separate more * Period.now * use PeriodFrequency --------- Co-authored-by: Loic Diridollou <loic.diridollou@gmail.com>
1 parent 8ec4901 commit 9d3eb9f

File tree

15 files changed

+95
-57
lines changed

15 files changed

+95
-57
lines changed

‎pandas-stubs/_libs/tslibs/period.pyi‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,9 +16,12 @@ from pandas import (
1616
from typing_extensions import Self
1717

1818
from pandas._libs.tslibs import NaTType
19-
from pandas._libs.tslibs.offsets import BaseOffset
19+
from pandas._libs.tslibs.offsets import (
20+
BaseOffset,
21+
)
2022
from pandas._libs.tslibs.timestamps import Timestamp
2123
from pandas._typing import (
24+
PeriodFrequency,
2225
ShapeT,
2326
np_1darray,
2427
np_ndarray,
@@ -63,7 +66,7 @@ class Period(PeriodMixin):
6366
value: (
6467
Period | str | datetime.datetime | datetime.date | Timestamp | None
6568
) = ...,
66-
freq: str | BaseOffset | None = ...,
69+
freq: PeriodFrequency | None = None,
6770
ordinal: int | None = ...,
6871
year: int | None = ...,
6972
month: int | None = ...,
@@ -223,12 +226,12 @@ class Period(PeriodMixin):
223226
def day_of_year(self) -> int: ...
224227
@property
225228
def day_of_week(self) -> int: ...
226-
def asfreq(self, freq: str | BaseOffset, how: _PeriodFreqHow = "end") -> Period: ...
229+
def asfreq(self, freq: PeriodFrequency, how: _PeriodFreqHow = "end") -> Period: ...
227230
@classmethod
228-
def now(cls, freq: str | BaseOffset = ...) -> Period: ...
231+
def now(cls, freq: PeriodFrequency | None = None) -> Period: ...
229232
def strftime(self, fmt: str) -> str: ...
230233
def to_timestamp(
231234
self,
232-
freq: str | BaseOffset | None = ...,
235+
freq: PeriodFrequency | None = None,
233236
how: _PeriodToTimestampHow = "S",
234237
) -> Timestamp: ...

‎pandas-stubs/_libs/tslibs/timedeltas.pyi‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,12 @@ from pandas import (
2424
from typing_extensions import Self
2525

2626
from pandas._libs.tslibs import (
27-
BaseOffset,
2827
NaTType,
2928
)
3029
from pandas._libs.tslibs.period import Period
3130
from pandas._libs.tslibs.timestamps import Timestamp
3231
from pandas._typing import (
32+
Frequency,
3333
Just,
3434
ShapeT,
3535
TimeUnit,
@@ -132,9 +132,9 @@ class Timedelta(timedelta):
132132
@property
133133
def asm8(self) -> np.timedelta64: ...
134134
# TODO: round/floor/ceil could return NaT?
135-
def round(self, freq: str | BaseOffset) -> Self: ...
136-
def floor(self, freq: str | BaseOffset) -> Self: ...
137-
def ceil(self, freq: str | BaseOffset) -> Self: ...
135+
def round(self, freq: Frequency) -> Self: ...
136+
def floor(self, freq: Frequency) -> Self: ...
137+
def ceil(self, freq: Frequency) -> Self: ...
138138
@property
139139
def resolution_string(self) -> str: ...
140140
# Override due to more types supported than timedelta

‎pandas-stubs/_libs/tslibs/timestamps.pyi‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,12 +30,12 @@ from typing_extensions import (
3030
)
3131

3232
from pandas._libs.tslibs import (
33-
BaseOffset,
3433
Period,
3534
Tick,
3635
Timedelta,
3736
)
3837
from pandas._typing import (
38+
PeriodFrequency,
3939
ShapeT,
4040
TimestampNonexistent,
4141
TimeUnit,
@@ -282,7 +282,7 @@ class Timestamp(datetime, SupportsIndex):
282282
def is_year_end(self) -> bool: ...
283283
def to_pydatetime(self, warn: bool = ...) -> datetime: ...
284284
def to_datetime64(self) -> np.datetime64: ...
285-
def to_period(self, freq: BaseOffset | str | None = ...) -> Period: ...
285+
def to_period(self, freq: PeriodFrequency | None = ...) -> Period: ...
286286
def to_julian_date(self) -> np.float64: ...
287287
@property
288288
def asm8(self) -> np.datetime64: ...

‎pandas-stubs/_typing.pyi‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,19 @@ from pandas.core.dtypes.dtypes import (
5656
)
5757

5858
from pandas.io.formats.format import EngFormatter
59+
from pandas.tseries.offsets import (
60+
Day,
61+
Hour,
62+
Micro,
63+
Milli,
64+
Minute,
65+
MonthEnd,
66+
Nano,
67+
QuarterEnd,
68+
Second,
69+
Week,
70+
YearEnd,
71+
)
5972

6073
P = ParamSpec("P")
6174

@@ -162,6 +175,20 @@ Suffixes: TypeAlias = tuple[str | None, str | None] | list[str | None]
162175
Ordered: TypeAlias = bool | None
163176
JSONSerializable: TypeAlias = PythonScalar | list | dict
164177
Frequency: TypeAlias = str | BaseOffset
178+
PeriodFrequency: TypeAlias = (
179+
str
180+
| Day
181+
| Hour
182+
| Minute
183+
| Second
184+
| Milli
185+
| Micro
186+
| Nano
187+
| YearEnd
188+
| QuarterEnd
189+
| MonthEnd
190+
| Week
191+
)
165192
Axes: TypeAlias = ListLike
166193

167194
RandomState: TypeAlias = (

‎pandas-stubs/core/arrays/period.pyi‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ from pandas._libs.tslibs import Timestamp
88
from pandas._libs.tslibs.period import Period
99
from pandas._typing import (
1010
NpDtype,
11+
PeriodFrequency,
1112
np_1darray,
1213
)
1314

@@ -42,6 +43,8 @@ class PeriodArray(DatetimeLikeArrayMixin, DatelikeOps):
4243
def start_time(self) -> Timestamp: ...
4344
@property
4445
def end_time(self) -> Timestamp: ...
45-
def to_timestamp(self, freq: str | None = ..., how: str = ...) -> Timestamp: ...
46+
def to_timestamp(
47+
self, freq: PeriodFrequency | None = None, how: str = ...
48+
) -> Timestamp: ...
4649
def asfreq(self, freq: str | None = ..., how: str = "E") -> Period: ...
4750
def astype(self, dtype, copy: bool = True): ...

‎pandas-stubs/core/frame.pyi‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,6 @@ from pandas._libs.lib import _NoDefaultDoNotUse
7979
from pandas._libs.missing import NAType
8080
from pandas._libs.tslibs import BaseOffset
8181
from pandas._libs.tslibs.nattype import NaTType
82-
from pandas._libs.tslibs.offsets import DateOffset
8382
from pandas._typing import (
8483
S2,
8584
AggFuncTypeBase,
@@ -104,6 +103,7 @@ from pandas._typing import (
104103
FillnaOptions,
105104
FloatFormatType,
106105
FormattersType,
106+
Frequency,
107107
GroupByObjectNonScalar,
108108
HashableT,
109109
HashableT1,
@@ -133,6 +133,7 @@ from pandas._typing import (
133133
NDFrameT,
134134
NsmallestNlargestKeep,
135135
ParquetEngine,
136+
PeriodFrequency,
136137
QuantileInterpolation,
137138
RandomState,
138139
ReadBuffer,
@@ -1681,14 +1682,14 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
16811682
) -> Self: ...
16821683
def to_timestamp(
16831684
self,
1684-
freq=...,
1685+
freq: PeriodFrequency | None = None,
16851686
how: ToTimestampHow = ...,
16861687
axis: Axis = 0,
16871688
copy: _bool = True,
16881689
) -> Self: ...
16891690
def to_period(
16901691
self,
1691-
freq: _str | None = None,
1692+
freq: PeriodFrequency | None = None,
16921693
axis: Axis = 0,
16931694
copy: _bool = True,
16941695
) -> Self: ...
@@ -2222,7 +2223,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
22222223
self,
22232224
periods: int = 1,
22242225
fill_method: None = None,
2225-
freq: DateOffset | dt.timedelta | _str | None = ...,
2226+
freq: Frequency | dt.timedelta | None = ...,
22262227
fill_value: Scalar | NAType | None = ...,
22272228
) -> Self: ...
22282229
def pop(self, item: _str) -> Series: ...
@@ -2339,7 +2340,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
23392340
@overload
23402341
def rolling(
23412342
self,
2342-
window: int | str | dt.timedelta | BaseOffset | BaseIndexer,
2343+
window: int | Frequency | dt.timedelta | BaseIndexer,
23432344
min_periods: int | None = ...,
23442345
center: _bool = ...,
23452346
on: Hashable | None = ...,
@@ -2353,7 +2354,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
23532354
@overload
23542355
def rolling(
23552356
self,
2356-
window: int | str | dt.timedelta | BaseOffset | BaseIndexer,
2357+
window: int | Frequency | dt.timedelta | BaseIndexer,
23572358
min_periods: int | None = ...,
23582359
center: _bool = ...,
23592360
on: Hashable | None = ...,

‎pandas-stubs/core/groupby/groupby.pyi‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -315,7 +315,7 @@ class GroupBy(BaseGroupBy[NDFrameT]):
315315
periods: int = ...,
316316
fill_method: Literal["bfill", "ffill"] | None | _NoDefaultDoNotUse = ...,
317317
limit: int | None | _NoDefaultDoNotUse = ...,
318-
freq=...,
318+
freq: Frequency | None = None,
319319
axis: Axis | _NoDefaultDoNotUse = ...,
320320
) -> NDFrameT: ...
321321
@final

‎pandas-stubs/core/indexes/accessors.pyi‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,11 +34,12 @@ from typing_extensions import Never
3434

3535
from pandas._libs.interval import Interval
3636
from pandas._libs.tslibs import BaseOffset
37-
from pandas._libs.tslibs.offsets import DateOffset
3837
from pandas._libs.tslibs.period import Period
3938
from pandas._libs.tslibs.timedeltas import Timedelta
4039
from pandas._libs.tslibs.timestamps import Timestamp
4140
from pandas._typing import (
41+
Frequency,
42+
PeriodFrequency,
4243
TimeAmbiguous,
4344
TimeNonexistent,
4445
TimestampConvention,
@@ -178,7 +179,7 @@ _DTTimestampTimedeltaReturnType = TypeVar(
178179
class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
179180
def round(
180181
self,
181-
freq: str | BaseOffset | None,
182+
freq: Frequency | None,
182183
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
183184
nonexistent: (
184185
Literal["shift_forward", "shift_backward", "NaT", "raise"]
@@ -188,7 +189,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
188189
) -> _DTTimestampTimedeltaReturnType: ...
189190
def floor(
190191
self,
191-
freq: str | BaseOffset | None,
192+
freq: Frequency | None,
192193
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
193194
nonexistent: (
194195
Literal["shift_forward", "shift_backward", "NaT", "raise"]
@@ -198,7 +199,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
198199
) -> _DTTimestampTimedeltaReturnType: ...
199200
def ceil(
200201
self,
201-
freq: str | BaseOffset | None,
202+
freq: Frequency | None,
202203
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
203204
nonexistent: (
204205
Literal["shift_forward", "shift_backward", "NaT", "raise"]
@@ -225,7 +226,7 @@ class _DatetimeLikeNoTZMethods(
225226
],
226227
):
227228
def to_period(
228-
self, freq: str | BaseOffset | None = ...
229+
self, freq: PeriodFrequency | None = None
229230
) -> _DTToPeriodReturnType: ...
230231
def tz_localize(
231232
self,
@@ -357,12 +358,12 @@ class _PeriodProperties(
357358
def strftime(self, date_format: str) -> _PeriodStrReturnTypes: ...
358359
def to_timestamp(
359360
self,
360-
freq: str | DateOffset | None = ...,
361+
freq: PeriodFrequency | None = None,
361362
how: TimestampConvention = ...,
362363
) -> _PeriodDTAReturnTypes: ...
363364
def asfreq(
364365
self,
365-
freq: str | DateOffset | None = ...,
366+
freq: PeriodFrequency | None = None,
366367
how: Literal["E", "END", "FINISH", "S", "START", "BEGIN"] = ...,
367368
) -> _PeriodPAReturnTypes: ...
368369

‎pandas-stubs/core/indexes/datetimes.pyi‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,6 @@ import numpy as np
1616
from pandas import (
1717
DataFrame,
1818
Index,
19-
Timedelta,
2019
TimedeltaIndex,
2120
Timestamp,
2221
)
@@ -25,7 +24,6 @@ from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
2524
from pandas.core.series import Series
2625
from typing_extensions import Self
2726

28-
from pandas._libs.tslibs.offsets import DateOffset
2927
from pandas._typing import (
3028
AxesData,
3129
DateAndDatetimeLike,
@@ -99,14 +97,14 @@ class DatetimeIndex(
9997
@property
10098
def dtype(self) -> np.dtype | DatetimeTZDtype: ...
10199
def shift(
102-
self, periods: int = 1, freq: DateOffset | Timedelta | str | None = None
100+
self, periods: int = 1, freq: Frequency | timedelta | None = None
103101
) -> Self: ...
104102

105103
@overload
106104
def date_range(
107105
start: str | DateAndDatetimeLike,
108106
end: str | DateAndDatetimeLike,
109-
freq: str | timedelta | Timedelta | BaseOffset | None = None,
107+
freq: Frequency | timedelta | None = None,
110108
tz: TimeZones = None,
111109
normalize: bool = False,
112110
name: Hashable | None = None,
@@ -129,7 +127,7 @@ def date_range(
129127
start: str | DateAndDatetimeLike,
130128
*,
131129
periods: int,
132-
freq: str | timedelta | Timedelta | BaseOffset | None = None,
130+
freq: Frequency | timedelta | None = None,
133131
tz: TimeZones = None,
134132
normalize: bool = False,
135133
name: Hashable | None = None,
@@ -141,7 +139,7 @@ def date_range(
141139
*,
142140
end: str | DateAndDatetimeLike,
143141
periods: int,
144-
freq: str | timedelta | Timedelta | BaseOffset | None = None,
142+
freq: Frequency | timedelta | None = None,
145143
tz: TimeZones = None,
146144
normalize: bool = False,
147145
name: Hashable | None = None,
@@ -153,7 +151,7 @@ def bdate_range(
153151
start: str | DateAndDatetimeLike | None = ...,
154152
end: str | DateAndDatetimeLike | None = ...,
155153
periods: int | None = ...,
156-
freq: str | timedelta | Timedelta | BaseOffset = ...,
154+
freq: Frequency | timedelta = ...,
157155
tz: TimeZones = ...,
158156
normalize: bool = ...,
159157
name: Hashable | None = ...,
@@ -167,7 +165,7 @@ def bdate_range(
167165
end: str | DateAndDatetimeLike | None = ...,
168166
periods: int | None = ...,
169167
*,
170-
freq: str | timedelta | Timedelta | BaseOffset,
168+
freq: Frequency | timedelta,
171169
tz: TimeZones = ...,
172170
normalize: bool = ...,
173171
name: Hashable | None = ...,

0 commit comments

Comments
 (0)