fix: #718 attempt to drop TimestampSeries

Author: cmp0xff

docs/philosophy.md

@@ -37,9 +37,7 @@ the following example that creates two series of datetimes with corresponding ar
 
 ```python
 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
@@ -51,15 +49,11 @@ inappropriate to add two series containing `Timestamp` values.  The types will b
 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:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
-ttest.py:10: note: Revealed type is "builtins.Exception"
+ttest.py:3: note: Revealed type is "pandas.core.series.TimedeltaSeries"
+ttest.py:5: note: Revealed type is "builtins.Exception"
 ```
 
-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 result of `pd.to_timedelta()`.
+The type `TimedeltaSeries` is 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,7 +32,6 @@ from pandas.core.series import (
     PeriodSeries,
     Series,
     TimedeltaSeries,
-    TimestampSeries,
 )
 
 from pandas._libs.tslibs import BaseOffset
@@ -162,7 +164,7 @@ class _DatetimeLikeOps(
 
 _DTTimestampTimedeltaReturnType = TypeVar(
     "_DTTimestampTimedeltaReturnType",
-    bound=Series | TimestampSeries | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
+    bound=Series | Series[Timestamp] | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -198,7 +200,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 +322,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 +365,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 +379,7 @@ class CombinedDatetimelikeProperties(
         Series[dt.date],
         Series[dt.time],
         str,
-        TimestampSeries,
+        Series[Timestamp],
         Series[str],
         PeriodSeries,
     ],
@@ -388,11 +390,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 +429,13 @@ class TimedeltaIndexProperties(
     _TimedeltaPropertiesNoRounding[Index, Index],
     _DatetimeRoundingMethods[TimedeltaIndex],
 ): ...
+
+class _dtDescriptor:
+    @overload
+    def __get__(
+        self, instance: Series[Timestamp], owner: Any
+    ) -> TimestampProperties: ...
+    @overload
+    def __get__(
+        self, instance: Series, owner: Any
+    ) -> CombinedDatetimelikeProperties: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -20,8 +20,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
 
@@ -57,13 +57,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
@@ -72,7 +72,7 @@ class DatetimeIndex(DatetimeTimedeltaMixin[Timestamp], DatetimeIndexProperties):
     def __sub__(
         self, other: datetime | Timestamp | DatetimeIndex
     ) -> TimedeltaIndex: ...
-    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

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

pandas-stubs/core/reshape/tile.pyi

@@ -15,7 +15,6 @@ from pandas import (
     Series,
     Timestamp,
 )
-from pandas.core.series import TimestampSeries
 
 from pandas._typing import (
     IntervalT,
@@ -51,10 +50,10 @@ def cut(
 ) -> tuple[npt.NDArray[np.intp], IntervalIndex[IntervalT]]: ...
 @overload
 def cut(  # pyright: ignore[reportOverlappingOverload]
-    x: TimestampSeries,
+    x: Series[Timestamp],
     bins: (
         int
-        | TimestampSeries
+        | Series[Timestamp]
         | DatetimeIndex
         | Sequence[Timestamp]
         | Sequence[np.datetime64]
@@ -70,7 +69,7 @@ def cut(  # pyright: ignore[reportOverlappingOverload]
 ) -> tuple[Series, DatetimeIndex]: ...
 @overload
 def cut(
-    x: TimestampSeries,
+    x: Series[Timestamp],
     bins: IntervalIndex[Interval[Timestamp]],
     right: bool = ...,
     labels: Sequence[Label] | None = ...,
@@ -156,10 +155,10 @@ def cut(
 ) -> npt.NDArray[np.intp]: ...
 @overload
 def cut(
-    x: TimestampSeries,
+    x: Series[Timestamp],
     bins: (
         int
-        | TimestampSeries
+        | Series[Timestamp]
         | DatetimeIndex
         | Sequence[Timestamp]
         | Sequence[np.datetime64]