Merge remote-tracking branch 'upstream/main' into series-map

Author: hamdanal

.gitignore

@@ -135,3 +135,6 @@ dmypy.json
 .pyre/
 /poetry.lock
 .idea/**/*
+
+# duplication of stub specific objects upon testing
+tests/_typing.pyi

pandas-stubs/__init__.pyi

@@ -63,7 +63,6 @@ from pandas.core.api import (
     to_numeric as to_numeric,
     to_timedelta as to_timedelta,
     unique as unique,
-    value_counts as value_counts,
 )
 from pandas.core.arrays.sparse import SparseDtype as SparseDtype
 from pandas.core.computation.api import eval as eval

pandas-stubs/_libs/json.pyi

@@ -117,7 +117,7 @@ class NAType:
     @overload
     def __eq__(self, other: Index, /) -> BooleanArray: ...
     @overload
-    def __eq__(  # pyright: ignore[reportIncompatibleMethodOverride]
+    def __eq__(  # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override]
         self, other: Scalar, /
     ) -> NAType: ...
     @overload  # type: ignore[override]
@@ -127,7 +127,7 @@ class NAType:
     @overload
     def __ne__(self, other: Index, /) -> BooleanArray: ...
     @overload
-    def __ne__(  # pyright: ignore[reportIncompatibleMethodOverride]
+    def __ne__(  # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override]
         self, other: Scalar, /
     ) -> NAType: ...
     @overload

pandas-stubs/_libs/missing.pyi

@@ -1,16 +1,4 @@
-from collections.abc import Callable
-
-class CachedProperty:
-    def __init__(self, func: Callable) -> None: ...
-    def __get__(self, obj, typ): ...
-    def __set__(self, obj, value) -> None: ...
-
 # note: this is a lie to make type checkers happy (they special
 # case property). cache_readonly uses attribute names similar to
 # property (fget) but it does not provide fset and fdel.
 cache_readonly = property
-
-class AxisProperty:
-    def __init__(self, axis: int = ..., doc: str = ...) -> None: ...
-    def __get__(self, obj, typ): ...
-    def __set__(self, obj, value) -> None: ...

pandas-stubs/_libs/properties.pyi

@@ -45,7 +45,7 @@ class BaseOffset:
         self, other: np_ndarray[ShapeT, np.object_]
     ) -> np_ndarray[ShapeT, np.object_]: ...
     @overload
-    def __add__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
+    def __add__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
     def __add__(self, other: date) -> Timestamp: ...
     @overload
@@ -57,7 +57,7 @@ class BaseOffset:
         self, other: np_ndarray[ShapeT, np.object_]
     ) -> np_ndarray[ShapeT, np.object_]: ...
     @overload
-    def __radd__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
+    def __radd__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
     def __radd__(self, other: date) -> Timestamp: ...
     @overload
@@ -68,7 +68,7 @@ class BaseOffset:
     @overload
     def __rsub__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
     @overload
-    def __rsub__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap]  # pyright: ignore[reportOverlappingOverload]
+    def __rsub__(self, other: _DatetimeT) -> _DatetimeT: ...  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
     @overload
     def __rsub__(self, other: date) -> Timestamp: ...
     @overload
@@ -124,7 +124,6 @@ class BusinessDay(BaseOffset):
     def __init__(
         self, n: int = ..., normalize: bool = ..., offset: timedelta = ...
     ) -> None: ...
-    def __reduce__(self): ...
 
 class BusinessHour(SingleConstructorOffset):
     def __init__(

pandas-stubs/_libs/tslibs/offsets.pyi

@@ -259,7 +259,7 @@ class Timedelta(timedelta):
         self, other: np_ndarray[ShapeT, np.integer | np.floating]
     ) -> np_ndarray[ShapeT, np.timedelta64]: ...
     @overload
