fix: #718 also remove TimedeltaSeries

Author: cmp0xff

docs/philosophy.md

@@ -32,29 +32,6 @@ the type of `lt` is `Series[bool]`.  This allows further type checking to occur
 pandas methods.  Note that in the above example, `s` is just typed as `Series` (which
 defaults to `Series[Any]`) because its type cannot be statically inferred.
 
-This also allows type checking for operations on series that contain date/time data.  Consider
-the following example that creates two series of datetimes with corresponding arithmetic.
-
-```python
-s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
-s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
-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
-inappropriate to add two series containing `Timestamp` values.  The types will be
-revealed as follows:
-
-```text
-ttest.py:3: note: Revealed type is "pandas.core.series.TimedeltaSeries"
-ttest.py:5: note: Revealed type is "builtins.Exception"
-```
-
-The type `TimedeltaSeries` is the result of `pd.to_timedelta()`.
-
 ### Interval is Generic
 
 A pandas `Interval` can be a time interval, an interval of integers, or an interval of

pandas-stubs/_libs/interval.pyi

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

pandas-stubs/_libs/tslibs/period.pyi

@@ -15,7 +15,6 @@ from pandas import (
 from pandas.core.series import (
     OffsetSeries,
     PeriodSeries,
-    TimedeltaSeries,
 )
 from typing_extensions import TypeAlias
 
@@ -82,7 +81,7 @@ class Period(PeriodMixin):
     @overload
     def __sub__(self, other: PeriodIndex) -> Index: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> PeriodSeries: ...
+    def __sub__(self, other: Series[Timedelta]) -> PeriodSeries: ...
     @overload
     def __sub__(self, other: TimedeltaIndex) -> PeriodIndex: ...
     @overload
@@ -92,7 +91,7 @@ class Period(PeriodMixin):
     @overload
     def __add__(self, other: Index) -> PeriodIndex: ...
     @overload
-    def __add__(self, other: OffsetSeries | TimedeltaSeries) -> PeriodSeries: ...
+    def __add__(self, other: OffsetSeries | Series[Timedelta]) -> PeriodSeries: ...
     #  ignore[misc] here because we know all other comparisons
     #  are False, so we use Literal[False]
     @overload
@@ -148,7 +147,7 @@ class Period(PeriodMixin):
     @overload
     def __radd__(self, other: Index) -> Index: ...
     @overload
-    def __radd__(self, other: TimedeltaSeries) -> PeriodSeries: ...
+    def __radd__(self, other: Series[Timedelta]) -> PeriodSeries: ...
     @overload
     def __radd__(self, other: NaTType) -> NaTType: ...
     @property

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -17,7 +17,6 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.series import TimedeltaSeries
 from typing_extensions import (
     Self,
     TypeAlias,
@@ -159,10 +158,7 @@ class Timedelta(timedelta):
     @overload
     def __add__(self, other: pd.TimedeltaIndex) -> pd.TimedeltaIndex: ...
     @overload
-    def __add__(
-        self,
-        other: TimedeltaSeries,
-    ) -> TimedeltaSeries: ...
+    def __add__(self, other: Series[Timedelta]) -> Series[Timedelta]: ...
     @overload
     def __add__(self, other: Series[Timestamp]) -> Series[Timestamp]: ...
     @overload
@@ -195,9 +191,7 @@ class Timedelta(timedelta):
     @overload
     def __sub__(self, other: pd.TimedeltaIndex) -> TimedeltaIndex: ...
     @overload
-    def __sub__(
-        self, other: TimedeltaSeries | Series[pd.Timedelta]
-    ) -> TimedeltaSeries: ...
+    def __sub__(self, other: Series[pd.Timedelta]) -> Series[pd.Timedelta]: ...
     @overload
     def __rsub__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
     @overload
@@ -231,9 +225,9 @@ class Timedelta(timedelta):
         self, other: npt.NDArray[np.integer] | npt.NDArray[np.floating]
     ) -> npt.NDArray[np.timedelta64]: ...
     @overload
-    def __mul__(self, other: Series[int]) -> TimedeltaSeries: ...
+    def __mul__(self, other: Series[int]) -> Series[Timedelta]: ...
     @overload
-    def __mul__(self, other: Series[float]) -> TimedeltaSeries: ...
+    def __mul__(self, other: Series[float]) -> Series[Timedelta]: ...
     @overload
     def __mul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     @overload
@@ -243,9 +237,9 @@ class Timedelta(timedelta):
         self, other: npt.NDArray[np.floating] | npt.NDArray[np.integer]
     ) -> npt.NDArray[np.timedelta64]: ...
     @overload
-    def __rmul__(self, other: Series[int]) -> TimedeltaSeries: ...
+    def __rmul__(self, other: Series[int]) -> Series[Timedelta]: ...
     @overload
-    def __rmul__(self, other: Series[float]) -> TimedeltaSeries: ...
+    def __rmul__(self, other: Series[float]) -> Series[Timedelta]: ...
     # maybe related to https://github.com/python/mypy/issues/10755
     @overload
     def __rmul__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
@@ -266,11 +260,11 @@ class Timedelta(timedelta):
     @overload
     def __floordiv__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     @overload
-    def __floordiv__(self, other: Series[int]) -> TimedeltaSeries: ...
+    def __floordiv__(self, other: Series[int]) -> Series[Timedelta]: ...
     @overload
-    def __floordiv__(self, other: Series[float]) -> TimedeltaSeries: ...
+    def __floordiv__(self, other: Series[float]) -> Series[Timedelta]: ...
     @overload
-    def __floordiv__(self, other: TimedeltaSeries) -> Series[int]: ...
+    def __floordiv__(self, other: Series[Timedelta]) -> Series[int]: ...
     @overload
     def __floordiv__(self, other: NaTType | None) -> float: ...
     @overload
@@ -291,19 +285,19 @@ class Timedelta(timedelta):
         self, other: npt.NDArray[np.integer] | npt.NDArray[np.floating]
     ) -> npt.NDArray[np.timedelta64]: ...
     @overload
-    def __truediv__(self, other: TimedeltaSeries) -> Series[float]: ...
+    def __truediv__(self, other: Series[Timedelta]) -> Series[float]: ...
     @overload
-    def __truediv__(self, other: Series[int]) -> TimedeltaSeries: ...
+    def __truediv__(self, other: Series[int]) -> Series[Timedelta]: ...
     @overload
-    def __truediv__(self, other: Series[float]) -> TimedeltaSeries: ...
+    def __truediv__(self, other: Series[float]) -> Series[Timedelta]: ...
     @overload
     def __truediv__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     def __rtruediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
     # Override due to more types supported than dt.timedelta
     @overload
     def __eq__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __eq__(self, other: Series[Timedelta] | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(  # type: ignore[overload-overlap]
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
@@ -314,7 +308,7 @@ class Timedelta(timedelta):
     @overload
     def __ne__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __ne__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(  # type: ignore[overload-overlap]
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
@@ -327,7 +321,7 @@ class Timedelta(timedelta):
     @overload
     def __mod__(self, other: float) -> Timedelta: ...
     @overload
-    def __mod__(self, other: Series[int] | Series[float]) -> TimedeltaSeries: ...
+    def __mod__(self, other: Series[int] | Series[float]) -> Series[Timedelta]: ...
     @overload
     def __mod__(self, other: Index[int] | Index[float]) -> TimedeltaIndex: ...
     @overload
@@ -336,8 +330,8 @@ class Timedelta(timedelta):
     ) -> npt.NDArray[np.timedelta64]: ...
     @overload
     def __mod__(
-        self, other: Series[int] | Series[float] | TimedeltaSeries
-    ) -> TimedeltaSeries: ...
+        self, other: Series[int] | Series[float] | Series[Timedelta]
+    ) -> Series[Timedelta]: ...
     def __divmod__(self, other: timedelta) -> tuple[int, Timedelta]: ...
     # Mypy complains Forward operator "<inequality op>" is not callable, so ignore misc
     # for le, lt ge and gt
@@ -349,7 +343,7 @@ class Timedelta(timedelta):
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __le__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
+    def __le__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
     def __lt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
@@ -358,7 +352,7 @@ class Timedelta(timedelta):
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __lt__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
+    def __lt__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
     def __ge__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
@@ -367,7 +361,7 @@ class Timedelta(timedelta):
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __ge__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
+    def __ge__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
     def __gt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
@@ -376,7 +370,7 @@ class Timedelta(timedelta):
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __gt__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
+    def __gt__(self, other: Series[pd.Timedelta]) -> Series[bool]: ...
     def __hash__(self) -> int: ...
     def isoformat(self) -> str: ...
     def to_numpy(self) -> np.timedelta64: ...

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -22,10 +22,7 @@ from pandas import (
     Index,
     TimedeltaIndex,
 )
-from pandas.core.series import (
-    Series,
-    TimedeltaSeries,
-)
+from pandas.core.series import Series
 from typing_extensions import (
     Never,
     Self,
@@ -204,7 +201,7 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
-    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
+    def __add__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
     @overload
     def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
@@ -223,9 +220,9 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
+    def __sub__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
     @overload
-    def __sub__(self, other: Series[Timestamp]) -> TimedeltaSeries: ...
+    def __sub__(self, other: Series[Timestamp]) -> Series[Timedelta]: ...
     @overload
     def __sub__(
         self, other: npt.NDArray[np.timedelta64]

pandas-stubs/core/indexes/accessors.pyi

@@ -31,7 +31,6 @@ from pandas.core.frame import DataFrame
 from pandas.core.series import (
     PeriodSeries,
     Series,
-    TimedeltaSeries,
 )
 
 from pandas._libs.tslibs import BaseOffset
@@ -164,7 +163,7 @@ class _DatetimeLikeOps(
 
 _DTTimestampTimedeltaReturnType = TypeVar(
     "_DTTimestampTimedeltaReturnType",
-    bound=Series | Series[Timestamp] | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
+    bound=Series | Series[Timestamp] | DatetimeIndex | TimedeltaIndex,
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -315,11 +314,11 @@ class _TimedeltaPropertiesNoRounding(
 class TimedeltaProperties(
     Properties,
     _TimedeltaPropertiesNoRounding[Series[int], Series[float]],
-    _DatetimeRoundingMethods[TimedeltaSeries],
+    _DatetimeRoundingMethods[Series[Timedelta]],
 ):
     @property
     def unit(self) -> TimeUnit: ...
-    def as_unit(self, unit: TimeUnit) -> TimedeltaSeries: ...
+    def as_unit(self, unit: TimeUnit) -> Series[Timedelta]: ...
 
 _PeriodDTReturnTypes = TypeVar(
     "_PeriodDTReturnTypes", bound=Series[Timestamp] | DatetimeIndex
@@ -436,6 +435,10 @@ class _dtDescriptor:
         self, instance: Series[Timestamp], owner: Any
     ) -> TimestampProperties: ...
     @overload
+    def __get__(
+        self, instance: Series[Timedelta], owner: Any
+    ) -> TimedeltaProperties: ...
+    @overload
     def __get__(
         self, instance: Series, owner: Any
     ) -> CombinedDatetimelikeProperties: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -19,10 +19,7 @@ from pandas import (
 )
 from pandas.core.indexes.accessors import DatetimeIndexProperties
 from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
-from pandas.core.series import (
-    Series,
-    TimedeltaSeries,
-)
+from pandas.core.series import Series
 from typing_extensions import Self
 
 from pandas._typing import (
@@ -57,13 +54,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) -> Series[Timestamp]: ...
+    def __add__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
     @overload
     def __add__(
         self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
     ) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
+    def __sub__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
     @overload
     def __sub__(
         self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset

pandas-stubs/core/indexes/interval.pyi

@@ -10,15 +10,8 @@ from typing import (
 
 import numpy as np
 import pandas as pd
-from pandas import (
-    Index,
-    Timestamp,
-)
+from pandas import Index
 from pandas.core.indexes.extension import ExtensionIndex
-from pandas.core.series import (
-    Series,
-    TimedeltaSeries,
-)
 from typing_extensions import TypeAlias
 
 from pandas._libs.interval import (
@@ -55,13 +48,13 @@ _EdgesFloat: TypeAlias = (
 _EdgesTimestamp: TypeAlias = (
     Sequence[DatetimeLike]
     | npt.NDArray[np.datetime64]
-    | Series[Timestamp]
+    | pd.Series[pd.Timestamp]
     | pd.DatetimeIndex
 )
 _EdgesTimedelta: TypeAlias = (
     Sequence[pd.Timedelta]
     | npt.NDArray[np.timedelta64]
-    | TimedeltaSeries
+    | pd.Series[pd.Timedelta]
     | pd.TimedeltaIndex
 )
 _TimestampLike: TypeAlias = pd.Timestamp | np.datetime64 | dt.datetime