refactor: #718 only drop TimestampSeries

docs/philosophy.md

@@ -36,6 +36,8 @@ This also allows type checking for operations on series that contain date/time d
 the following example that creates two series of datetimes with corresponding arithmetic.
 
 ```python
+import pandas as pd
+
 s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
 reveal_type(s1)
 s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
@@ -46,19 +48,21 @@ ssum = s1 + s2
 reveal_type(ssum)
 ```
 
-The above code (without the `reveal_type()` statements) will raise an `Exception` on the computation of `ssum` because it is
+The above code (without the `reveal_type()` statements) will get a `Never`
+on the computation of `ssum` because it is
 inappropriate to add two series containing `Timestamp` values.  The types will be
 revealed as follows:
 
 ```text
-ttest.py:4: note: Revealed type is "pandas.core.series.TimestampSeries"
-ttest.py:6: note: Revealed type is "pandas.core.series.TimestampSeries"
+ttest.py:4: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
+ttest.py:6: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
 ttest.py:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
-ttest.py:10: note: Revealed type is "builtins.Exception"
+ttest.py:9: error: Need type annotation for "ssum"  [var-annotated]
+ttest.py:10: note: Revealed type is "Never"
 ```
 
-The type `TimestampSeries` is the result of creating a series from `pd.to_datetime()`, while
-the type `TimedeltaSeries` is the result of subtracting two `TimestampSeries` as well as
+The type `Series[Timestamp]` is the result of creating a series from `pd.to_datetime()`, while
+the type `TimedeltaSeries` is the result of subtracting two `Series[Timestamp]` as well as
 the result of `pd.to_timedelta()`.
 
 ### Interval is Generic

pandas-stubs/_libs/interval.pyi

@@ -13,10 +13,7 @@ from pandas import (
     Timedelta,
     Timestamp,
 )
