ENH: Improve typing for Timedelta

pandas-stubs/_libs/tslibs/period.pyi

@@ -63,16 +63,16 @@ class PeriodMixin:
 class Period(PeriodMixin):
     def __init__(
         self,
-        value: Any = ...,
-        freq: Any = ...,
-        ordinal: Any = ...,
-        year: Any = ...,
-        month: int = ...,
-        quarter: Any = ...,
-        day: int = ...,
-        hour: int = ...,
-        minute: int = ...,
-        second: int = ...,
+        value: Period | str | None = ...,
+        freq: str | BaseOffset | None = ...,
+        ordinal: int | None = ...,
+        year: int | None = ...,
+        month: int | None = ...,
+        quarter: int | None = ...,
+        day: int | None = ...,
+        hour: int | None = ...,
+        minute: int | None = ...,
+        second: int | None = ...,
     ) -> None: ...
     @overload
     def __sub__(self, other: _PeriodAddSub) -> Period: ...

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -19,7 +19,10 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.series import TimedeltaSeries
+from pandas.core.series import (
+    TimedeltaSeries,
+    TimestampSeries,
+)
 from typing_extensions import TypeAlias
 
 from pandas._libs.tslibs import (
@@ -135,7 +138,7 @@ class Timedelta(timedelta):
     def resolution_string(self) -> str: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __add__(self, other: timedelta | np.timedelta64) -> Timedelta: ...
+    def __add__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
     @overload
     def __add__(self, other: dt.datetime | np.datetime64 | Timestamp) -> Timestamp: ...
     @overload
@@ -159,11 +162,17 @@ class Timedelta(timedelta):
     @overload
     def __add__(self, other: pd.TimedeltaIndex) -> pd.TimedeltaIndex: ...
     @overload
-    def __add__(self, other: pd.Series) -> pd.Series: ...
+    def __add__(
+        self, other: TimedeltaSeries | Series[pd.Timedelta]
+    ) -> TimedeltaSeries: ...
+    @overload
+    def __add__(
+        self, other: Series[Timestamp] | TimestampSeries
+    ) -> TimestampSeries: ...
     @overload
     def __radd__(self, other: np.datetime64) -> Timestamp: ...
     @overload
-    def __radd__(self, other: timedelta | np.timedelta64) -> Timedelta: ...
+    def __radd__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
     @overload
     def __radd__(self, other: NaTType) -> NaTType: ...
     @overload
@@ -180,7 +189,7 @@ class Timedelta(timedelta):
     def __radd__(self, other: pd.PeriodIndex) -> pd.PeriodIndex: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __sub__(self, other: timedelta | np.timedelta64) -> Timedelta: ...
+    def __sub__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
     @overload
     def __sub__(self, other: NaTType) -> NaTType: ...
     @overload
@@ -190,9 +199,11 @@ class Timedelta(timedelta):
     @overload
     def __sub__(self, other: pd.TimedeltaIndex) -> TimedeltaIndex: ...
     @overload
-    def __sub__(self, other: pd.Series) -> pd.Series: ...
+    def __sub__(
+        self, other: TimedeltaSeries | Series[pd.Timedelta]
+    ) -> TimedeltaSeries: ...
     @overload
-    def __rsub__(self, other: timedelta | np.timedelta64) -> Timedelta: ...
+    def __rsub__(self, other: timedelta | Timedelta | np.timedelta64) -> Timedelta: ...
     @overload
     def __rsub__(self, other: Timestamp | np.datetime64) -> Timestamp: ...
     @overload
@@ -240,7 +251,7 @@ class Timedelta(timedelta):
     # Override due to more types supported than dt.timedelta
     # error: Signature of "__floordiv__" incompatible with supertype "timedelta"
     @overload  # type: ignore[override]
-    def __floordiv__(self, other: timedelta) -> int: ...
+    def __floordiv__(self, other: timedelta | Timedelta | np.timedelta64) -> int: ...
     @overload
     def __floordiv__(self, other: float) -> Timedelta: ...
     @overload
@@ -250,59 +261,69 @@ class Timedelta(timedelta):
     @overload
     def __floordiv__(
         self, other: npt.NDArray[np.timedelta64]
-    ) -> npt.NDArray[np.number]: ...
+    ) -> npt.NDArray[np.int_]: ...
     @overload
     def __floordiv__(self, other: Int64Index | Float64Index) -> TimedeltaIndex: ...
     @overload
     def __floordiv__(self, other: Series[int]) -> TimedeltaSeries: ...
     @overload
     def __floordiv__(self, other: Series[float]) -> TimedeltaSeries: ...
     @overload
+    def __floordiv__(
+        self, other: Series[Timedelta] | TimedeltaSeries
+    ) -> Series[int]: ...
+    @overload
     def __floordiv__(self, other: NaTType | None) -> float: ...
     @overload
-    def __rfloordiv__(self, other: timedelta | str) -> int: ...
+    def __rfloordiv__(self, other: timedelta | Timedelta | str) -> int: ...
     @overload
     def __rfloordiv__(self, other: NaTType | None) -> float: ...
     @overload
     def __rfloordiv__(
         self, other: npt.NDArray[np.timedelta64]
-    ) -> npt.NDArray[np.number]: ...
+    ) -> npt.NDArray[np.int_]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __truediv__(self, other: timedelta | NaTType) -> float: ...
+    def __truediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
     @overload
     def __truediv__(self, other: float) -> Timedelta: ...
     @overload
     def __truediv__(
         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] | TimedeltaSeries
