Skip to content

Commit abf9147

Browse files
cmp0xffcmp0xff
committed
refactor: only drop TimestampSeries #1273 (review) 
1 parent 3edd3b3 commit abf9147

File tree

17 files changed

+497
-289
lines changed

17 files changed

+497
-289
lines changed

‎docs/philosophy.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ This also allows type checking for operations on series that contain date/time d
3636
the following example that creates two series of datetimes with corresponding arithmetic.
3737

3838
```python
39+
import pandas as pd
40+
3941
s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
4042
reveal_type(s1)
4143
s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
@@ -46,19 +48,21 @@ ssum = s1 + s2
4648
reveal_type(ssum)
4749
```
4850

49-
The above code (without the `reveal_type()` statements) will raise an `Exception` on the computation of `ssum` because it is
51+
The above code (without the `reveal_type()` statements) will get a `Never`
52+
on the computation of `ssum` because it is
5053
inappropriate to add two series containing `Timestamp` values. The types will be
5154
revealed as follows:
5255

5356
```text
54-
ttest.py:4: note: Revealed type is "pandas.core.series.TimestampSeries"
55-
ttest.py:6: note: Revealed type is "pandas.core.series.TimestampSeries"
57+
ttest.py:4: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
58+
ttest.py:6: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
5659
ttest.py:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
57-
ttest.py:10: note: Revealed type is "builtins.Exception"
60+
ttest.py:9: error: Need type annotation for "ssum" [var-annotated]
61+
ttest.py:10: note: Revealed type is "Never"
5862
```
5963

60-
The type `TimestampSeries` is the result of creating a series from `pd.to_datetime()`, while
61-
the type `TimedeltaSeries` is the result of subtracting two `TimestampSeries` as well as
64+
The type `Series[Timestamp]` is the result of creating a series from `pd.to_datetime()`, while
65+
the type `TimedeltaSeries` is the result of subtracting two `Series[Timestamp]` as well as
6266
the result of `pd.to_timedelta()`.
6367

6468
### Interval is Generic

‎pandas-stubs/_libs/interval.pyi

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -13,10 +13,7 @@ from pandas import (
1313
Timedelta,
1414
Timestamp,
1515
)
16-
from pandas.core.series import (
17-
TimedeltaSeries,
18-
TimestampSeries,
19-
)
16+
from pandas.core.series import TimedeltaSeries
2017

