Merge branch 'main' into hotfix/cmp0xff/gh718-drop-tss-tds

docs/philosophy.md

@@ -37,6 +37,7 @@ the following example that creates two series of datetimes with corresponding ar
 
 ```python
 import pandas as pd
+from typing import reveal_type
 
 s1 = pd.Series(pd.to_datetime(["2022-05-01", "2022-06-01"]))
 reveal_type(s1)
@@ -47,17 +48,15 @@ reveal_type(td)
 ssum = s1 + s2
 ```
 
-The above code (without the `reveal_type()` statements) will get a `Never`
-on the computation of `ssum` because it is
+The above code (without the `reveal_type()` statements) will get an error on the computation of `ssum` because it is
 inappropriate to add two series containing `Timestamp` values.  The types will be
 revealed by `mypy` 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.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"
+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.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

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -300,7 +300,7 @@ class Timedelta(timedelta):
     @overload
     def __eq__(self, other: timedelta | Timedelta | np.timedelta64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self, other: Series[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

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -21,6 +21,7 @@ from pandas import (
     DatetimeIndex,
     TimedeltaIndex,
 )
+from pandas.core.indexes.base import Index
 from pandas.core.series import Series
 from typing_extensions import (
     Never,
@@ -178,24 +179,40 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __le__(self, other: DatetimeIndex) -> np_1darray[np.bool]: ...
     @overload
+    def __le__(
+        self, other: np_ndarray[ShapeT, np.datetime64]
+    ) -> np_ndarray[ShapeT, np.bool]: ...
+    @overload
     def __le__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __lt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __lt__(self, other: DatetimeIndex) -> np_1darray[np.bool]: ...
     @overload
+    def __lt__(
+        self, other: np_ndarray[ShapeT, np.datetime64]
+    ) -> np_ndarray[ShapeT, np.bool]: ...
+    @overload
     def __lt__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __ge__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __ge__(self, other: DatetimeIndex) -> np_1darray[np.bool]: ...
     @overload
+    def __ge__(
+        self, other: np_ndarray[ShapeT, np.datetime64]
+    ) -> np_ndarray[ShapeT, np.bool]: ...
+    @overload
     def __ge__(self, other: Series[Timestamp]) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __gt__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[misc]
     @overload
     def __gt__(self, other: DatetimeIndex) -> np_1darray[np.bool]: ...
     @overload
+    def __gt__(
+        self, other: np_ndarray[ShapeT, np.datetime64]
+    ) -> np_ndarray[ShapeT, np.bool]: ...
+    @overload
     def __gt__(self, other: Series[Timestamp]) -> Series[bool]: ...
     # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
     @overload  # type: ignore[override]
@@ -205,8 +222,6 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
-    def __add__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
-    @overload
     def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
     def __radd__(self, other: timedelta) -> Self: ...
@@ -224,10 +239,6 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
-    @overload
-    def __sub__(self, other: Series[Timestamp]) -> Series[Timedelta]: ...
-    @overload
     def __sub__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...

pandas-stubs/core/indexes/accessors.pyi

@@ -163,7 +163,12 @@ class _DatetimeLikeOps(
 # in to the dt accessor
 
 _DTTimestampTimedeltaReturnType = TypeVar(
-    "_DTTimestampTimedeltaReturnType", bound=Series | DatetimeIndex | TimedeltaIndex
+    "_DTTimestampTimedeltaReturnType",
+    bound=Series
+    | Series[Timestamp]
+    | Series[Timedelta]
+    | DatetimeIndex
+    | TimedeltaIndex,
 )
 
 class _DatetimeRoundingMethods(Generic[_DTTimestampTimedeltaReturnType]):

pandas-stubs/core/indexes/datetimes.pyi

@@ -66,17 +66,10 @@ class DatetimeIndex(
 
     # various ignores needed for mypy, as we do want to restrict what can be used in
     # arithmetic for these types
-    @overload  # type: ignore[override]
-    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
-    @overload
-    def __add__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
-    @overload
-    def __add__(
-        self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset
+    def __add__(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self, other: timedelta | Timedelta | TimedeltaIndex | BaseOffset  # type: ignore[override]
     ) -> DatetimeIndex: ...
-    @overload
-    def __sub__(self, other: Series[Timedelta]) -> Series[Timestamp]: ...
-    @overload
+    @overload  # type: ignore[override]
     def __sub__(
         self,
         other: timedelta | np.timedelta64 | np_ndarray_td | TimedeltaIndex | BaseOffset,

pandas-stubs/core/indexes/timedeltas.pyi

@@ -82,7 +82,7 @@ class TimedeltaIndex(
     def inferred_type(self) -> str: ...
     @final
     def to_series(self, index=..., name: Hashable = ...) -> Series[Timedelta]: ...
-    def shift(self, periods: int = ..., freq=...) -> Self: ...
+    def shift(self, periods: int = 1, freq=...) -> Self: ...
 
 @overload
 def timedelta_range(