-from pandas.core.series import (
-    TimedeltaSeries,
-    TimestampSeries,
-)
+from pandas.core.series import TimedeltaSeries
 
 from pandas._typing import (
     IntervalClosedType,
@@ -174,7 +171,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __gt__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __lt__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -183,7 +180,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __lt__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __ge__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -192,7 +189,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __ge__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __le__(self, other: Interval[_OrderableT]) -> bool: ...

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -17,10 +17,7 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.series import (
-    TimedeltaSeries,
-    TimestampSeries,
-)
+from pandas.core.series import TimedeltaSeries
 from typing_extensions import (
     Self,
     TypeAlias,
@@ -167,7 +164,7 @@ class Timedelta(timedelta):
         other: TimedeltaSeries,
     ) -> TimedeltaSeries: ...
     @overload
-    def __add__(self, other: TimestampSeries) -> TimestampSeries: ...
+    def __add__(self, other: Series[Timestamp]) -> Series[Timestamp]: ...
     @overload
     def __radd__(self, other: np.datetime64) -> Timestamp: ...
     @overload

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -25,7 +25,6 @@ from pandas import (
 from pandas.core.series import (
     Series,
     TimedeltaSeries,
-    TimestampSeries,
 )
 from typing_extensions import (
     Never,
@@ -172,31 +171,31 @@ class Timestamp(datetime, SupportsIndex):
         self, other: DatetimeIndex | npt.NDArray[np.datetime64]
     ) -> np_ndarray_bool: ...
     @overload
-    def __le__(self, other: TimestampSeries) -> Series[bool]: ...
+    def __le__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __lt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __lt__(
         self, other: DatetimeIndex | npt.NDArray[np.datetime64]
     ) -> np_ndarray_bool: ...
     @overload
-    def __lt__(self, other: TimestampSeries) -> Series[bool]: ...
+    def __lt__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __ge__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __ge__(
         self, other: DatetimeIndex | npt.NDArray[np.datetime64]
     ) -> np_ndarray_bool: ...
     @overload
-    def __ge__(self, other: TimestampSeries) -> Series[bool]: ...
+    def __ge__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __gt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __gt__(
         self, other: DatetimeIndex | npt.NDArray[np.datetime64]
     ) -> np_ndarray_bool: ...
     @overload
-    def __gt__(self, other: TimestampSeries) -> Series[bool]: ...
+    def __gt__(self, other: Series[Timestamp]) -> Series[bool]: ...
     # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
     @overload  # type: ignore[override]
     def __add__(
@@ -205,7 +204,7 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
-    def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
+    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
     def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
@@ -224,25 +223,25 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> TimestampSeries: ...
+    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
-    def __sub__(self, other: TimestampSeries) -> TimedeltaSeries: ...
+    def __sub__(self, other: Series[Timestamp]) -> TimedeltaSeries: ...
     @overload
     def __sub__(
         self, other: npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.datetime64]: ...
     @overload
     def __eq__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self, other: TimestampSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __eq__(self, other: Series[Timestamp]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: npt.NDArray[np.datetime64] | Index) -> np_ndarray_bool: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: object) -> Literal[False]: ...
     @overload
     def __ne__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self, other: TimestampSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __ne__(self, other: Series[Timestamp]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(self, other: npt.NDArray[np.datetime64] | Index) -> np_ndarray_bool: ...  # type: ignore[overload-overlap]
     @overload

pandas-stubs/core/indexes/accessors.pyi

@@ -4,9 +4,11 @@ from datetime import (
     tzinfo as _tzinfo,
 )
 from typing import (
+    Any,
     Generic,
     Literal,
     TypeVar,
+    overload,
 )
 
 import numpy as np
@@ -17,6 +19,7 @@ from pandas import (
     PeriodIndex,
     Timedelta,
     TimedeltaIndex,
+    Timestamp,
 )
 from pandas.core.accessor import PandasDelegate
 from pandas.core.arrays import (
@@ -29,12 +32,13 @@ from pandas.core.series import (
     PeriodSeries,
     Series,
     TimedeltaSeries,
-    TimestampSeries,
 )
+from typing_extensions import Never
 
 from pandas._libs.tslibs import BaseOffset
 from pandas._libs.tslibs.offsets import DateOffset
 from pandas._typing import (
+    S1,
     TimeAmbiguous,
     TimeNonexistent,
     TimestampConvention,
@@ -155,14 +159,13 @@ class _DatetimeLikeOps(
     ],
 ): ...
 
-# Ideally, the rounding methods would return TimestampSeries when `Series.dt.method`
+# Ideally, the rounding methods would return Series[Timestamp] when `Series.dt.method`
 # is invoked, but because of how Series.dt is hooked in and that we may not know the
 # type of the series, we don't know which kind of series was ...ed
 # in to the dt accessor
 
 _DTTimestampTimedeltaReturnType = TypeVar(
-    "_DTTimestampTimedeltaReturnType",
-    bound=Series | TimestampSeries | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
+    "_DTTimestampTimedeltaReturnType", bound=Series | DatetimeIndex | TimedeltaIndex
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -198,7 +201,7 @@ class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
     ) -> _DTTimestampTimedeltaReturnType: ...
 
 _DTNormalizeReturnType = TypeVar(
-    "_DTNormalizeReturnType", TimestampSeries, DatetimeIndex
+    "_DTNormalizeReturnType", Series[Timestamp], DatetimeIndex
 )
 _DTStrKindReturnType = TypeVar("_DTStrKindReturnType", bound=Series[str] | Index)
 _DTToPeriodReturnType = TypeVar(
@@ -320,7 +323,7 @@ class TimedeltaProperties(
     def as_unit(self, unit: TimeUnit) -> TimedeltaSeries: ...
 
 _PeriodDTReturnTypes = TypeVar(
-    "_PeriodDTReturnTypes", bound=TimestampSeries | DatetimeIndex
+    "_PeriodDTReturnTypes", bound=Series[Timestamp] | DatetimeIndex
 )
 _PeriodIntReturnTypes = TypeVar("_PeriodIntReturnTypes", bound=Series[int] | Index[int])
 _PeriodStrReturnTypes = TypeVar("_PeriodStrReturnTypes", bound=Series[str] | Index)
@@ -363,7 +366,7 @@ class PeriodIndexFieldOps(
 class PeriodProperties(
     Properties,
     _PeriodProperties[
-        TimestampSeries, Series[int], Series[str], DatetimeArray, PeriodArray
+        Series[Timestamp], Series[int], Series[str], DatetimeArray, PeriodArray
     ],
     _DatetimeFieldOps[Series[int]],
     _IsLeapYearProperty,
@@ -377,7 +380,7 @@ class CombinedDatetimelikeProperties(
         Series[dt.date],
         Series[dt.time],
         str,
-        TimestampSeries,
+        Series[Timestamp],
         Series[str],
         PeriodSeries,
     ],
@@ -388,11 +391,11 @@ class TimestampProperties(
     DatetimeProperties[
         Series[int],
         Series[bool],
-        TimestampSeries,
+        Series[Timestamp],
         Series[dt.date],
         Series[dt.time],
         str,
-        TimestampSeries,
+        Series[Timestamp],
         Series[str],
         PeriodSeries,
     ]
@@ -427,3 +430,46 @@ class TimedeltaIndexProperties(
     _TimedeltaPropertiesNoRounding[Index, Index],
     _DatetimeRoundingMethods[TimedeltaIndex],
 ): ...
+
+class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]):
+    @overload
+    def __get__(self, instance: Series[Never], owner: Any) -> Never: ...
+    @overload
+    def __get__(
+        self, instance: Series[Timestamp], owner: Any
+    ) -> TimestampProperties: ...
+    @overload
+    def __get__(
+        self, instance: Series[S1], owner: Any
+    ) -> CombinedDatetimelikeProperties: ...
+    def round(
+        self,
+        freq: str | BaseOffset | None,
+        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
+        nonexistent: (
+            Literal["shift_forward", "shift_backward", "NaT", "raise"]
+            | timedelta
+            | Timedelta
+        ) = ...,
+    ) -> Series[S1]: ...
+    def floor(
+        self,
+        freq: str | BaseOffset | None,
+        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
+        nonexistent: (
+            Literal["shift_forward", "shift_backward", "NaT", "raise"]
+            | timedelta
+            | Timedelta
+        ) = ...,
+    ) -> Series[S1]: ...
+    def ceil(
+        self,
+        freq: str | BaseOffset | None,
+        ambiguous: Literal["raise", "infer", "NaT"] | bool | np_ndarray_bool = ...,
+        nonexistent: (
+            Literal["shift_forward", "shift_backward", "NaT", "raise"]
+            | timedelta
+            | Timedelta
+        ) = ...,
+    ) -> Series[S1]: ...
+    def as_unit(self, unit: TimeUnit) -> Series[S1]: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -23,8 +23,8 @@ from pandas import (
 from pandas.core.indexes.accessors import DatetimeIndexProperties
 from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
 from pandas.core.series import (
+    Series,
     TimedeltaSeries,
-    TimestampSeries,
 )
 from typing_extensions import Self
 
@@ -60,13 +60,13 @@ class DatetimeIndex(DatetimeTimedeltaMixin[Timestamp], DatetimeIndexProperties):
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
     @overload
-    def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
+    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
     def __add__(
         self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
     ) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> TimestampSeries: ...
+    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
     def __sub__(
         self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
@@ -76,7 +76,7 @@ class DatetimeIndex(DatetimeTimedeltaMixin[Timestamp], DatetimeIndexProperties):
         self, other: datetime | Timestamp | DatetimeIndex
     ) -> TimedeltaIndex: ...
     @final
-    def to_series(self, index=..., name: Hashable = ...) -> TimestampSeries: ...
+    def to_series(self, index=..., name: Hashable = ...) -> Series[Timestamp]: ...
     def snap(self, freq: str = ...): ...
     def slice_indexer(self, start=..., end=..., step=...): ...
     def searchsorted(self, value, side: str = ..., sorter=...): ...

pandas-stubs/core/indexes/interval.pyi

@@ -15,7 +15,6 @@ from pandas import Index
 from pandas.core.indexes.extension import ExtensionIndex
 from pandas.core.series import (
     TimedeltaSeries,
-    TimestampSeries,
 )
 from typing_extensions import TypeAlias
 
@@ -53,7 +52,7 @@ _EdgesFloat: TypeAlias = (
 _EdgesTimestamp: TypeAlias = (
     Sequence[DatetimeLike]
     | npt.NDArray[np.datetime64]
-    | TimestampSeries
+    | pd.Series[pd.Timestamp]
     | pd.DatetimeIndex
 )
 _EdgesTimedelta: TypeAlias = (