2118
from pandas._typing import (
2219
IntervalClosedType,
@@ -174,7 +171,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
174171
@overload
175172
def __gt__(
176173
self,
177-
other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
174+
other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
178175
) -> Series[bool]: ...
179176
@overload
180177
def __lt__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -183,7 +180,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
183180
@overload
184181
def __lt__(
185182
self,
186-
other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
183+
other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
187184
) -> Series[bool]: ...
188185
@overload
189186
def __ge__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -192,7 +189,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
192189
@overload
193190
def __ge__(
194191
self,
195-
other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
192+
other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
196193
) -> Series[bool]: ...
197194
@overload
198195
def __le__(self, other: Interval[_OrderableT]) -> bool: ...

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

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,7 @@ from pandas import (
1717
Series,
1818
TimedeltaIndex,
1919
)
20-
from pandas.core.series import (
21-
TimedeltaSeries,
22-
TimestampSeries,
23-
)
20+
from pandas.core.series import TimedeltaSeries
2421
from typing_extensions import (
2522
Self,
2623
TypeAlias,
@@ -167,7 +164,7 @@ class Timedelta(timedelta):
167164
other: TimedeltaSeries,
168165
) -> TimedeltaSeries: ...
169166
@overload
170-
def __add__(self, other: TimestampSeries) -> TimestampSeries: ...
167+
def __add__(self, other: Series[Timestamp]) -> Series[Timestamp]: ...
171168
@overload
172169
def __radd__(self, other: np.datetime64) -> Timestamp: ...
173170
@overload

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

Lines changed: 9 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ from pandas import (
2525
from pandas.core.series import (
2626
Series,
2727
TimedeltaSeries,
28-
TimestampSeries,
2928
)
3029
from typing_extensions import (
3130
Never,
@@ -172,31 +171,31 @@ class Timestamp(datetime, SupportsIndex):
172171
self, other: DatetimeIndex | npt.NDArray[np.datetime64]
173172
) -> np_ndarray_bool: ...
174173
@overload
175-
def __le__(self, other: TimestampSeries) -> Series[bool]: ...
174+
def __le__(self, other: Series[Timestamp]) -> Series[bool]: ...
176175
@overload # type: ignore[override]
177176
def __lt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ... # type: ignore[misc]
178177
@overload
179178
def __lt__(
180179
self, other: DatetimeIndex | npt.NDArray[np.datetime64]
181180
) -> np_ndarray_bool: ...
182181
@overload
183-
def __lt__(self, other: TimestampSeries) -> Series[bool]: ...
182+
def __lt__(self, other: Series[Timestamp]) -> Series[bool]: ...
184183
@overload # type: ignore[override]
185184
def __ge__(self, other: Timestamp | datetime | np.datetime64) -> bool: ... # type: ignore[misc]
186185
@overload
187186
def __ge__(
188187
self, other: DatetimeIndex | npt.NDArray[np.datetime64]
189188
) -> np_ndarray_bool: ...
190189
@overload
191-
def __ge__(self, other: TimestampSeries) -> Series[bool]: ...
190+
def __ge__(self, other: Series[Timestamp]) -> Series[bool]: ...
192191
@overload # type: ignore[override]
193192
def __gt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ... # type: ignore[misc]
194193
@overload
195194
def __gt__(
196195
self, other: DatetimeIndex | npt.NDArray[np.datetime64]
197196
) -> np_ndarray_bool: ...
198197
@overload
199-
def __gt__(self, other: TimestampSeries) -> Series[bool]: ...
198+
def __gt__(self, other: Series[Timestamp]) -> Series[bool]: ...
200199
# error: Signature of "__add__" incompatible with supertype "date"/"datetime"
201200
@overload # type: ignore[override]
202201
def __add__(
@@ -205,7 +204,7 @@ class Timestamp(datetime, SupportsIndex):
205204
@overload
206205
def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
207206
@overload
208-
def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
207+
def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
209208
@overload
210209
def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
211210
@overload
@@ -224,25 +223,25 @@ class Timestamp(datetime, SupportsIndex):
224223
@overload
225224
def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
226225
@overload
227-
def __sub__(self, other: TimedeltaSeries) -> TimestampSeries: ...
226+
def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
228227
@overload
229-
def __sub__(self, other: TimestampSeries) -> TimedeltaSeries: ...
228+
def __sub__(self, other: Series[Timestamp]) -> TimedeltaSeries: ...
230229
@overload
231230
def __sub__(
232231
self, other: npt.NDArray[np.timedelta64]
233232
) -> npt.NDArray[np.datetime64]: ...
234233
@overload
235234
def __eq__(self, other: Timestamp | datetime | np.datetime64) -> bool: ... # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
236235
@overload
237-
def __eq__(self, other: TimestampSeries) -> Series[bool]: ... # type: ignore[overload-overlap]
236+
def __eq__(self, other: Series[Timestamp]) -> Series[bool]: ... # type: ignore[overload-overlap]
238237
@overload
239238
def __eq__(self, other: npt.NDArray[np.datetime64] | Index) -> np_ndarray_bool: ... # type: ignore[overload-overlap]
240239
@overload
241240
def __eq__(self, other: object) -> Literal[False]: ...
242241
@overload
243242
def __ne__(self, other: Timestamp | datetime | np.datetime64) -> bool: ... # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
244243
@overload
245-
def __ne__(self, other: TimestampSeries) -> Series[bool]: ... # type: ignore[overload-overlap]
244+
def __ne__(self, other: Series[Timestamp]) -> Series[bool]: ... # type: ignore[overload-overlap]
246245
@overload
247246
def __ne__(self, other: npt.NDArray[np.datetime64] | Index) -> np_ndarray_bool: ... # type: ignore[overload-overlap]
248247
@overload

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

Lines changed: 56 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@ from datetime import (
44
tzinfo as _tzinfo,
55
)
66
from typing import (
7+
Any,
78
Generic,
89
Literal,
910
TypeVar,
11+
overload,
1012
)
1113

1214
import numpy as np
@@ -17,6 +19,7 @@ from pandas import (
1719
PeriodIndex,
1820
Timedelta,
1921
TimedeltaIndex,
22+
Timestamp,
2023
)
2124
from pandas.core.accessor import PandasDelegate
2225
from pandas.core.arrays import (
@@ -29,12 +32,13 @@ from pandas.core.series import (
2932
PeriodSeries,
3033
Series,
3134
TimedeltaSeries,
32-
TimestampSeries,
3335
)
36+
from typing_extensions import Never
3437

3538
from pandas._libs.tslibs import BaseOffset
3639
from pandas._libs.tslibs.offsets import DateOffset
3740
from pandas._typing import (
41+
S1,
3842
TimeAmbiguous,
3943
TimeNonexistent,
4044
TimestampConvention,
@@ -155,14 +159,13 @@ class _DatetimeLikeOps(
155159
],
156160
): ...
157161

158-
# Ideally, the rounding methods would return TimestampSeries when `Series.dt.method`
162+
# Ideally, the rounding methods would return Series[Timestamp] when `Series.dt.method`
159163
# is invoked, but because of how Series.dt is hooked in and that we may not know the
160164
# type of the series, we don't know which kind of series was ...ed
161165
# in to the dt accessor
162166

163167
_DTTimestampTimedeltaReturnType = TypeVar(
164-
"_DTTimestampTimedeltaReturnType",
165-
bound=Series | TimestampSeries | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
168+
"_DTTimestampTimedeltaReturnType", bound=Series | DatetimeIndex | TimedeltaIndex
166169
)
167170

168171
class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -198,7 +201,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
198201
) -> _DTTimestampTimedeltaReturnType: ...
199202

200203
_DTNormalizeReturnType = TypeVar(
201-
"_DTNormalizeReturnType", TimestampSeries, DatetimeIndex
204+
"_DTNormalizeReturnType", Series[Timestamp], DatetimeIndex
202205
)
203206
_DTStrKindReturnType = TypeVar("_DTStrKindReturnType", bound=Series[str] | Index)
204207
_DTToPeriodReturnType = TypeVar(
@@ -320,7 +323,7 @@ class TimedeltaProperties(
320323
def as_unit(self, unit: TimeUnit) -> TimedeltaSeries: ...
321324

322325
_PeriodDTReturnTypes = TypeVar(
323-
"_PeriodDTReturnTypes", bound=TimestampSeries | DatetimeIndex
326+
"_PeriodDTReturnTypes", bound=Series[Timestamp] | DatetimeIndex
324327
)
325328
_PeriodIntReturnTypes = TypeVar("_PeriodIntReturnTypes", bound=Series[int] | Index[int])
326329
_PeriodStrReturnTypes = TypeVar("_PeriodStrReturnTypes", bound=Series[str] | Index)
@@ -363,7 +366,7 @@ class PeriodIndexFieldOps(
363366
class PeriodProperties(
364367
Properties,
365368
_PeriodProperties[
366-
TimestampSeries, Series[int], Series[str], DatetimeArray, PeriodArray
369+
Series[Timestamp], Series[int], Series[str], DatetimeArray, PeriodArray
367370
],
368371
_DatetimeFieldOps[Series[int]],
369372
_IsLeapYearProperty,
@@ -377,7 +380,7 @@ class CombinedDatetimelikeProperties(
377380
Series[dt.date],
378381
Series[dt.time],
379382
str,
380-
TimestampSeries,
383+
Series[Timestamp],
381384
Series[str],
382385
PeriodSeries,
383386
],
@@ -388,11 +391,11 @@ class TimestampProperties(
388391
DatetimeProperties[
389392
Series[int],
390393
Series[bool],
391-
TimestampSeries,
394+
Series[Timestamp],
392395
Series[dt.date],
393396
Series[dt.time],
394397
str,
395-
TimestampSeries,
398+
Series[Timestamp],
396399
Series[str],
397400
PeriodSeries,
398401
]
@@ -427,3 +430,46 @@ class TimedeltaIndexProperties(
427430
_TimedeltaPropertiesNoRounding[Index, Index],
428431
_DatetimeRoundingMethods[TimedeltaIndex],
429432
): ...
433+
434+
class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]):
435+
@overload
436+
def __get__(self, instance: Series[Never], owner: Any) -> Never: ...
437+
@overload
438+
def __get__(
439+
self, instance: Series[Timestamp], owner: Any
440+
) -> TimestampProperties: ...
441+
@overload
442+
def __get__(
443+
self, instance: Series[S1], owner: Any
444+
) -> CombinedDatetimelikeProperties: ...
445+
def round(
446+
self,
447+
freq: str | BaseOffset | None,
448+
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
449+
nonexistent: (
450+
Literal["shift_forward", "shift_backward", "NaT", "raise"]
451+
| timedelta
452+
| Timedelta
453+
) = ...,
454+
) -> Series[S1]: ...
455+
def floor(
456+
self,
457+
freq: str | BaseOffset | None,
458+
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
459+
nonexistent: (
460+
Literal["shift_forward", "shift_backward", "NaT", "raise"]
461+
| timedelta
462+
| Timedelta
463+
) = ...,
464+
) -> Series[S1]: ...
465+
def ceil(
466+
self,
467+
freq: str | BaseOffset | None,
468+
ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
469+
nonexistent: (
470+
Literal["shift_forward", "shift_backward", "NaT", "raise"]
471+
| timedelta
472+
| Timedelta
473+
) = ...,
474+
) -> Series[S1]: ...
475+
def as_unit(self, unit: TimeUnit) -> Series[S1]: ...

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,8 @@ from pandas import (
2323
from pandas.core.indexes.accessors import DatetimeIndexProperties
2424
from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
2525
from pandas.core.series import (
26+
Series,
2627
TimedeltaSeries,
27-
TimestampSeries,
2828
)
2929
from typing_extensions import Self
3030

@@ -60,13 +60,13 @@ class DatetimeIndex(DatetimeTimedeltaMixin[Timestamp], DatetimeIndexProperties):
6060
# various ignores needed for mypy, as we do want to restrict what can be used in
6161
# arithmetic for these types
6262
@overload
63-
def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
63+
def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
6464
@overload
6565
def __add__(
6666
self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
6767
) -> DatetimeIndex: ...
6868
@overload
69-
def __sub__(self, other: TimedeltaSeries) -> TimestampSeries: ...
69+
def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
7070
@overload
7171
def __sub__(
7272
self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
@@ -76,7 +76,7 @@ class DatetimeIndex(DatetimeTimedeltaMixin[Timestamp], DatetimeIndexProperties):
7676
self, other: datetime | Timestamp | DatetimeIndex
7777
) -> TimedeltaIndex: ...
7878
@final
79-
def to_series(self, index=..., name: Hashable = ...) -> TimestampSeries: ...
79+
def to_series(self, index=..., name: Hashable = ...) -> Series[Timestamp]: ...
8080
def snap(self, freq: str = ...): ...
8181
def slice_indexer(self, start=..., end=..., step=...): ...
8282
def searchsorted(self, value, side: str = ..., sorter=...): ...

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,6 @@ from pandas import Index
1515
from pandas.core.indexes.extension import ExtensionIndex
1616
from pandas.core.series import (
1717
TimedeltaSeries,
18-
TimestampSeries,
1918
)
2019
from typing_extensions import TypeAlias
2120

@@ -53,7 +52,7 @@ _EdgesFloat: TypeAlias = (
5352
_EdgesTimestamp: TypeAlias = (
5453
Sequence[DatetimeLike]
5554
| npt.NDArray[np.datetime64]
56-
| TimestampSeries
55+
| pd.Series[pd.Timestamp]
5756
| pd.DatetimeIndex
5857
)
5958
_EdgesTimedelta: TypeAlias = (

0 commit comments

Comments
 (0)