TYP: stubs for tslibs (#40433)

Author: jbrockmendel

pandas/_libs/tslibs/ccalendar.pyi

@@ -0,0 +1,13 @@
+
+DAYS: list[str]
+MONTH_ALIASES: dict[int, str]
+MONTH_NUMBERS: dict[str, int]
+MONTHS: list[str]
+int_to_weekday: dict[int, str]
+
+def get_firstbday(year: int, month: int) -> int: ...
+def get_lastbday(year: int, month: int) -> int: ...
+def get_day_of_year(year: int, month: int, day: int) -> int: ...
+def get_iso_calendar(year: int, month: int, day: int) -> tuple[int, int, int]: ...
+def get_week_of_year(year: int, month: int, day: int) -> int: ...
+def get_days_in_month(year: int, month: int) -> int: ...

pandas/_libs/tslibs/strptime.pyi

@@ -0,0 +1,11 @@
+from typing import Optional
+
+import numpy as np
+
+def array_strptime(
+    values: np.ndarray,  # np.ndarray[object]
+    fmt: Optional[str],
+    exact: bool = True,
+    errors: str = "raise"
+) -> tuple[np.ndarray, np.ndarray]: ...
+# first  ndarray is M8[ns], second is object ndarray of Optional[tzinfo]

pandas/_libs/tslibs/timezones.pyi

@@ -0,0 +1,32 @@
+from datetime import (
+    datetime,
+    tzinfo,
+)
+from typing import (
+    Callable,
+    Optional,
+    Union,
+)
+
+import numpy as np
+
+# imported from dateutil.tz
+dateutil_gettz: Callable[[str], tzinfo]
+
+
+def tz_standardize(tz: tzinfo) -> tzinfo: ...
+
+def tz_compare(start: Optional[tzinfo], end: Optional[tzinfo]) -> bool: ...
+
+def infer_tzinfo(
+    start: Optional[datetime], end: Optional[datetime],
+) -> Optional[tzinfo]: ...
+
+# ndarrays returned are both int64_t
+def get_dst_info(tz: tzinfo) -> tuple[np.ndarray, np.ndarray, str]: ...
+
+def maybe_get_tz(tz: Optional[Union[str, int, np.int64, tzinfo]]) -> Optional[tzinfo]: ...
+
+def get_timezone(tz: tzinfo) -> Union[tzinfo, str]: ...
+
+def is_utc(tz: Optional[tzinfo]) -> bool: ...

pandas/_libs/tslibs/timezones.pyx

@@ -67,6 +67,7 @@ cdef inline bint treat_tz_as_dateutil(tzinfo tz):
     return hasattr(tz, '_trans_list') and hasattr(tz, '_trans_idx')
 
 
+# Returns str or tzinfo object
 cpdef inline object get_timezone(tzinfo tz):
     """
     We need to do several things here:
@@ -80,6 +81,8 @@ cpdef inline object get_timezone(tzinfo tz):
     the tz name. It needs to be a string so that we can serialize it with
     UJSON/pytables. maybe_get_tz (below) is the inverse of this process.
     """
+    if tz is None:
+        raise TypeError("tz argument cannot be None")
     if is_utc(tz):
         return tz
     else:
@@ -364,6 +367,8 @@ cpdef bint tz_compare(tzinfo start, tzinfo end):
     elif is_utc(end):
         # Ensure we don't treat tzlocal as equal to UTC when running in UTC
         return False
+    elif start is None or end is None:
+        return start is None and end is None
     return get_timezone(start) == get_timezone(end)
 
 

pandas/_libs/tslibs/tzconversion.pyi

@@ -0,0 +1,25 @@
+from datetime import (
+    timedelta,
+    tzinfo,
+)
+from typing import (
+    Iterable,
+    Optional,
+    Union,
+)
+
+import numpy as np
+
+def tz_convert_from_utc(
+    vals: np.ndarray,  # const int64_t[:]
+    tz: tzinfo,
+) -> np.ndarray: ...  # np.ndarray[np.int64]
+
+def tz_convert_from_utc_single(val: np.int64, tz: tzinfo) -> np.int64: ...
+
+def tz_localize_to_utc(
+    vals: np.ndarray,  # np.ndarray[np.int64]
+    tz: Optional[tzinfo],
+    ambiguous: Optional[Union[str, bool, Iterable[bool]]] = None,
+    nonexistent: Optional[Union[str, timedelta, np.timedelta64]] = None,
+) -> np.ndarray: ...  # np.ndarray[np.int64]

pandas/_libs/tslibs/vectorized.pyi

@@ -0,0 +1,47 @@
+"""
+For cython types that cannot be represented precisely, closest-available
+python equivalents are used, and the precise types kept as adjacent comments.
+"""
+from datetime import tzinfo
+from typing import (
+    Optional,
+    Union,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs.dtypes import Resolution
+from pandas._libs.tslibs.offsets import BaseOffset
+
+def dt64arr_to_periodarr(
+    stamps: np.ndarray,  # const int64_t[:]
+    freq: int,
+    tz: Optional[tzinfo],
+) -> np.ndarray: ...  # np.ndarray[np.int64, ndim=1]
+
+
+def is_date_array_normalized(
+    stamps: np.ndarray,  # const int64_t[:]
+    tz: Optional[tzinfo] = None,
+) -> bool: ...
+
+
+def normalize_i8_timestamps(
+    stamps: np.ndarray,  # const int64_t[:]
+    tz: Optional[tzinfo],
+) -> np.ndarray: ...  # np.ndarray[np.int64]
+
+
+def get_resolution(
+    stamps: np.ndarray,  # const int64_t[:]
+    tz: Optional[tzinfo] = None,
+) -> Resolution: ...
+
+
+def ints_to_pydatetime(
+    arr: np.ndarray,  # const int64_t[:}]
+    tz: Optional[tzinfo] = None,
+    freq: Optional[Union[str, BaseOffset]] = None,
+    fold: bool = False,
+    box: str = "datetime",
+) -> np.ndarray: ...  # np.ndarray[object]

pandas/core/tools/datetimes.py

@@ -289,7 +289,7 @@ def _convert_listlike_datetimes(
     name: Hashable = None,
     tz: Optional[Timezone] = None,
     unit: Optional[str] = None,
-    errors: Optional[str] = None,
+    errors: str = "raise",
     infer_datetime_format: bool = False,
     dayfirst: Optional[bool] = None,
     yearfirst: Optional[bool] = None,
@@ -432,7 +432,7 @@ def _array_strptime_with_fallback(
     tz,
     fmt: str,
     exact: bool,
-    errors: Optional[str],
+    errors: str,
     infer_datetime_format: bool,
 ) -> Optional[Index]:
     """
@@ -480,7 +480,7 @@ def _to_datetime_with_format(
     tz,
     fmt: str,
     exact: bool,
-    errors: Optional[str],
+    errors: str,
     infer_datetime_format: bool,
 ) -> Optional[Index]:
     """