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

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

@@ -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)
@@ -45,26 +46,61 @@ reveal_type(s2)
 td = s1 - s2
 reveal_type(td)
 ssum = s1 + s2
-reveal_type(ssum)
 ```
 
-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 as follows:
+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
 the type `Series[Timedelta]` is the result of subtracting two `Series[Timestamp]` as well as
 the result of `pd.to_timedelta()`.
 
+### Progressive arithmetic typing for generic Series
+
+Consider the following Series from a DataFrame:
+
+```python
+import pandas as pd
+from typing_extensions import reveal_type
+
+
+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 - pd.Timestamp(2025, 7, 12))  # type checker: TimedeltaSeries, runtime: Series
+
+tags = frame["tag"]
+reveal_type("suffix" + tags)  # type checker: Series[str], runtime: Series
+```
+
+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, 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 type of the arithmetic operation.
+
 ### Interval is Generic
 
 A pandas `Interval` can be a time interval, an interval of integers, or an interval of

pandas-stubs/__init__.pyi

@@ -119,7 +119,6 @@ from pandas.io.api import (
     read_stata as read_stata,
     read_table as read_table,
     read_xml as read_xml,
-    to_pickle as to_pickle,
 )
 from pandas.io.json._normalize import json_normalize as json_normalize
 from pandas.tseries import offsets as offsets

pandas-stubs/_libs/interval.pyi

@@ -17,7 +17,7 @@ from pandas import (
 from pandas._typing import (
     IntervalClosedType,
     IntervalT,
-    np_ndarray_bool,
+    np_1darray,
     npt,
 )
 
@@ -166,7 +166,9 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __gt__(self, other: Interval[_OrderableT]) -> bool: ...
     @overload
-    def __gt__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __gt__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __gt__(
         self,
@@ -175,7 +177,9 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __lt__(self, other: Interval[_OrderableT]) -> bool: ...
     @overload
-    def __lt__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __lt__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __lt__(
         self,
@@ -184,7 +188,9 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __ge__(self, other: Interval[_OrderableT]) -> bool: ...
     @overload
-    def __ge__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __ge__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __ge__(
         self,
@@ -193,19 +199,25 @@ class Interval(IntervalMixin, Generic[_OrderableT]):
     @overload
     def __le__(self, other: Interval[_OrderableT]) -> bool: ...
     @overload
-    def __le__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __le__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __eq__(self, other: Interval[_OrderableT]) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __eq__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __eq__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __eq__(self, other: Series[_OrderableT]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload
     def __eq__(self, other: object) -> Literal[False]: ...
     @overload
     def __ne__(self, other: Interval[_OrderableT]) -> bool: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
-    def __ne__(self: IntervalT, other: IntervalIndex[IntervalT]) -> np_ndarray_bool: ...
+    def __ne__(
+        self: IntervalT, other: IntervalIndex[IntervalT]
+    ) -> np_1darray[np.bool]: ...
     @overload
     def __ne__(self, other: Series[_OrderableT]) -> Series[bool]: ...  # type: ignore[overload-overlap]
     @overload

pandas-stubs/_libs/lib.pyi

@@ -16,10 +16,10 @@ class _NoDefault(Enum):
 no_default: Final = _NoDefault.no_default
 _NoDefaultDoNotUse: TypeAlias = Literal[_NoDefault.no_default]  # noqa: PYI047
 
-def infer_dtype(value: object, skipna: bool = ...) -> str: ...
+def infer_dtype(value: object, skipna: bool = True) -> str: ...
 def is_iterator(obj: object) -> bool: ...
 def is_scalar(val: object) -> bool: ...
-def is_list_like(obj: object, allow_sets: bool = ...) -> bool: ...
+def is_list_like(obj: object, allow_sets: bool = True) -> bool: ...
 def is_complex(val: object) -> TypeGuard[complex]: ...
 def is_bool(val: object) -> TypeGuard[bool | np.bool_]: ...
 def is_integer(val: object) -> TypeGuard[int | np.integer]: ...