refactor(series)!: ⏱️ drop TimedeltaSeries (#1273)

* refactor: only drop TimestampSeries #1273 (review)

* refactor: also remove TimedeltaSeries

* feat: add

* feat(test): sub

* feat(test): mul

* feat(test): truediv

* feat(test): floordiv

* feat(test): remove redundant

* fix: pandas-dev/pandas#62316

* fix: comments

* fix(test): ignore mypy for now

* fix: comments

* fix: comments

Author: cmp0xff

.pre-commit-config.yaml

@@ -2,16 +2,16 @@ minimum_pre_commit_version: 2.15.0
 ci:
     autofix_prs: false
 repos:
--   repo: https://github.com/python/black
-    rev: 25.1.0
+-   repo: https://github.com/psf/black
+    rev: 25.9.0
     hooks:
     -   id: black
 -   repo: https://github.com/PyCQA/isort
     rev: 6.0.1
     hooks:
     -   id: isort
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.10
+    rev: v0.13.2
     hooks:
     -   id: ruff-check
         args: [

docs/philosophy.md

@@ -55,12 +55,12 @@ revealed by `mypy` as follows:
 ```text
 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:9: note: Revealed type is "pandas.core.series.Series[pandas._libs.tslibs.timestamps.Timedelta]"
 ttest.py:10: error: Unsupported operand types for + ("Series[Timestamp]" and "Series[Timestamp]")  [operator]
 ```
 
 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()`.
 
 ### Progressive arithmetic typing for generic Series

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,
@@ -173,7 +172,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: ...
@@ -184,7 +183,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: ...
@@ -195,7 +194,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
 
@@ -86,7 +85,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
@@ -96,7 +95,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
@@ -172,7 +171,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,
@@ -162,10 +161,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
@@ -198,9 +194,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
@@ -234,9 +228,9 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
     ) -> np_ndarray[ShapeT, 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
@@ -246,9 +240,9 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.floating] | np_ndarray[ShapeT, np.integer]
     ) -> np_ndarray[ShapeT, 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: ...
@@ -269,11 +263,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
@@ -294,19 +288,19 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.integer] | np_ndarray[ShapeT, np.floating]
     ) -> np_ndarray[ShapeT, 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[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
@@ -319,7 +313,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__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
@@ -334,7 +328,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
@@ -343,8 +337,8 @@ class Timedelta(timedelta):
     ) -> np_ndarray[ShapeT, 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
@@ -358,7 +352,7 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, 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]
@@ -369,7 +363,7 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, 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]
@@ -380,7 +374,7 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, 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]
@@ -391,7 +385,7 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, 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 (
     TimedeltaIndex,
 )
 from pandas.core.indexes.base import Index
-from pandas.core.series import (
-    Series,
-    TimedeltaSeries,
-)
+from pandas.core.series import Series
 from typing_extensions import (
     Never,
     Self,
@@ -225,8 +222,6 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
-    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
-    @overload
     def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
     def __radd__(self, other: timedelta) -> Self: ...
@@ -244,8 +239,6 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
-    @overload
     def __sub__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...

pandas-stubs/core/arraylike.pyi

@@ -19,14 +19,6 @@ class OpsMixin:
     def __rxor__(self, other: Any) -> Self: ...
     # -------------------------------------------------------------
     # Arithmetic Methods
-    def __mul__(self, other: Any) -> Self: ...
-    def __rmul__(self, other: Any) -> Self: ...
-    # Handled by subclasses that specify only the valid values
-    # that can be passed
-    #  def __truediv__(self, other: Any) -> Self: ...
-    #  def __rtruediv__(self, other: Any) -> Self: ...
-    #  def __floordiv__(self, other: Any) -> Self: ...
-    #  def __rfloordiv__(self, other: Any) -> Self: ...
     def __mod__(self, other: Any) -> Self: ...
     def __rmod__(self, other: Any) -> Self: ...
     def __divmod__(self, other: Any) -> tuple[Self, Self]: ...

pandas-stubs/core/frame.pyi

@@ -763,7 +763,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     @overload
     def to_xml(
         self,
-        path_or_buffer: Literal[None] = ...,
+        path_or_buffer: None = ...,
         index: bool = ...,
         root_name: str | None = ...,
         row_name: str | None = ...,
@@ -1806,6 +1806,8 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         level: Level | None = ...,
         fill_value: float | None = None,
     ) -> Self: ...
+    def __mul__(self, other: Any) -> Self: ...
+    def __rmul__(self, other: Any) -> Self: ...
     @final
     def add_prefix(self, prefix: _str, axis: Axis | None = None) -> Self: ...
     @final

pandas-stubs/core/groupby/indexing.pyi

@@ -27,6 +27,6 @@ class GroupByNthSelector(Generic[_GroupByT]):
     def __call__(
         self,
         n: PositionalIndexer | tuple,
-        dropna: Literal["any", "all", None] = ...,
+        dropna: Literal["any", "all"] | None = ...,
     ) -> DataFrame | Series: ...
     def __getitem__(self, n: PositionalIndexer | tuple) -> DataFrame | Series: ...

pandas-stubs/core/indexes/accessors.pyi

@@ -30,7 +30,6 @@ from pandas.core.frame import DataFrame
 from pandas.core.series import (
     PeriodSeries,
     Series,
-    TimedeltaSeries,
 )
 from typing_extensions import Never
 
@@ -165,7 +164,11 @@ class _DatetimeLikeOps(
 
 _DTTimestampTimedeltaReturnType = TypeVar(
     "_DTTimestampTimedeltaReturnType",
-    bound=Series | Series[Timestamp] | TimedeltaSeries | DatetimeIndex | TimedeltaIndex,
+    bound=Series
+    | Series[Timestamp]
+    | Series[Timedelta]
+    | DatetimeIndex
+    | TimedeltaIndex,
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):
@@ -316,7 +319,7 @@ class _TimedeltaPropertiesNoRounding(
 class TimedeltaProperties(
     Properties,
     _TimedeltaPropertiesNoRounding[Series[int], Series[float]],
-    _DatetimeRoundingMethods[TimedeltaSeries],
+    _DatetimeRoundingMethods[Series[Timedelta]],
 ):
     @property
     def unit(self) -> TimeUnit: ...
@@ -440,7 +443,7 @@ class _dtDescriptor(CombinedDatetimelikeProperties, Generic[S1]):
     ) -> TimestampProperties: ...
     @overload
     def __get__(
-        self, instance: Series[Timedelta] | TimedeltaSeries, owner: Any
+        self, instance: Series[Timedelta], owner: Any
     ) -> TimedeltaProperties: ...
     @overload
     def __get__(