refactor: also remove TimedeltaSeries

docs/philosophy.md

@@ -56,13 +56,13 @@ revealed as follows:
 ```text
 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:8: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timedeltas.Timedelta]"
 ttest.py:9: error: Need type annotation for "ssum"  [var-annotated]
 ttest.py:10: note: Revealed type is "Never"
 ```
 
 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 type `Series[Timedelta]` 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,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[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 typing_extensions import Never
 
@@ -316,11 +315,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
@@ -439,6 +438,10 @@ class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]):
         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: ...

pandas-stubs/core/indexes/datetimes.pyi

@@ -22,10 +22,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 (
@@ -60,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) -> 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

@@ -13,9 +13,6 @@ import numpy as np
 import pandas as pd
 from pandas import Index
 from pandas.core.indexes.extension import ExtensionIndex
-from pandas.core.series import (
-    TimedeltaSeries,
-)
 from typing_extensions import TypeAlias
 
 from pandas._libs.interval import (
@@ -58,7 +55,7 @@ _EdgesTimestamp: TypeAlias = (
 _EdgesTimedelta: TypeAlias = (
     Sequence[pd.Timedelta]
     | npt.NDArray[np.timedelta64]
-    | TimedeltaSeries
+    | pd.Series[pd.Timedelta]
     | pd.TimedeltaIndex
 )
 _TimestampLike: TypeAlias = pd.Timestamp | np.datetime64 | dt.datetime

pandas-stubs/core/indexes/timedeltas.pyi

@@ -19,7 +19,7 @@ from pandas.core.indexes.accessors import TimedeltaIndexProperties
 from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
 from pandas.core.indexes.datetimes import DatetimeIndex
 from pandas.core.indexes.period import PeriodIndex
-from pandas.core.series import TimedeltaSeries
+from pandas.core.series import Series
 from typing_extensions import Self
 
 from pandas._libs import (
@@ -75,7 +75,7 @@ class TimedeltaIndex(DatetimeTimedeltaMixin[Timedelta], TimedeltaIndexProperties
     @property
     def inferred_type(self) -> str: ...
     @final
-    def to_series(self, index=..., name: Hashable = ...) -> TimedeltaSeries: ...
+    def to_series(self, index=..., name: Hashable = ...) -> Series[Timedelta]: ...
     def shift(self, periods: int = ..., freq=...) -> Self: ...
 
 def timedelta_range(