+    ) -> Series[float]: ...
     @overload
     def __truediv__(self, other: Series[int]) -> TimedeltaSeries: ...
     @overload
     def __truediv__(self, other: Series[float]) -> TimedeltaSeries: ...
     @overload
     def __truediv__(self, other: Int64Index | Float64Index) -> TimedeltaIndex: ...
-    def __rtruediv__(self, other: timedelta | NaTType) -> float: ...
+    def __rtruediv__(self, other: timedelta | Timedelta | NaTType) -> float: ...
     # Override due to more types supported than dt.timedelta
-    @overload  # type: ignore[override]
-    def __eq__(self, other: timedelta | np.timedelta64) -> bool: ...
     @overload
-    def __eq__(self, other: TimedeltaSeries) -> Series[bool]: ...
+    def __eq__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
+    @overload
+    def __eq__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[misc]
     @overload
-    def __eq__(
+    def __eq__(  # type: ignore[misc]
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
+    @overload
+    def __eq__(self, other: object) -> Literal[False]: ...
     # Override due to more types supported than dt.timedelta
-    @overload  # type: ignore[override]
-    def __ne__(self, other: timedelta | np.timedelta64) -> bool: ...
     @overload
-    def __ne__(self, other: TimedeltaSeries) -> Series[bool]: ...
+    def __ne__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
-    def __ne__(
+    def __ne__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[misc]
+    @overload
+    def __ne__(  # type: ignore[misc]
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
+    @overload
+    def __ne__(self, other: object) -> Literal[True]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
     def __mod__(self, other: timedelta) -> Timedelta: ...
@@ -317,47 +338,48 @@ class Timedelta(timedelta):
         self, other: npt.NDArray[np.integer] | npt.NDArray[np.floating]
     ) -> npt.NDArray[np.timedelta64]: ...
     @overload
-    def __mod__(self, other: Series) -> Series: ...
+    def __mod__(
+        self, other: Series[int] | Series[float] | Series[Timedelta] | TimedeltaSeries
+    ) -> TimedeltaSeries: ...
     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
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __le__(self, other: timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
+    def __le__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
     def __le__(
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __le__(self, other: TimedeltaSeries) -> Series[bool]: ...
+    def __le__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __lt__(self, other: timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
+    def __lt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
     def __lt__(
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __lt__(self, other: TimedeltaSeries) -> Series[bool]: ...
+    def __lt__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __ge__(self, other: timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
+    def __ge__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
     def __ge__(
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __ge__(self, other: TimedeltaSeries) -> Series[bool]: ...
+    def __ge__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
     # Override due to more types supported than dt.timedelta
     @overload  # type: ignore[override]
-    def __gt__(self, other: timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
+    def __gt__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[misc]
     @overload
     def __gt__(
         self, other: TimedeltaIndex | npt.NDArray[np.timedelta64]
     ) -> npt.NDArray[np.bool_]: ...
     @overload
-    def __gt__(self, other: TimedeltaSeries) -> Series[bool]: ...
-    def __hash__(self) -> int: ...
+    def __gt__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...
     def isoformat(self) -> str: ...
     def to_numpy(self) -> np.timedelta64: ...
     @property

pandas-stubs/core/indexes/timedeltas.pyi

@@ -1,9 +1,12 @@
+import datetime as dt
 from typing import (
     Hashable,
     Literal,
+    Sequence,
     overload,
 )
 
+import numpy as np
 from pandas import (
     DateOffset,
     Period,
@@ -20,31 +23,24 @@ from pandas._libs import (
 )
 from pandas._libs.tslibs import BaseOffset
 from pandas._typing import (
+    AnyArrayLike,
     TimedeltaConvertibleTypes,
     num,
 )
 
 class TimedeltaIndex(DatetimeTimedeltaMixin, TimedeltaIndexProperties):
     def __init__(
         self,
-        data=...,
+        data: AnyArrayLike
+        | list[str]
+        | Sequence[dt.timedelta | Timedelta | np.timedelta64 | float] = ...,
         unit: Literal["D", "h", "m", "s", "ms", "us", "ns"] = ...,
         freq: str | BaseOffset = ...,
         closed: object = ...,
-        dtype=...,
+        dtype: Literal["<m8[ns]"] = ...,
         copy: bool = ...,
         name: str = ...,
     ): ...
-    def __new__(
-        cls,
-        data=...,
-        unit=...,
-        freq=...,
-        closed=...,
-        dtype=...,
-        copy: bool = ...,
-        name=...,
-    ): ...
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
     @overload  # type: ignore[override]

pandas-stubs/core/series.pyi

@@ -1741,6 +1741,8 @@ class TimedeltaSeries(Series[Timedelta]):
     def __add__(self, other: Period) -> PeriodSeries: ...
     @overload
     def __add__(self, other: Timestamp | DatetimeIndex) -> TimestampSeries: ...
+    @overload
+    def __add__(self, other: Timedelta) -> TimedeltaSeries: ...
     def __radd__(self, pther: Timestamp | TimestampSeries) -> TimestampSeries: ...  # type: ignore[override]
     def __mul__(self, other: num) -> TimedeltaSeries: ...  # type: ignore[override]
     def __sub__(  # type: ignore[override]