refactor: #718 only drop TimestampSeries

docs/philosophy.md

@@ -36,67 +36,70 @@ This also allows type checking for operations on series that contain date/time d
 the following example that creates two series of datetimes with corresponding arithmetic.
 
 ```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)
 s2 = pd.Series(pd.to_datetime(["2022-05-15", "2022-06-15"]))
 reveal_type(s2)
 td = s1 - s2
 reveal_type(td)
 ssum = s1 + s2
-reveal_type(ssum)
 ```
 
-The above code (without the `reveal_type()` statements) will raise an `Exception` 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 as follows:
+revealed by `mypy` as follows:
 
 ```text
-ttest.py:4: note: Revealed type is "pandas.core.series.TimestampSeries"
-ttest.py:6: note: Revealed type is "pandas.core.series.TimestampSeries"
-ttest.py:8: note: Revealed type is "pandas.core.series.TimedeltaSeries"
-ttest.py:10: note: Revealed type is "builtins.Exception"
+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:10: error: Unsupported operand types for + ("Series[Timestamp]" and "Series[Timestamp]")  [operator]
 ```
 
-The type `TimestampSeries` is the result of creating a series from `pd.to_datetime()`, while
-the type `TimedeltaSeries` is the result of subtracting two `TimestampSeries` as well as
+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 result of `pd.to_timedelta()`.
 
-### Generic Series have restricted arithmetic
+### Progressive arithmetic typing for generic Series
 
 Consider the following Series from a DataFrame:
 
 ```python
 import pandas as pd
 from typing_extensions import reveal_type
-from typing import TYPE_CHECKING, cast
-
-if TYPE_CHECKING:
-    from pandas.core.series import TimestampSeries  # noqa: F401
 
 
-frame = pd.DataFrame({"timestamp": [pd.Timestamp(2025, 8, 26)], "tag": ["one"], "value": [1.0]})
+frame = pd.DataFrame({"timestamp": [pd.Timestamp(2025, 9, 15)], "tag": ["one"], "value": [1.0]})
 values = frame["value"]
 reveal_type(values)  # type checker: Series[Any], runtime: Series
 new_values = values + 2
 
 timestamps = frame["timestamp"]
-reveal_type(timestamps)  # type checker: Series[Any], runtime: Series
-reveal_type(timestamps - pd.Timestamp(2025, 7, 12))  # type checker: Unknown and error, runtime: Series
-reveal_type(cast("TimestampSeries", timestamps) - pd.Timestamp(2025, 7, 12))  # type checker: TimedeltaSeries, runtime: Series
+reveal_type(timestamps - pd.Timestamp(2025, 7, 12))  # type checker: TimedeltaSeries, runtime: Series
 
 tags = frame["tag"]
-reveal_type("suffix" + tags)  # type checker: Never, runtime: Series
+reveal_type("suffix" + tags)  # type checker: Series[str], runtime: Series
 ```
 
-Since they are taken from a DataFrame, all three of them, `values`, `timestamps`
+Since these Series are taken from a DataFrame, all three of them, `values`, `timestamps`
 and `tags`, are recognized by type checkers as `Series[Any]`.  The code snippet
-runs fine at runtime. In the stub for type checking, however, we restrict
-generic Series to perform arithmetic operations only with numeric types, and
-give `Series[Any]` for the results. For `Timedelta`, `Timestamp`, `str`, etc.,
-arithmetic is restricted to `Series[Any]` and the result is either undefined, 
-showing `Unknown` and errors, or `Never`. Users are encouraged to cast such
-generic Series to ones with concrete types, so that type checkers can provide
-meaningful results.
+runs fine at runtime.  In the stub for type checking, when there is only one
+valid outcome, we provide the typing of this outcome as the result.  For
+example, if a `Timestamp` is subtracted from a `Series[Any]`, or a `str`
+is added to a `Series[Any]`, valid outcomes can only be `TimedeltaSeries` and
+`Series[str]`, respectively, which will be realized when the left operands
+are actually `Series[Timestamp]` and `Series[str]`, respectively.
+
+Note that static type checkers cannot determine the contents of a `Series[Any]`
+at runtime.  Users are invited to verify the results provided progressivly by the
+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.
 
 ### Interval is Generic
 

pandas-stubs/_libs/interval.pyi

@@ -13,10 +13,7 @@ from pandas import (
     Timedelta,
     Timestamp,
 )
-from pandas.core.series import (
-    TimedeltaSeries,
-    TimestampSeries,
-)
+from pandas.core.series import TimedeltaSeries
 
 from pandas._typing import (
     IntervalClosedType,
@@ -176,7 +173,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __gt__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __lt__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -187,7 +184,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __lt__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __ge__(self, other: Interval[_OrderableT]) -> bool: ...
@@ -198,7 +195,7 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __ge__(
         self,
-        other: Series[int] | Series[float] | TimestampSeries | TimedeltaSeries,
+        other: Series[int] | Series[float] | Series[Timestamp] | TimedeltaSeries,
     ) -> Series[bool]: ...
     @overload
     def __le__(self, other: Interval[_OrderableT]) -> bool: ...

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -17,10 +17,7 @@ from pandas import (
     Series,
     TimedeltaIndex,
 )
-from pandas.core.series import (
-    TimedeltaSeries,
-    TimestampSeries,
-)
+from pandas.core.series import TimedeltaSeries
 from typing_extensions import (
     Self,
     TypeAlias,
@@ -170,7 +167,7 @@ class Timedelta(timedelta):
         other: TimedeltaSeries,
     ) -> TimedeltaSeries: ...
     @overload
-    def __add__(self, other: TimestampSeries) -> TimestampSeries: ...
+    def __add__(self, other: Series[Timestamp]) -> Series[Timestamp]: ...
     @overload
     def __radd__(self, other: np.datetime64) -> Timestamp: ...
     @overload

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -25,7 +25,6 @@ from pandas.core.indexes.base import Index
 from pandas.core.series import (
     Series,
     TimedeltaSeries,
-    TimestampSeries,
 )
 from typing_extensions import (
     Never,
@@ -187,7 +186,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __le__(self, other: TimestampSeries) -> Series[bool]: ...
+    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
@@ -197,7 +196,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __lt__(self, other: TimestampSeries) -> Series[bool]: ...
+    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
@@ -207,7 +206,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __ge__(self, other: TimestampSeries) -> Series[bool]: ...
+    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
@@ -217,7 +216,7 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __gt__(self, other: TimestampSeries) -> Series[bool]: ...
+    def __gt__(self, other: Series[Timestamp]) -> Series[bool]: ...
     # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
     @overload  # type: ignore[override]
     def __add__(
@@ -226,7 +225,7 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
-    def __add__(self, other: TimedeltaSeries) -> TimestampSeries: ...
+    def __add__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
     def __add__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
@@ -239,23 +238,21 @@ class Timestamp(datetime, SupportsIndex):
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
     # TODO: test dt64
     @overload  # type: ignore[override]
-    def __sub__(self, other: Timestamp | datetime | np.datetime64) -> Timedelta: ...
+    def __sub__(self, other: datetime | np.datetime64) -> Timedelta: ...
     @overload
     def __sub__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
     @overload
     def __sub__(self, other: TimedeltaIndex) -> DatetimeIndex: ...
     @overload
-    def __sub__(self, other: TimedeltaSeries) -> TimestampSeries: ...
-    @overload
-    def __sub__(self, other: TimestampSeries) -> TimedeltaSeries: ...
+    def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
     def __sub__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
     @overload
     def __eq__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self, other: TimestampSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __eq__(self, other: Series[Timestamp]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
@@ -265,7 +262,7 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __ne__(self, other: Timestamp | datetime | np.datetime64) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self, other: TimestampSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
+    def __ne__(self, other: Series[Timestamp]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload