TYP: tslibs

pandas/_libs/tslibs/conversion.pyi

@@ -5,6 +5,8 @@ from datetime import (
 
 import numpy as np
 
+from pandas._typing import npt
+
 DT64NS_DTYPE: np.dtype
 TD64NS_DTYPE: np.dtype
 
@@ -22,6 +24,6 @@ def ensure_timedelta64ns(
     copy: bool = ...,
 ) -> np.ndarray: ...  # np.ndarray[timedelta64ns]
 def datetime_to_datetime64(
-    values: np.ndarray,  # np.ndarray[object]
+    values: npt.NDArray[np.object_],
 ) -> tuple[np.ndarray, tzinfo | None,]: ...  # (np.ndarray[dt64ns], _)
 def localize_pydatetime(dt: datetime, tz: tzinfo | None) -> datetime: ...

pandas/_libs/tslibs/fields.pyi

@@ -1,33 +1,35 @@
 import numpy as np
 
+from pandas._typing import npt
+
 def build_field_sarray(
-    dtindex: np.ndarray,  # const int64_t[:]
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
 ) -> np.ndarray: ...
 def month_position_check(fields, weekdays) -> str | None: ...
 def get_date_name_field(
-    dtindex: np.ndarray,  # const int64_t[:]
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
     field: str,
     locale=...,
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...
 def get_start_end_field(
-    dtindex: np.ndarray,  # const int64_t[:]
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
     field: str,
     freqstr: str | None = ...,
     month_kw: int = ...,
-) -> np.ndarray: ...  # np.ndarray[bool]
+) -> npt.NDArray[np.bool_]: ...
 def get_date_field(
-    dtindex: np.ndarray,  # const int64_t[:]
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
     field: str,
-) -> np.ndarray: ...  # np.ndarray[in32]
+) -> npt.NDArray[np.int32]: ...
 def get_timedelta_field(
     tdindex: np.ndarray,  # const int64_t[:]
     field: str,
-) -> np.ndarray: ...  # np.ndarray[int32]
+) -> npt.NDArray[np.int32]: ...
 def isleapyear_arr(
     years: np.ndarray,
-) -> np.ndarray: ...  # np.ndarray[bool]
+) -> npt.NDArray[np.bool_]: ...
 def build_isocalendar_sarray(
-    dtindex: np.ndarray,  # const int64_t[:]
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
 ) -> np.ndarray: ...
 def get_locale_names(name_type: str, locale: object = None): ...
 
@@ -44,7 +46,7 @@ class RoundTo:
     def NEAREST_HALF_MINUS_INFTY(self) -> int: ...
 
 def round_nsint64(
-    values: np.ndarray,  # np.ndarray[np.int64]
+    values: npt.NDArray[np.int64],
     mode: RoundTo,
     nanos: int,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...

pandas/_libs/tslibs/parsing.pyi

@@ -3,6 +3,7 @@ from datetime import datetime
 import numpy as np
 
 from pandas._libs.tslibs.offsets import BaseOffset
+from pandas._typing import npt
 
 class DateParseError(ValueError): ...
 
@@ -21,32 +22,32 @@ def parse_time_string(
 def _does_string_look_like_datetime(py_string: str) -> bool: ...
 def quarter_to_myear(year: int, quarter: int, freq: str) -> tuple[int, int]: ...
 def try_parse_dates(
-    values: np.ndarray,  # object[:]
+    values: npt.NDArray[np.object_],  # object[:]
     parser=...,
     dayfirst: bool = ...,
     default: datetime | None = ...,
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...
 def try_parse_date_and_time(
-    dates: np.ndarray,  # object[:]
-    times: np.ndarray,  # object[:]
+    dates: npt.NDArray[np.object_],  # object[:]
+    times: npt.NDArray[np.object_],  # object[:]
     date_parser=...,
     time_parser=...,
     dayfirst: bool = ...,
     default: datetime | None = ...,
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...
 def try_parse_year_month_day(
-    years: np.ndarray,  # object[:]
-    months: np.ndarray,  # object[:]
-    days: np.ndarray,  # object[:]
-) -> np.ndarray: ...  # np.ndarray[object]
+    years: npt.NDArray[np.object_],  # object[:]
+    months: npt.NDArray[np.object_],  # object[:]
+    days: npt.NDArray[np.object_],  # object[:]
+) -> npt.NDArray[np.object_]: ...
 def try_parse_datetime_components(
-    years: np.ndarray,  # object[:]
-    months: np.ndarray,  # object[:]
-    days: np.ndarray,  # object[:]
-    hours: np.ndarray,  # object[:]
-    minutes: np.ndarray,  # object[:]
-    seconds: np.ndarray,  # object[:]
-) -> np.ndarray: ...  # np.ndarray[object]
+    years: npt.NDArray[np.object_],  # object[:]
+    months: npt.NDArray[np.object_],  # object[:]
+    days: npt.NDArray[np.object_],  # object[:]
+    hours: npt.NDArray[np.object_],  # object[:]
+    minutes: npt.NDArray[np.object_],  # object[:]
+    seconds: npt.NDArray[np.object_],  # object[:]
+) -> npt.NDArray[np.object_]: ...
 def format_is_iso(f: str) -> bool: ...
 def guess_datetime_format(
     dt_str,
@@ -57,5 +58,5 @@ def guess_datetime_format(
 def concat_date_cols(
     date_cols: tuple,
     keep_trivial_numbers: bool = ...,
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...
 def get_rule_month(source: str) -> str: ...

pandas/_libs/tslibs/period.pyi

@@ -8,6 +8,7 @@ from pandas._libs.tslibs.timestamps import Timestamp
 from pandas._typing import (
     Frequency,
     Timezone,
+    npt,
 )
 
 INVALID_FREQ_ERR_MSG: str
@@ -16,30 +17,30 @@ DIFFERENT_FREQ: str
 class IncompatibleFrequency(ValueError): ...
 
 def periodarr_to_dt64arr(
-    periodarr: np.ndarray,  # const int64_t[:]
+    periodarr: npt.NDArray[np.int64],  # const int64_t[:]
     freq: int,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def period_asfreq_arr(
-    arr: np.ndarray,  # ndarray[int64_t] arr,
+    arr: npt.NDArray[np.int64],
     freq1: int,
     freq2: int,
     end: bool,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def get_period_field_arr(
     field: str,
-    arr: np.ndarray,  # const int64_t[:]
+    arr: npt.NDArray[np.int64],  # const int64_t[:]
     freq: int,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def from_ordinals(
-    values: np.ndarray,  # const int64_t[:]
+    values: npt.NDArray[np.int64],  # const int64_t[:]
     freq: Frequency,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def extract_ordinals(
-    values: np.ndarray,  # np.ndarray[object]
+    values: npt.NDArray[np.object_],
     freq: Frequency | int,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def extract_freq(
-    values: np.ndarray,  # np.ndarray[object]
+    values: npt.NDArray[np.object_],
 ) -> BaseOffset: ...
 
 # exposed for tests

pandas/_libs/tslibs/strptime.pyi

@@ -1,7 +1,9 @@
 import numpy as np
 
+from pandas._typing import npt
+
 def array_strptime(
-    values: np.ndarray,  # np.ndarray[object]
+    values: npt.NDArray[np.object_],
     fmt: str | None,
     exact: bool = True,
     errors: str = "raise",

pandas/_libs/tslibs/timedeltas.pyi

@@ -7,6 +7,7 @@ from typing import (
 )
 
 import numpy as np
+from pands._typing import npt
 
 from pandas._libs.tslibs import (
     NaTType,
@@ -16,11 +17,11 @@ from pandas._libs.tslibs import (
 _S = TypeVar("_S")
 
 def ints_to_pytimedelta(
-    arr: np.ndarray,  # const int64_t[:]
+    arr: npt.NDArray[np.int64],  # const int64_t[:]
     box: bool = ...,
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...
 def array_to_timedelta64(
-    values: np.ndarray,  # ndarray[object]
+    values: npt.NDArray[np.object_],
     unit: str | None = ...,
     errors: str = ...,
 ) -> np.ndarray: ...  # np.ndarray[m8ns]

pandas/_libs/tslibs/timezones.pyi

@@ -6,6 +6,8 @@ from typing import Callable
 
 import numpy as np
 
+from pandas._typing import npt
+
 # imported from dateutil.tz
 dateutil_gettz: Callable[[str], tzinfo]
 
@@ -15,9 +17,9 @@ def infer_tzinfo(
     start: datetime | None,
     end: datetime | None,
 ) -> tzinfo | None: ...
-
-# ndarrays returned are both int64_t
-def get_dst_info(tz: tzinfo) -> tuple[np.ndarray, np.ndarray, str]: ...
+def get_dst_info(
+    tz: tzinfo,
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64], str]: ...
 def maybe_get_tz(tz: str | int | np.int64 | tzinfo | None) -> tzinfo | None: ...
 def get_timezone(tz: tzinfo) -> tzinfo | str: ...
 def is_utc(tz: tzinfo | None) -> bool: ...

pandas/_libs/tslibs/tzconversion.pyi

@@ -6,14 +6,16 @@ from typing import Iterable
 
 import numpy as np
 
+from pandas._typing import npt
+
 def tz_convert_from_utc(
-    vals: np.ndarray,  # const int64_t[:]
+    vals: npt.NDArray[np.int64],  # const int64_t[:]
     tz: tzinfo,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.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]
+    vals: npt.NDArray[np.int64],
     tz: tzinfo | None,
     ambiguous: str | bool | Iterable[bool] | None = None,
     nonexistent: str | timedelta | np.timedelta64 | None = None,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...

pandas/_libs/tslibs/vectorized.pyi

@@ -8,28 +8,29 @@ import numpy as np
 
 from pandas._libs.tslibs.dtypes import Resolution
 from pandas._libs.tslibs.offsets import BaseOffset
+from pandas._typing import npt
 
 def dt64arr_to_periodarr(
-    stamps: np.ndarray,  # const int64_t[:]
+    stamps: npt.NDArray[np.int64],  # const int64_t[:]
     freq: int,
     tz: tzinfo | None,
-) -> np.ndarray: ...  # np.ndarray[np.int64, ndim=1]
+) -> npt.NDArray[np.int64]: ...  # np.ndarray[np.int64, ndim=1]
 def is_date_array_normalized(
-    stamps: np.ndarray,  # const int64_t[:]
+    stamps: npt.NDArray[np.int64],  # const int64_t[:]
     tz: tzinfo | None = None,
 ) -> bool: ...
 def normalize_i8_timestamps(
-    stamps: np.ndarray,  # const int64_t[:]
+    stamps: npt.NDArray[np.int64],  # const int64_t[:]
     tz: tzinfo | None,
-) -> np.ndarray: ...  # np.ndarray[np.int64]
+) -> npt.NDArray[np.int64]: ...
 def get_resolution(
-    stamps: np.ndarray,  # const int64_t[:]
+    stamps: npt.NDArray[np.int64],  # const int64_t[:]
     tz: tzinfo | None = None,
 ) -> Resolution: ...
 def ints_to_pydatetime(
-    arr: np.ndarray,  # const int64_t[:}]
+    arr: npt.NDArray[np.int64],  # const int64_t[:}]
     tz: tzinfo | None = None,
     freq: str | BaseOffset | None = None,
     fold: bool = False,
     box: str = "datetime",
-) -> np.ndarray: ...  # np.ndarray[object]
+) -> npt.NDArray[np.object_]: ...

pandas/core/arrays/datetimes.py

@@ -110,11 +110,13 @@ def tz_to_dtype(tz):
         return DatetimeTZDtype(tz=tz)
 
 
-def _field_accessor(name, field, docstring=None):
+def _field_accessor(name: str, field: str, docstring=None):
     def f(self):
         values = self._local_timestamps()
 
         if field in self._bool_ops:
+            result: np.ndarray
+
             if field.endswith(("start", "end")):
                 freq = self.freq
                 month_kw = 12