TYP: tslibs.parsing.pyi (pandas-dev#40576)

Author: jbrockmendel

pandas/_libs/tslibs/parsing.pyi

@@ -0,0 +1,81 @@
+from datetime import datetime
+
+import numpy as np
+
+from pandas._libs.tslibs.offsets import BaseOffset
+
+class DateParseError(ValueError): ...
+
+
+def parse_datetime_string(
+    date_string: str,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    **kwargs,
+) -> datetime: ...
+
+
+def parse_time_string(
+    arg: str,
+    freq: BaseOffset | str | None = ...,
+    dayfirst: bool | None = ...,
+    yearfirst: bool | None = ...,
+) -> tuple[datetime, str]: ...
+
+
+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[:]
+    parser=...,
+    dayfirst: bool = ...,
+    default: datetime | None = ...,
+) -> np.ndarray: ...  # np.ndarray[object]
+
+def try_parse_date_and_time(
+    dates: np.ndarray,  # object[:]
+    times: np.ndarray,  # object[:]
+    date_parser=...,
+    time_parser=...,
+    dayfirst: bool = ...,
+    default: datetime | None = ...,
+) -> np.ndarray: ... # np.ndarray[object]
+
+def try_parse_year_month_day(
+    years: np.ndarray,  # object[:]
+    months: np.ndarray, # object[:]
+    days: np.ndarray,   # object[:]
+) -> np.ndarray: ...    # np.ndarray[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]
+
+
+def format_is_iso(f: str) -> bool: ...
+
+
+def guess_datetime_format(
+    dt_str,
+    dayfirst: bool = ...,
+    dt_str_parse=...,
+    dt_str_split=...,
+) -> str | None: ...
+
+
+def concat_date_cols(
+    date_cols: tuple,
+    keep_trivial_numbers: bool = ...,
+) -> np.ndarray: ...  # np.ndarray[object]
+
+
+def get_rule_month(source: str) -> str: ...

pandas/_libs/tslibs/parsing.pyx

@@ -219,7 +219,7 @@ def parse_datetime_string(
     bint dayfirst=False,
     bint yearfirst=False,
     **kwargs,
-):
+) -> datetime:
     """
     Parse datetime string, only returns datetime.
     Also cares special handling matching time patterns.
@@ -281,7 +281,9 @@ def parse_time_string(arg: str, freq=None, dayfirst=None, yearfirst=None):
 
     Returns
     -------
-    datetime, datetime/dateutil.parser._result, str
+    datetime
+    str
+        Describing resolution of parsed string.
     """
     if is_offset_object(freq):
         freq = freq.rule_code
@@ -595,7 +597,7 @@ cdef dateutil_parse(
 
 def try_parse_dates(
     object[:] values, parser=None, bint dayfirst=False, default=None,
-):
+) -> np.ndarray:
     cdef:
         Py_ssize_t i, n
         object[:] result
@@ -639,7 +641,7 @@ def try_parse_date_and_time(
     time_parser=None,
     bint dayfirst=False,
     default=None,
-):
+) -> np.ndarray:
     cdef:
         Py_ssize_t i, n
         object[:] result
@@ -675,7 +677,9 @@ def try_parse_date_and_time(
     return result.base  # .base to access underlying ndarray
 
 
-def try_parse_year_month_day(object[:] years, object[:] months, object[:] days):
+def try_parse_year_month_day(
+    object[:] years, object[:] months, object[:] days
+) -> np.ndarray:
     cdef:
         Py_ssize_t i, n
         object[:] result
@@ -697,7 +701,7 @@ def try_parse_datetime_components(object[:] years,
                                   object[:] days,
                                   object[:] hours,
                                   object[:] minutes,
-                                  object[:] seconds):
+                                  object[:] seconds) -> np.ndarray:
 
     cdef:
         Py_ssize_t i, n
@@ -988,7 +992,7 @@ cdef inline object convert_to_unicode(object item, bint keep_trivial_numbers):
 
 @cython.wraparound(False)
 @cython.boundscheck(False)
-def concat_date_cols(tuple date_cols, bint keep_trivial_numbers=True):
+def concat_date_cols(tuple date_cols, bint keep_trivial_numbers=True) -> np.ndarray:
     """
     Concatenates elements from numpy arrays in `date_cols` into strings.
 

pandas/core/indexes/datetimes.py

@@ -636,7 +636,7 @@ def _validate_partial_date_slice(self, reso: Resolution):
             # See also GH14826
             raise KeyError
 
-        if reso == "microsecond":
+        if reso.attrname == "microsecond":
             # _partial_date_slice doesn't allow microsecond resolution, but
             # _parsed_string_to_bounds allows it.
             raise KeyError
@@ -748,11 +748,11 @@ def _maybe_cast_slice_bound(self, label, side: str, kind):
         if isinstance(label, str):
             freq = getattr(self, "freqstr", getattr(self, "inferred_freq", None))
             try:
-                parsed, reso = parsing.parse_time_string(label, freq)
+                parsed, reso_str = parsing.parse_time_string(label, freq)
             except parsing.DateParseError as err:
                 raise self._invalid_indexer("slice", label) from err
 
-            reso = Resolution.from_attrname(reso)
+            reso = Resolution.from_attrname(reso_str)
             lower, upper = self._parsed_string_to_bounds(reso, parsed)
             # lower, upper form the half-open interval:
             #   [parsed, parsed + 1 freq)
@@ -772,8 +772,8 @@ def _maybe_cast_slice_bound(self, label, side: str, kind):
 
     def _get_string_slice(self, key: str):
         freq = getattr(self, "freqstr", getattr(self, "inferred_freq", None))
-        parsed, reso = parsing.parse_time_string(key, freq)
-        reso = Resolution.from_attrname(reso)
+        parsed, reso_str = parsing.parse_time_string(key, freq)
+        reso = Resolution.from_attrname(reso_str)
         return self._partial_date_slice(reso, parsed)
 
     def slice_indexer(self, start=None, end=None, step=None, kind=None):

pandas/core/indexes/period.py

@@ -490,12 +490,12 @@ def get_loc(self, key, method=None, tolerance=None):
                 pass
 
             try:
-                asdt, reso = parse_time_string(key, self.freq)
+                asdt, reso_str = parse_time_string(key, self.freq)
             except (ValueError, DateParseError) as err:
                 # A string with invalid format
                 raise KeyError(f"Cannot interpret '{key}' as period") from err
 
-            reso = Resolution.from_attrname(reso)
+            reso = Resolution.from_attrname(reso_str)
             grp = reso.freq_group.value
             freqn = self.dtype.freq_group_code
 
@@ -556,8 +556,8 @@ def _maybe_cast_slice_bound(self, label, side: str, kind: str):
             return Period(label, freq=self.freq)
         elif isinstance(label, str):
             try:
-                parsed, reso = parse_time_string(label, self.freq)
-                reso = Resolution.from_attrname(reso)
+                parsed, reso_str = parse_time_string(label, self.freq)
+                reso = Resolution.from_attrname(reso_str)
                 bounds = self._parsed_string_to_bounds(reso, parsed)
                 return bounds[0 if side == "left" else 1]
             except ValueError as err:
@@ -585,8 +585,8 @@ def _validate_partial_date_slice(self, reso: Resolution):
             raise ValueError
 
     def _get_string_slice(self, key: str):
-        parsed, reso = parse_time_string(key, self.freq)
-        reso = Resolution.from_attrname(reso)
+        parsed, reso_str = parse_time_string(key, self.freq)
+        reso = Resolution.from_attrname(reso_str)
         try:
             return self._partial_date_slice(reso, parsed)
         except KeyError as err: