refactor(series): #718 return Never

Author: cmp0xff

pandas-stubs/core/series.pyi

@@ -183,11 +183,26 @@ from pandas.core.dtypes.dtypes import CategoricalDtype
 
 from pandas.plotting import PlotAccessor
 
+_scalar_timestamp: TypeAlias = datetime | np.datetime64 | Timestamp
+_vector_timestamp: TypeAlias = (
+    Sequence[datetime]
+    | Sequence[np.datetime64]
+    | Sequence[Timestamp]
+    | np.typing.NDArray[np.datetime64]
+    | DatetimeIndex
+)
+_nonseries_timestamp: TypeAlias = _scalar_timestamp | _vector_timestamp
+
 _scalar_timedelta: TypeAlias = timedelta | np.timedelta64 | BaseOffset | Timedelta
 _vector_timedelta: TypeAlias = (
-    Sequence[timedelta] | Sequence[Timedelta] | TimedeltaIndex
+    Sequence[timedelta]
+    | Sequence[np.timedelta64]
+    | Sequence[Timedelta]
+    | np.typing.NDArray[np.timedelta64]
+    | TimedeltaIndex
 )
 _nonseries_timedelta: TypeAlias = _scalar_timedelta | _vector_timedelta
+
 _nonseries_int: TypeAlias = int | np_ndarray_anyint | Sequence[int]
 
 _T_INT = TypeVar("_T_INT", bound=int)
@@ -1601,6 +1616,10 @@ class Series(IndexOpsMixin[S1], NDFrame):
         self: Series[_T_INT], other: _nonseries_int | Series[int]
     ) -> Series[_T_INT]: ...
     @overload
+    def __add__(
+        self: Series[Timestamp], other: _nonseries_timestamp | Series[Timestamp]
+    ) -> Never: ...
+    @overload
     def __add__(
         self: Series[_T_STAMP],
         other: _nonseries_timedelta | Series[Timedelta],
@@ -1609,8 +1628,7 @@ class Series(IndexOpsMixin[S1], NDFrame):
     def __add__(self: Series[Timedelta], other: Period) -> PeriodSeries: ...
     @overload
     def __add__(
-        self: Series[Timedelta],
-        other: datetime | Timestamp | Series[Timestamp] | DatetimeIndex,
+        self: Series[Timedelta], other: _nonseries_timestamp | Series[Timestamp]
     ) -> Series[Timestamp]: ...
     @overload
     def __add__(self, other: S1 | Self) -> Self: ...

tests/test_frame.py

@@ -2816,9 +2816,9 @@ def test_sum_get_add() -> None:
     summer = df.sum(axis=1)
     check(assert_type(summer, pd.Series), pd.Series)
 
-    check(assert_type(s + summer, pd.Series), pd.Series)
-    check(assert_type(s + df["y"], pd.Series), pd.Series)
-    check(assert_type(summer + summer, pd.Series), pd.Series)
+    check(assert_type(s + summer, pd.Series), pd.Series)  # type: ignore[assert-type]
+    check(assert_type(s + df["y"], pd.Series), pd.Series)  # type: ignore[assert-type]
+    check(assert_type(summer + summer, pd.Series), pd.Series)  # type: ignore[assert-type]
 
 
 def test_getset_untyped() -> None:

tests/test_series.py

@@ -1593,7 +1593,7 @@ def test_series_min_max_sub_axis() -> None:
     ss = s1 - s2
     sm = s1 * s2
     sd = s1 / s2
-    check(assert_type(sa, pd.Series), pd.Series)
+    check(assert_type(sa, pd.Series), pd.Series)  # type: ignore[assert-type]
     check(assert_type(ss, pd.Series), pd.Series)  # type: ignore[assert-type]
     check(assert_type(sm, pd.Series), pd.Series)
     check(assert_type(sd, pd.Series), pd.Series)

tests/test_timefuncs.py

@@ -320,9 +320,9 @@ def test_fail_on_adding_two_timestamps() -> None:
     s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
     s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
     if TYPE_CHECKING_INVALID_USAGE:
-        ssum: pd.Series = s1 + s2
+        ssum = s1 + s2  # type: ignore[var-annotated]
         ts = pd.Timestamp("2022-06-30")
-        tsum: pd.Series = s1 + ts
+        tsum = s1 + ts  # type: ignore[var-annotated]
 
 
 def test_dtindex_tzinfo() -> None: