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

Author: cmp0xff

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
     hooks:
     -   id: isort
 -   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.12.3
+    rev: v0.12.10
     hooks:
     -   id: ruff-check
         args: [

docs/philosophy.md

@@ -63,6 +63,43 @@ The type `Series[Timestamp]` is the result of creating a series from `pd.to_date
 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
+
+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]})
+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
+
+tags = frame["tag"]
+reveal_type("suffix" + tags)  # type checker: Never, runtime: Series
+```
+
+Since they 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.
+
 ### Interval is Generic
 
 A pandas `Interval` can be a time interval, an interval of integers, or an interval of

pandas-stubs/_libs/tslibs/offsets.pyi

@@ -89,8 +89,7 @@ class BaseOffset:
     @property
     def nanos(self) -> int: ...
 
-class SingleConstructorOffset(BaseOffset):
-    def __reduce__(self): ...
+class SingleConstructorOffset(BaseOffset): ...
 
 class Tick(SingleConstructorOffset):
     def __init__(self, n: int = ..., normalize: bool = ...) -> None: ...

pandas-stubs/_libs/tslibs/period.pyi

@@ -102,7 +102,7 @@ class Period(PeriodMixin):
     @overload
     def __eq__(self, other: Period) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self, other: PeriodIndex) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
+    def __eq__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: PeriodSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
@@ -154,7 +154,7 @@ class Period(PeriodMixin):
     @overload
     def __ne__(self, other: Period) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self, other: PeriodIndex) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
+    def __ne__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(self, other: PeriodSeries) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -308,7 +308,7 @@ class Timedelta(timedelta):
     @overload
     def __eq__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
-    def __eq__(self, other: TimedeltaIndex) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
+    def __eq__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(  # type: ignore[overload-overlap]
         self, other: np_ndarray[ShapeT, np.timedelta64]
@@ -321,7 +321,7 @@ class Timedelta(timedelta):
     @overload
     def __ne__(self, other: TimedeltaSeries | Series[pd.Timedelta]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
-    def __ne__(self, other: TimedeltaIndex) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
+    def __ne__(self, other: Index) -> np_1darray[np.bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __ne__(  # type: ignore[overload-overlap]
         self, other: np_ndarray[ShapeT, np.timedelta64]

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -19,9 +19,9 @@ from typing import (
 import numpy as np
 from pandas import (
     DatetimeIndex,
-    Index,
     TimedeltaIndex,
 )
+from pandas.core.indexes.base import Index
 from pandas.core.series import (
     Series,
     TimedeltaSeries,
@@ -246,10 +246,6 @@ class Timestamp(datetime, SupportsIndex):
     @overload
     def __sub__(self, other: TimedeltaSeries) -> Series[Timestamp]: ...
     @overload
-    def __sub__(self, other: Series[Never]) -> Series: ...
-    @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/_typing.pyi

@@ -893,7 +893,7 @@ IndexingInt: TypeAlias = (
 )
 
 # AxesData is used for data for Index
-AxesData: TypeAlias = Mapping[S3, Any] | Axes | KeysView
+AxesData: TypeAlias = Mapping[S3, Any] | Axes | KeysView[S3]
 
 # Any plain Python or numpy function
 Function: TypeAlias = np.ufunc | Callable[..., Any]

pandas-stubs/core/arraylike.pyi

@@ -21,8 +21,6 @@ class OpsMixin:
     # Arithmetic Methods
     def __add__(self, other: Any) -> Self: ...
     def __radd__(self, other: Any) -> Self: ...
-    def __sub__(self, other: Any) -> Self: ...
-    def __rsub__(self, other: Any) -> Self: ...
     def __mul__(self, other: Any) -> Self: ...
     def __rmul__(self, other: Any) -> Self: ...
     # Handled by subclasses that specify only the valid values

pandas-stubs/core/frame.pyi

@@ -39,10 +39,7 @@ from pandas.core.arraylike import OpsMixin
 from pandas.core.generic import NDFrame
 from pandas.core.groupby.generic import DataFrameGroupBy
 from pandas.core.indexers import BaseIndexer
-from pandas.core.indexes.base import (
-    Index,
-    UnknownIndex,
-)
+from pandas.core.indexes.base import Index
 from pandas.core.indexes.category import CategoricalIndex
 from pandas.core.indexes.datetimes import DatetimeIndex
 from pandas.core.indexes.interval import IntervalIndex
@@ -545,10 +542,16 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     @classmethod
     def from_records(
         cls,
-        data,
-        index=...,
-        exclude: SequenceNotStr[str] | None = None,
-        columns: SequenceNotStr[str] | None = None,
+        data: (
+            np_2darray
+            | Sequence[SequenceNotStr]
+            | Sequence[Mapping[str, Any]]
+            | Mapping[str, Any]
+            | Mapping[str, SequenceNotStr[Any]]
+        ),
+        index: str | SequenceNotStr[Hashable] | None = None,
+        columns: ListLike | None = None,
+        exclude: ListLike | None = None,
         coerce_float: bool = False,
         nrows: int | None = None,
     ) -> Self: ...
@@ -1755,9 +1758,7 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
     @property
     def iloc(self) -> _iLocIndexerFrame[Self]: ...
     @property
-    # mypy complains if we use Index[Any] instead of UnknownIndex here, even though
-    # the latter is aliased to the former ¯\_(ツ)_/¯.
-    def index(self) -> UnknownIndex: ...
+    def index(self) -> Index: ...
     @index.setter
     def index(self, idx: Index) -> None: ...
     @property
@@ -2402,20 +2403,15 @@ class DataFrame(NDFrame, OpsMixin, _GetItemHack):
         numeric_only: _bool = False,
         **kwargs: Any,
     ) -> Series: ...
+    def __sub__(self, other: Any) -> Self: ...
+    def __rsub__(self, other: Any) -> Self: ...
     def sub(
         self,
         other: num | ListLike | DataFrame,
         axis: Axis | None = ...,
         level: Level | None = ...,
         fill_value: float | None = None,
     ) -> Self: ...
-    def subtract(
-        self,
-        other: num | ListLike | DataFrame,
-        axis: Axis | None = ...,
-        level: Level | None = ...,
-        fill_value: float | None = None,
-    ) -> Self: ...
     def sum(
         self,
         axis: Axis = 0,

pandas-stubs/core/indexes/base.pyi

@@ -15,7 +15,6 @@ from typing import (
     ClassVar,
     Generic,
     Literal,
-    TypeAlias,
     final,
     overload,
     type_check_only,
@@ -50,6 +49,7 @@ from pandas._typing import (
     ArrayLike,
     AxesData,
     DropKeep,
+    Dtype,
     DtypeArg,
     DTypeLike,
     DtypeObj,
@@ -89,7 +89,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[int]: ...
     @overload
     def __new__(
@@ -100,7 +99,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[int]: ...
     @overload
     def __new__(
@@ -111,7 +109,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[float]: ...
     @overload
     def __new__(
@@ -122,7 +119,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[float]: ...
     @overload
     def __new__(
@@ -137,7 +133,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[complex]: ...
     @overload
     def __new__(
@@ -148,7 +143,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Index[complex]: ...
     # special overloads with dedicated Index-subclasses
     @overload
@@ -160,7 +154,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> DatetimeIndex: ...
     @overload
     def __new__(
@@ -171,7 +164,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> DatetimeIndex: ...
     @overload
     def __new__(
@@ -182,7 +174,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> PeriodIndex: ...
     @overload
     def __new__(
@@ -193,7 +184,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> PeriodIndex: ...
     @overload
     def __new__(
@@ -204,7 +194,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> TimedeltaIndex: ...
     @overload
     def __new__(
@@ -215,7 +204,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> TimedeltaIndex: ...
     @overload
     def __new__(
@@ -226,7 +214,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> IntervalIndex[Interval[_OrderableT]]: ...
     @overload
     def __new__(
@@ -237,7 +224,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> IntervalIndex[Interval[Any]]: ...
     # generic overloads
     @overload
@@ -249,7 +235,6 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Self: ...
     @overload
     def __new__(
@@ -260,19 +245,17 @@ class Index(IndexOpsMixin[S1]):
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Self: ...
     # fallback overload
     @overload
     def __new__(
         cls,
         data: AxesData,
         *,
-        dtype=...,
+        dtype: Dtype = ...,
         copy: bool = ...,
         name: Hashable = ...,
         tupleize_cols: bool = ...,
-        **kwargs,
     ) -> Self: ...
     @property
     def str(
@@ -476,6 +459,8 @@ class Index(IndexOpsMixin[S1]):
     def __lt__(self, other: Self | S1) -> np_1darray[np.bool]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
     def __gt__(self, other: Self | S1) -> np_1darray[np.bool]: ...  # type: ignore[override] # pyright: ignore[reportIncompatibleMethodOverride]
     # overwrite inherited methods from OpsMixin
+    def __sub__(self, other: Any) -> Self: ...
+    def __rsub__(self, other: Any) -> Self: ...
     @overload
     def __mul__(
         self: Index[int] | Index[float], other: timedelta
@@ -524,8 +509,6 @@ class Index(IndexOpsMixin[S1]):
     ) -> Self: ...
     def infer_objects(self, copy: bool = True) -> Self: ...
 
-UnknownIndex: TypeAlias = Index[Any]
-
 @type_check_only
 class _IndexSubclassBase(Index[S1], Generic[S1, GenericT_co]):
     @overload