refactor(series)!: 🕰️ drop TimestampSeries

docs/philosophy.md

@@ -99,7 +99,7 @@ type checkers and be warned if they are unreasonable.
 
 When there are several possible valid outcomes of an arithmetic expression,
 for example numeric types `Series[bool]`, `Series[int]`, etc., `Series[Any]` 
-will be given as the resulting typing.
+will be given as the resulting type of the arithmetic operation.
 
 ### Interval is Generic
 

pandas-stubs/core/series.pyi

@@ -2211,23 +2211,6 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload
     def __and__(self, other: int | np_ndarray_anyint | Series[int]) -> Series[int]: ...
     def __eq__(self, other: object) -> Series[_bool]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
-    @overload
-    def __floordiv__(
-        self: Series[Timedelta], other: float | Sequence[float]
-    ) -> TimedeltaSeries: ...
-    @overload
-    def __floordiv__(
-        self: Series[Timedelta],
-        other: (
-            timedelta
-            | np.timedelta64
-            | np_ndarray_td
-            | TimedeltaIndex
-            | Series[Timedelta]
-            | TimedeltaSeries
-        ),
-    ) -> Series[int]: ...
-    @overload
     def __floordiv__(self, other: num | _ListLike | Series[S1]) -> Series[int]: ...
     def __ge__(  # type: ignore[override]
         self, other: S1 | _ListLike | Series[S1] | datetime | timedelta | date
@@ -2750,19 +2733,6 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload
     def __rand__(self, other: int | np_ndarray_anyint | Series[int]) -> Series[int]: ...
     def __rdivmod__(self, other: num | _ListLike | Series[S1]) -> Series[S1]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
-    @overload
-    def __rfloordiv__(
-        self: Series[Timedelta],
-        other: (
-            timedelta
-            | np.timedelta64
-            | np_ndarray_td
-            | TimedeltaIndex
-            | Series[Timedelta]
-            | TimedeltaSeries
-        ),
-    ) -> Series[int]: ...
-    @overload
     def __rfloordiv__(self, other: num | _ListLike | Series[S1]) -> Series[S1]: ...
     def __rmod__(self, other: num | _ListLike | Series[S1]) -> Series[S1]: ...
     def __rpow__(self, other: num | _ListLike | Series[S1]) -> Series[S1]: ...
@@ -3034,7 +3004,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
     @overload
     def sub(
         self: Series[Timestamp],
-        other: datetime | np.datetime64 | np_ndarray_dt,
+        other: datetime | Sequence[datetime] | np.datetime64 | np_ndarray_dt,
         level: Level | None = None,
         fill_value: float | None = None,
         axis: int = 0,
@@ -3052,6 +3022,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
         self: Series[Timestamp],
         other: (
             timedelta
+            | Sequence[timedelta]
             | np.timedelta64
             | np_ndarray_td
             | TimedeltaIndex
@@ -3177,8 +3148,6 @@ class Series(IndexOpsMixin[S1], NDFrame):
             | Series[complex]
         ),
     ) -> Series[complex]: ...
-    # @overload
-    # def __rsub__(self: Series[Timestamp], other: np_ndarray_td) -> Never: ...
     @overload
     def __rsub__(
         self: Series[Timestamp], other: datetime | np.datetime64 | np_ndarray_dt
@@ -3322,18 +3291,10 @@ class Series(IndexOpsMixin[S1], NDFrame):
         fill_value: float | None = None,
         axis: int = 0,
     ) -> Series[complex]: ...
-    # @overload
-    # def rsub(
-    #     self: Series[Timestamp],
-    #     other: np_ndarray_td,
-    #     level: Level | None = None,
-    #     fill_value: float | None = None,
-    #     axis: int = 0,
-    # ) -> Never: ...
     @overload
     def rsub(
         self: Series[Timestamp],
-        other: datetime | np.datetime64 | np_ndarray_dt,
+        other: datetime | Sequence[datetime] | np.datetime64 | np_ndarray_dt,
         level: Level | None = None,
         fill_value: float | None = None,
         axis: int = 0,

pyproject.toml

@@ -36,7 +36,7 @@ types-pytz = ">= 2022.1.1"
 numpy = ">= 1.23.5"
 
 [tool.poetry.group.dev.dependencies]
-mypy = "1.17.1"
+mypy = "1.18.1"
 pandas = "2.3.2"
 pyarrow = ">=10.0.1"
 pytest = ">=7.1.2"

tests/series/arithmetic/test_sub.py

@@ -167,12 +167,10 @@ def test_sub_ts_py_datetime() -> None:
         _5 = a - left_ts  # type: ignore[operator] # pyright: ignore[reportOperatorIssue]
 
     check(assert_type(left_ts.sub(s), "TimedeltaSeries"), pd.Series, pd.Timedelta)
-    if TYPE_CHECKING_INVALID_USAGE:
-        left_ts.sub(a)  # type: ignore[arg-type] # pyright: ignore[reportArgumentType,reportCallIssue]
+    check(assert_type(left_ts.sub(a), "TimedeltaSeries"), pd.Series, pd.Timedelta)
 
     check(assert_type(left_ts.rsub(s), "TimedeltaSeries"), pd.Series, pd.Timedelta)
-    if TYPE_CHECKING_INVALID_USAGE:
-        left_ts.rsub(a)  # type: ignore[arg-type] # pyright: ignore[reportArgumentType,reportCallIssue]
+    check(assert_type(left_ts.rsub(a), "TimedeltaSeries"), pd.Series, pd.Timedelta)
 
 
 def test_sub_ts_numpy_datetime() -> None:

tests/series/arithmetic/timestamp/test_add.py

@@ -118,6 +118,8 @@ def test_add_numpy_array() -> None:
     # `Series`.
     if TYPE_CHECKING_INVALID_USAGE:
         assert_type(s + left, "npt.NDArray[np.datetime64]")
+    # Here even the dtype of `NDArray` is in the wrong direction.
+    # `np.datetime64` would be more sensible.
     check(assert_type(d + left, "npt.NDArray[np.timedelta64]"), pd.Series, pd.Timestamp)
 
     if TYPE_CHECKING_INVALID_USAGE:

tests/series/arithmetic/timestamp/test_sub.py

@@ -92,11 +92,12 @@ def test_sub_py_sequence() -> None:
         _1 = s - left  # type: ignore[operator] # pyright: ignore[reportOperatorIssue]
         _b = d - left  # type: ignore[operator] # pyright: ignore[reportOperatorIssue]
 
-        left.sub(s)  # type: ignore[call-overload] # pyright: ignore[reportArgumentType,reportCallIssue]
-        left.sub(d)  # type: ignore[call-overload] # pyright: ignore[reportArgumentType,reportCallIssue]
+    left.sub(s)
+    left.sub(d)
 
-        left.rsub(s)  # type: ignore[call-overload] # pyright: ignore[reportArgumentType,reportCallIssue]
-        left.rsub(d)  # type: ignore[call-overload] # pyright: ignore[reportArgumentType,reportCallIssue]
+    left.rsub(s)
+    if TYPE_CHECKING_INVALID_USAGE:
+        left.rsub(d)  # type: ignore[arg-type] # pyright: ignore[reportArgumentType,reportCallIssue]
 
 
 def test_sub_numpy_array() -> None: