TYP: Subset of "Improved the type stubs in the _libs directory to help with type checking" (#44251)

Author: twoertwein

pandas/_libs/interval.pyx

@@ -516,9 +516,9 @@ def intervals_to_interval_bounds(ndarray intervals, bint validate_closed=True):
 
     Returns
     -------
-    tuple of tuples
-        left : (ndarray, object, array)
-        right : (ndarray, object, array)
+    tuple of
+        left : ndarray
+        right : ndarray
         closed: str
     """
     cdef:

pandas/_libs/missing.pyi

@@ -0,0 +1,15 @@
+import numpy as np
+from numpy import typing as npt
+
+class NAType: ...
+
+NA: NAType
+
+def is_matching_na(
+    left: object, right: object, nan_matches_none: bool = ...
+) -> bool: ...
+def isposinf_scalar(val: object) -> bool: ...
+def isneginf_scalar(val: object) -> bool: ...
+def checknull(val: object, inf_as_na: bool = ...) -> bool: ...
+def isnaobj(arr: np.ndarray, inf_as_na: bool = ...) -> npt.NDArray[np.bool_]: ...
+def is_numeric_na(values: np.ndarray) -> npt.NDArray[np.bool_]: ...

pandas/_libs/tslibs/dtypes.pyi

@@ -18,33 +18,33 @@ class PeriodDtypeBase:
     def resolution(self) -> Resolution: ...
 
 class FreqGroup(Enum):
-    FR_ANN: int = ...
-    FR_QTR: int = ...
-    FR_MTH: int = ...
-    FR_WK: int = ...
-    FR_BUS: int = ...
-    FR_DAY: int = ...
-    FR_HR: int = ...
-    FR_MIN: int = ...
-    FR_SEC: int = ...
-    FR_MS: int = ...
-    FR_US: int = ...
-    FR_NS: int = ...
-    FR_UND: int = ...
+    FR_ANN: int
+    FR_QTR: int
+    FR_MTH: int
+    FR_WK: int
+    FR_BUS: int
+    FR_DAY: int
+    FR_HR: int
+    FR_MIN: int
+    FR_SEC: int
+    FR_MS: int
+    FR_US: int
+    FR_NS: int
+    FR_UND: int
     @staticmethod
     def get_freq_group(code: int) -> FreqGroup: ...
 
 class Resolution(Enum):
-    RESO_NS: int = ...
-    RESO_US: int = ...
-    RESO_MS: int = ...
-    RESO_SEC: int = ...
-    RESO_MIN: int = ...
-    RESO_HR: int = ...
-    RESO_DAY: int = ...
-    RESO_MTH: int = ...
-    RESO_QTR: int = ...
-    RESO_YR: int = ...
+    RESO_NS: int
+    RESO_US: int
+    RESO_MS: int
+    RESO_SEC: int
+    RESO_MIN: int
+    RESO_HR: int
+    RESO_DAY: int
+    RESO_MTH: int
+    RESO_QTR: int
+    RESO_YR: int
     def __lt__(self, other: Resolution) -> bool: ...
     def __ge__(self, other: Resolution) -> bool: ...
     @property

pandas/_libs/tslibs/nattype.pyi

@@ -12,6 +12,8 @@ NaT: NaTType
 iNaT: int
 nat_strings: set[str]
 
+def is_null_datetimelike(val: object, inat_is_null: bool = ...) -> bool: ...
+
 class NaTType(datetime):
     value: np.int64
     def asm8(self) -> np.datetime64: ...

pandas/_libs/tslibs/np_datetime.pyi

@@ -0,0 +1 @@
+class OutOfBoundsDatetime(ValueError): ...

pandas/_libs/tslibs/offsets.pyx

@@ -3573,7 +3573,7 @@ cpdef to_offset(freq):
 
     Parameters
     ----------
-    freq : str, tuple, datetime.timedelta, DateOffset or None
+    freq : str, datetime.timedelta, BaseOffset or None
 
     Returns
     -------
@@ -3586,7 +3586,7 @@ cpdef to_offset(freq):
 
     See Also
     --------
-    DateOffset : Standard kind of date increment used for a date range.
+    BaseOffset : Standard kind of date increment used for a date range.
 
     Examples
     --------

pandas/_libs/tslibs/timestamps.pyi

@@ -17,15 +17,14 @@ import numpy as np
 
 from pandas._libs.tslibs import (
     BaseOffset,
-    NaT,
     NaTType,
     Period,
     Timedelta,
 )
 
 _S = TypeVar("_S")
 
-def integer_op_not_supported(obj) -> None: ...
+def integer_op_not_supported(obj) -> TypeError: ...
 
 class Timestamp(datetime):
     min: ClassVar[Timestamp]

pandas/core/arrays/string_.py

@@ -512,7 +512,9 @@ def _cmp_method(self, other, op):
 
     # ------------------------------------------------------------------------
     # String methods interface
-    _str_na_value = StringDtype.na_value
+    # error: Incompatible types in assignment (expression has type "NAType",
+    # base class "PandasArray" defined the type as "float")
+    _str_na_value = StringDtype.na_value  # type: ignore[assignment]
 
     def _str_map(
         self, f, na_value=None, dtype: Dtype | None = None, convert: bool = True

pandas/core/dtypes/cast.py

@@ -912,6 +912,10 @@ def maybe_upcast(
     # We get a copy in all cases _except_ (values.dtype == new_dtype and not copy)
     upcast_values = values.astype(new_dtype, copy=copy)
 
+    # error: Incompatible return value type (got "Tuple[ndarray[Any, dtype[Any]],
+    # Union[Union[str, int, float, bool] Union[Period, Timestamp, Timedelta, Any]]]",
+    # expected "Tuple[NumpyArrayT, Union[Union[str, int, float, bool], Union[Period,
+    # Timestamp, Timedelta, Any]]]")
     return upcast_values, fill_value  # type: ignore[return-value]
 
 

pandas/core/dtypes/dtypes.py

@@ -876,15 +876,15 @@ def freq(self):
 
     @classmethod
     def _parse_dtype_strict(cls, freq: str_type) -> BaseOffset:
-        if isinstance(freq, str):
+        if isinstance(freq, str):  # note: freq is already of type str!
             if freq.startswith("period[") or freq.startswith("Period["):
                 m = cls._match.search(freq)
                 if m is not None:
                     freq = m.group("freq")
 
-            freq = to_offset(freq)
-            if freq is not None:
-                return freq
+            freq_offset = to_offset(freq)
+            if freq_offset is not None:
+                return freq_offset
 
         raise ValueError("could not construct PeriodDtype")