TYP: misc annotations (#57606)

* TYP: misc changes

* fix runtime

* pre-commit

* a few more

* stubtest

* NoReturn for <3.11

Author: twoertwein

.pre-commit-config.yaml

@@ -127,7 +127,7 @@ repos:
         types: [python]
         stages: [manual]
         additional_dependencies: &pyright_dependencies
-        - [email protected].350
+        - [email protected].351
     -   id: pyright
         # note: assumes python env is setup and activated
         name: pyright reportGeneralTypeIssues

pandas/_libs/tslibs/nattype.pyi

@@ -1,20 +1,30 @@
 from datetime import (
+    date as date_,
     datetime,
+    time as time_,
     timedelta,
     tzinfo as _tzinfo,
 )
-import typing
+from typing import (
+    Literal,
+    NoReturn,
+    TypeAlias,
+)
 
 import numpy as np
 
 from pandas._libs.tslibs.period import Period
-from pandas._typing import Self
+from pandas._typing import (
+    Frequency,
+    Self,
+    TimestampNonexistent,
+)
 
 NaT: NaTType
 iNaT: int
 nat_strings: set[str]
 
-_NaTComparisonTypes: typing.TypeAlias = (
+_NaTComparisonTypes: TypeAlias = (
     datetime | timedelta | Period | np.datetime64 | np.timedelta64
 )
 
@@ -61,18 +71,38 @@ class NaTType:
     def week(self) -> float: ...
     @property
     def weekofyear(self) -> float: ...
+    @property
+    def fold(self) -> int: ...
     def day_name(self) -> float: ...
     def month_name(self) -> float: ...
     def weekday(self) -> float: ...
     def isoweekday(self) -> float: ...
+    def isoformat(self, sep: str = ..., timespec: str = ...) -> str: ...
+    def strftime(self, format: str) -> NoReturn: ...
     def total_seconds(self) -> float: ...
     def today(self, *args, **kwargs) -> NaTType: ...
     def now(self, *args, **kwargs) -> NaTType: ...
     def to_pydatetime(self) -> NaTType: ...
     def date(self) -> NaTType: ...
-    def round(self) -> NaTType: ...
-    def floor(self) -> NaTType: ...
-    def ceil(self) -> NaTType: ...
+    def round(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
+    def floor(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
+    def ceil(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
+    def combine(cls, date: date_, time: time_) -> NoReturn: ...
     @property
     def tzinfo(self) -> None: ...
     @property
@@ -81,8 +111,8 @@ class NaTType:
     def tz_localize(
         self,
         tz: _tzinfo | str | None,
-        ambiguous: str = ...,
-        nonexistent: str = ...,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
     ) -> NaTType: ...
     def replace(
         self,
@@ -121,6 +151,8 @@ class NaTType:
     @property
     def days(self) -> float: ...
     @property
+    def seconds(self) -> float: ...
+    @property
     def microseconds(self) -> float: ...
     @property
     def nanoseconds(self) -> float: ...

pandas/_libs/tslibs/offsets.pyi

@@ -196,7 +196,10 @@ class WeekOfMonth(WeekOfMonthMixin):
         self, n: int = ..., normalize: bool = ..., week: int = ..., weekday: int = ...
     ) -> None: ...
 
-class LastWeekOfMonth(WeekOfMonthMixin): ...
+class LastWeekOfMonth(WeekOfMonthMixin):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., weekday: int = ...
+    ) -> None: ...
 
 class FY5253Mixin(SingleConstructorOffset):
     def __init__(

pandas/_typing.py

@@ -207,7 +207,7 @@ def __reversed__(self) -> Iterator[_T_co]:
 IndexLabel = Union[Hashable, Sequence[Hashable]]
 Level = Hashable
 Shape = tuple[int, ...]
-Suffixes = tuple[Optional[str], Optional[str]]
+Suffixes = Sequence[Optional[str]]
 Ordered = Optional[bool]
 JSONSerializable = Optional[Union[PythonScalar, list, dict]]
 Frequency = Union[str, "BaseOffset"]
@@ -226,7 +226,7 @@ def __reversed__(self) -> Iterator[_T_co]:
 Dtype = Union["ExtensionDtype", NpDtype]
 AstypeArg = Union["ExtensionDtype", "npt.DTypeLike"]
 # DtypeArg specifies all allowable dtypes in a functions its dtype argument
-DtypeArg = Union[Dtype, dict[Hashable, Dtype]]
+DtypeArg = Union[Dtype, Mapping[Hashable, Dtype]]
 DtypeObj = Union[np.dtype, "ExtensionDtype"]
 
 # converters

pandas/core/dtypes/missing.py

@@ -45,6 +45,8 @@
 if TYPE_CHECKING:
     from re import Pattern
 
+    from pandas._libs.missing import NAType
+    from pandas._libs.tslibs import NaTType
     from pandas._typing import (
         ArrayLike,
         DtypeObj,
@@ -66,7 +68,7 @@
 
 
 @overload
-def isna(obj: Scalar | Pattern) -> bool:
+def isna(obj: Scalar | Pattern | NAType | NaTType) -> bool:
     ...
 
 
@@ -283,7 +285,7 @@ def _isna_recarray_dtype(values: np.rec.recarray) -> npt.NDArray[np.bool_]:
 
 
 @overload
-def notna(obj: Scalar) -> bool:
+def notna(obj: Scalar | Pattern | NAType | NaTType) -> bool:
     ...
 
 

pandas/core/frame.py

@@ -4799,7 +4799,7 @@ def insert(
         self,
         loc: int,
         column: Hashable,
-        value: Scalar | AnyArrayLike,
+        value: object,
         allow_duplicates: bool | lib.NoDefault = lib.no_default,
     ) -> None:
         """
@@ -6266,7 +6266,7 @@ def dropna(
         axis: Axis = 0,
         how: AnyAll | lib.NoDefault = lib.no_default,
         thresh: int | lib.NoDefault = lib.no_default,
-        subset: IndexLabel | None = None,
+        subset: IndexLabel | AnyArrayLike | None = None,
         inplace: bool = False,
         ignore_index: bool = False,
     ) -> DataFrame | None:
@@ -6390,7 +6390,7 @@ def dropna(
         if subset is not None:
             # subset needs to be list
             if not is_list_like(subset):
-                subset = [subset]
+                subset = [cast(Hashable, subset)]
             ax = self._get_axis(agg_axis)
             indices = ax.get_indexer_for(subset)
             check = indices == -1

pandas/core/groupby/generic.py

@@ -1326,7 +1326,7 @@ def hist(
         xrot: float | None = None,
         ylabelsize: int | None = None,
         yrot: float | None = None,
-        figsize: tuple[int, int] | None = None,
+        figsize: tuple[float, float] | None = None,
         bins: int | Sequence[int] = 10,
         backend: str | None = None,
         legend: bool = False,
@@ -2599,7 +2599,7 @@ def hist(
         ax=None,
         sharex: bool = False,
         sharey: bool = False,
-        figsize: tuple[int, int] | None = None,
+        figsize: tuple[float, float] | None = None,
         layout: tuple[int, int] | None = None,
         bins: int | Sequence[int] = 10,
         backend: str | None = None,

pandas/core/reshape/merge.py

@@ -445,7 +445,7 @@ def merge_asof(
     left_by=None,
     right_by=None,
     suffixes: Suffixes = ("_x", "_y"),
-    tolerance: int | Timedelta | None = None,
+    tolerance: int | datetime.timedelta | None = None,
     allow_exact_matches: bool = True,
     direction: str = "backward",
 ) -> DataFrame:
@@ -494,7 +494,7 @@ def merge_asof(
     suffixes : 2-length sequence (tuple, list, ...)
         Suffix to apply to overlapping column names in the left and right
         side, respectively.
-    tolerance : int or Timedelta, optional, default None
+    tolerance : int or timedelta, optional, default None
         Select asof tolerance within this range; must be compatible
         with the merge index.
     allow_exact_matches : bool, default True

pandas/core/series.py

@@ -2891,7 +2891,7 @@ def autocorr(self, lag: int = 1) -> float:
         """
         return self.corr(cast(Series, self.shift(lag)))
 
-    def dot(self, other: AnyArrayLike) -> Series | np.ndarray:
+    def dot(self, other: AnyArrayLike | DataFrame) -> Series | np.ndarray:
         """
         Compute the dot product between the Series and the columns of other.
 
@@ -6346,7 +6346,7 @@ def mean(
         skipna: bool = True,
         numeric_only: bool = False,
         **kwargs,
-    ):
+    ) -> Any:
         return NDFrame.mean(
             self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
         )
@@ -6358,7 +6358,7 @@ def median(
         skipna: bool = True,
         numeric_only: bool = False,
         **kwargs,
-    ):
+    ) -> Any:
         return NDFrame.median(
             self, axis=axis, skipna=skipna, numeric_only=numeric_only, **kwargs
         )

pandas/io/excel/_base.py

@@ -76,6 +76,7 @@
         DtypeBackend,
         ExcelWriterIfSheetExists,
         FilePath,
+        HashableT,
         IntStrT,
         ReadBuffer,
         Self,
@@ -382,7 +383,7 @@ def read_excel(
     | str
     | Sequence[int]
     | Sequence[str]
-    | Callable[[str], bool]
+    | Callable[[HashableT], bool]
     | None = ...,
     dtype: DtypeArg | None = ...,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = ...,
@@ -421,7 +422,7 @@ def read_excel(
     | str
     | Sequence[int]
     | Sequence[str]
-    | Callable[[str], bool]
+    | Callable[[HashableT], bool]
     | None = ...,
     dtype: DtypeArg | None = ...,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = ...,
@@ -460,7 +461,7 @@ def read_excel(
     | str
     | Sequence[int]
     | Sequence[str]
-    | Callable[[str], bool]
+    | Callable[[HashableT], bool]
     | None = None,
     dtype: DtypeArg | None = None,
     engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = None,