refactor: #718 only drop TimestampSeries

docs/philosophy.md

@@ -36,29 +36,31 @@ 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
+from typing import reveal_type
+
 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"]))
 reveal_type(s2)
 td = s1 - s2
 reveal_type(td)
 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 an error on the computation of `ssum` because it is
 inappropriate to add two series containing `Timestamp` values.  The types will be
-revealed as follows:
+revealed by `mypy` 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:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
-ttest.py:10: note: Revealed type is "builtins.Exception"
+ttest.py:5: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
+ttest.py:7: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timestamp]"
+ttest.py:9: note: Revealed type is "pandas.core.series.TimedeltaSeries"
+ttest.py:10: error: Unsupported operand types for + ("Series[Timestamp]" and "Series[Timestamp]")  [operator]
 ```
 
-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,
@@ -176,7 +173,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: ...
@@ -187,7 +184,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: ...
@@ -198,7 +195,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,
@@ -170,7 +167,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,
@@ -187,7 +186,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.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
@@ -197,7 +196,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.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
@@ -207,7 +206,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.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
@@ -217,7 +216,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.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__(
@@ -226,7 +225,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
@@ -245,17 +244,19 @@ 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[Never]) -> Series: ...
+    @overload
+    def __sub__(self, other: Series[Timestamp]) -> Series[Timedelta]: ...
     @overload
     def __sub__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, 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: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
@@ -265,7 +266,7 @@ class Timestamp(datetime, SupportsIndex):
     @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: Index) -> np_1darray[np.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
@@ -16,6 +18,7 @@ from pandas import (
     PeriodIndex,
     Timedelta,
     TimedeltaIndex,
+    Timestamp,
 )
 from pandas.core.accessor import PandasDelegate
 from pandas.core.arrays import (
@@ -28,12 +31,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,
@@ -154,14 +158,14 @@ 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,
+    bound=Series | Series[Timestamp] | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -197,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(
@@ -316,10 +320,10 @@ class TimedeltaProperties(
 ):
     @property
     def unit(self) -> TimeUnit: ...
-    def as_unit(self, unit: TimeUnit) -> TimedeltaSeries: ...
+    def as_unit(self, unit: TimeUnit) -> Series[Timedelta]: ...
 
 _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)
@@ -362,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,
@@ -376,7 +380,7 @@ class CombinedDatetimelikeProperties(
         Series[dt.date],
         Series[dt.time],
         str,
-        TimestampSeries,
+        Series[Timestamp],
         Series[str],
         PeriodSeries,
     ],
@@ -387,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,
     ]
@@ -426,3 +430,50 @@ 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[Timedelta], owner: Any
+    ) -> TimedeltaProperties: ...
+    @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
 
@@ -62,13 +62,13 @@ class DatetimeIndex(
     # 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
@@ -78,7 +78,7 @@ class DatetimeIndex(
         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
 
@@ -54,7 +53,7 @@ _EdgesFloat: TypeAlias = (
 _EdgesTimestamp: TypeAlias = (
     Sequence[DatetimeLike]
     | npt.NDArray[np.datetime64]
-    | TimestampSeries
+    | pd.Series[pd.Timestamp]
     | pd.DatetimeIndex
 )
 _EdgesTimedelta: TypeAlias = (