-    def __truediv__(
+    def __truediv__(  # ty: ignore[invalid-method-override]
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.floating]: ...
     @overload

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -32,6 +32,7 @@ from pandas._libs.tslibs import (
     Tick,
     Timedelta,
 )
+from pandas._libs.tslibs.nattype import NaTType
 from pandas._typing import (
     PeriodFrequency,
     ShapeT,
@@ -99,7 +100,7 @@ class Timestamp(datetime, SupportsIndex):
     def fold(self) -> int: ...
     if sys.version_info >= (3, 12):
         @classmethod
-        def fromtimestamp(  # pyright: ignore[reportIncompatibleMethodOverride]
+        def fromtimestamp(  # pyright: ignore[reportIncompatibleMethodOverride] # ty: ignore[invalid-method-override] # pyrefly: ignore[bad-param-name-override]
             cls, t: float, tz: _tzinfo | str | None = ...
         ) -> Self: ...
     else:
@@ -180,7 +181,9 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __le__(self, other: Series[Timestamp]) -> Series[bool]: ...
+    def __le__(  # ty: ignore[invalid-method-override]
+        self, other: Series[Timestamp]
+    ) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __lt__(self, other: datetime | np.datetime64 | Self) -> bool: ...
     @overload
@@ -190,7 +193,9 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __lt__(self, other: Series[Timestamp]) -> Series[bool]: ...
+    def __lt__(  # ty: ignore[invalid-method-override]
+        self, other: Series[Timestamp]
+    ) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __ge__(self, other: datetime | np.datetime64 | Self) -> bool: ...
     @overload
@@ -200,7 +205,9 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __ge__(self, other: Series[Timestamp]) -> Series[bool]: ...
+    def __ge__(  # ty: ignore[invalid-method-override]
+        self, other: Series[Timestamp]
+    ) -> Series[bool]: ...
     @overload  # type: ignore[override]
     def __gt__(self, other: datetime | np.datetime64 | Self) -> bool: ...
     @overload
@@ -210,7 +217,9 @@ class Timestamp(datetime, SupportsIndex):
         self, other: np_ndarray[ShapeT, np.datetime64]
     ) -> np_ndarray[ShapeT, np.bool]: ...
     @overload
-    def __gt__(self, other: Series[Timestamp]) -> Series[bool]: ...
+    def __gt__(  # ty: ignore[invalid-method-override]
+        self, other: Series[Timestamp]
+    ) -> Series[bool]: ...
     # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
     @overload  # type: ignore[override]
     def __add__(
@@ -228,15 +237,15 @@ class Timestamp(datetime, SupportsIndex):
     def __radd__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
-    # TODO: pandas-dev/pandas-stubs#1432 test dt64
+    def __rsub__(self, other: datetime | np.datetime64) -> Timedelta: ...
     @overload  # type: ignore[override]
     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__(
+    def __sub__(  # ty: ignore[invalid-method-override]
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
     @overload
@@ -284,7 +293,15 @@ class Timestamp(datetime, SupportsIndex):
     @property
     def asm8(self) -> np.datetime64: ...
     def tz_convert(self, tz: TimeZones) -> Self: ...
-    # TODO: pandas-dev/pandas-stubs#1432 could return NaT?
+    @overload
+    def tz_localize(  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
+        self,
+        tz: TimeZones,
+        ambiguous: _Ambiguous = "raise",
+        *,
+        nonexistent: Literal["NaT"],
+    ) -> Self | NaTType: ...
+    @overload
     def tz_localize(
         self,
         tz: TimeZones,

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -14,18 +14,17 @@ from os import PathLike
 from re import Pattern
 import sys
 from typing import (
+    TYPE_CHECKING,
     Any,
     Generic,
     Literal,
     Protocol,
     SupportsIndex,
     TypeAlias,
     TypedDict,
-    Union,
     overload,
 )
 
-from _typeshed import _T_contra
 import numpy as np
 from numpy import typing as npt
 import pandas as pd
@@ -87,13 +86,15 @@ HashableT5 = TypeVar("HashableT5", bound=Hashable)
 
 ArrayLike: TypeAlias = ExtensionArray | npt.NDArray[Any]
 AnyArrayLike: TypeAlias = ArrayLike | Index | Series
-AnyArrayLikeInt: TypeAlias = (
-    IntegerArray | Index[int] | Series[int] | npt.NDArray[np.integer]
-)
+if TYPE_CHECKING:  # noqa: PYI002
+    AnyArrayLikeInt: TypeAlias = (
+        IntegerArray | Index[int] | Series[int] | npt.NDArray[np.integer]
+    )
 
 # list-like
 
 _T_co = TypeVar("_T_co", covariant=True)
+_T_contra = TypeVar("_T_contra", contravariant=True)
 
 class SequenceNotStr(Protocol[_T_co]):
     @overload
@@ -594,18 +595,25 @@ IndexKeyFunc: TypeAlias = Callable[[Index], Index | AnyArrayLike] | None
 
 # types of `func` kwarg for DataFrame.aggregate and Series.aggregate
 # More specific than what is in pandas
-# following Union is here to make it ty compliant https://github.com/astral-sh/ty/issues/591
-AggFuncTypeBase: TypeAlias = Union[Callable, str, np.ufunc]  # noqa: UP007
-AggFuncTypeDictSeries: TypeAlias = Mapping[HashableT, AggFuncTypeBase]
+AggFuncTypeBase: TypeAlias = Callable[P, Any] | str | np.ufunc
+AggFuncTypeDictSeries: TypeAlias = Mapping[HashableT, AggFuncTypeBase[P]]
 AggFuncTypeDictFrame: TypeAlias = Mapping[
-    HashableT, AggFuncTypeBase | list[AggFuncTypeBase]
+    HashableT, AggFuncTypeBase[P] | Sequence[AggFuncTypeBase[P]]
 ]
-AggFuncTypeSeriesToFrame: TypeAlias = list[AggFuncTypeBase] | AggFuncTypeDictSeries
+AggFuncTypeSeriesToFrame: TypeAlias = (
+    Sequence[AggFuncTypeBase[P]] | AggFuncTypeDictSeries[HashableT, P]
+)
 AggFuncTypeFrame: TypeAlias = (
-    AggFuncTypeBase | list[AggFuncTypeBase] | AggFuncTypeDictFrame
+    AggFuncTypeBase[P]
+    | Sequence[AggFuncTypeBase[P]]
+    | AggFuncTypeDictFrame[HashableT, P]
+)
+AggFuncTypeDict: TypeAlias = (
+    AggFuncTypeDictSeries[HashableT, P] | AggFuncTypeDictFrame[HashableT, P]
+)
+AggFuncType: TypeAlias = (
+    AggFuncTypeBase[P] | Sequence[AggFuncTypeBase[P]] | AggFuncTypeDict[HashableT, P]
 )
-AggFuncTypeDict: TypeAlias = AggFuncTypeDictSeries | AggFuncTypeDictFrame
-AggFuncType: TypeAlias = AggFuncTypeBase | list[AggFuncTypeBase] | AggFuncTypeDict
 
 # Not used in stubs
 # AggObjType = Union[
@@ -692,7 +700,9 @@ CompressionOptions: TypeAlias = (
 
 # types in DataFrameFormatter
 FormattersType: TypeAlias = (
-    list[Callable] | tuple[Callable, ...] | Mapping[str | int, Callable]
+    list[Callable[..., Any]]
+    | tuple[Callable[..., Any], ...]
+    | Mapping[str | int, Callable[..., Any]]
 )
 # ColspaceType = Mapping[Hashable, Union[str, int]] not used in stubs
 FloatFormatType: TypeAlias = str | Callable[[float], str] | EngFormatter
@@ -825,7 +835,7 @@ TimeNonexistent: TypeAlias = (
 DropKeep: TypeAlias = Literal["first", "last", False]
 CorrelationMethod: TypeAlias = (
     Literal["pearson", "kendall", "spearman"]
-    | Callable[[np.typing.NDArray[Any], np.typing.NDArray[Any]], float]
+    | Callable[[npt.NDArray[Any], npt.NDArray[Any]], float]
 )
 AlignJoin: TypeAlias = Literal["outer", "inner", "left", "right"]
 DtypeBackend: TypeAlias = Literal["pyarrow", "numpy_nullable"]
@@ -948,6 +958,8 @@ np_1darray_dt: TypeAlias = np_1darray[np.datetime64]
 np_1darray_td: TypeAlias = np_1darray[np.timedelta64]
 np_2darray: TypeAlias = np.ndarray[tuple[int, int], np.dtype[GenericT]]
 
+NDArrayT = TypeVar("NDArrayT", bound=np.ndarray)
+
 DtypeNp = TypeVar("DtypeNp", bound=np.dtype[np.generic])
 KeysArgType: TypeAlias = Any
 ListLikeT = TypeVar("ListLikeT", bound=ListLike)
@@ -966,8 +978,9 @@ class SupportsDType(Protocol[GenericT_co]):
 # Similar to npt.DTypeLike but leaves out np.dtype and None for use in overloads
 DTypeLike: TypeAlias = type[Any] | tuple[Any, Any] | list[Any] | str
 
-IndexType: TypeAlias = slice | np_ndarray_anyint | Index | list[int] | Series[int]
-MaskType: TypeAlias = Series[bool] | np_ndarray_bool | list[bool]
+if TYPE_CHECKING:  # noqa: PYI002
+    IndexType: TypeAlias = slice | np_ndarray_anyint | Index | list[int] | Series[int]
+    MaskType: TypeAlias = Series[bool] | np_ndarray_bool | list[bool]
 
 # Scratch types for generics
 
@@ -1039,48 +1052,49 @@ Function: TypeAlias = np.ufunc | Callable[..., Any]
 # shared HashableT and HashableT#. This one can be used if the identical
 # type is need in a function that uses GroupByObjectNonScalar
 _HashableTa = TypeVar("_HashableTa", bound=Hashable)
-ByT = TypeVar(
-    "ByT",
-    bound=str
-    | bytes
-    | datetime.date
-    | datetime.datetime
-    | datetime.timedelta
-    | np.datetime64
-    | np.timedelta64
-    | bool
-    | int
-    | float
-    | complex
-    | Scalar
-    | Period
-    | Interval[int | float | Timestamp | Timedelta]
-    | tuple,
-)
-# Use a distinct SeriesByT when using groupby with Series of known dtype.
-# Essentially, an intersection between Series S1 TypeVar, and ByT TypeVar
-SeriesByT = TypeVar(
-    "SeriesByT",
-    bound=str
-    | bytes
-    | datetime.date
-    | bool
-    | int
-    | float
-    | complex
-    | datetime.datetime
-    | datetime.timedelta
-    | Period
-    | Interval[int | float | Timestamp | Timedelta],
-)
+if TYPE_CHECKING:  # noqa: PYI002
+    ByT = TypeVar(
+        "ByT",
+        bound=str
+        | bytes
+        | datetime.date
+        | datetime.datetime
+        | datetime.timedelta
+        | np.datetime64
+        | np.timedelta64
+        | bool
+        | int
+        | float
+        | complex
+        | Scalar
+        | Period
+        | Interval[int | float | Timestamp | Timedelta]
+        | tuple,
+    )
+    # Use a distinct SeriesByT when using groupby with Series of known dtype.
+    # Essentially, an intersection between Series S1 TypeVar, and ByT TypeVar
+    SeriesByT = TypeVar(
+        "SeriesByT",
+        bound=str
+        | bytes
+        | datetime.date
+        | bool
+        | int
+        | float
+        | complex
+        | datetime.datetime
+        | datetime.timedelta
+        | Period
+        | Interval[int | float | Timestamp | Timedelta],
+    )
 GroupByObjectNonScalar: TypeAlias = (
-    tuple
+    tuple[_HashableTa, ...]
     | list[_HashableTa]
     | Function
     | list[Function]
     | list[Series]
-    | np.ndarray
-    | list[np.ndarray]
+    | np_ndarray
+    | list[np_ndarray]
     | Mapping[Label, Any]
     | list[Mapping[Label, Any]]
     | list[Index]