CLN: tslibs typing, docstrings

Author: jbrockmendel

pandas/_libs/tslib.pyx

@@ -188,7 +188,7 @@ def ints_to_pydatetime(const int64_t[:] arr, object tz=None, object freq=None,
     return result
 
 
-def _test_parse_iso8601(object ts):
+def _test_parse_iso8601(ts: str):
     """
     TESTING ONLY: Parse string into Timestamp using iso8601 parser. Used
     only for testing, actual construction uses `convert_str_to_tsobject`

pandas/_libs/tslibs/conversion.pyx

@@ -444,15 +444,15 @@ cdef _TSObject convert_str_to_tsobject(object ts, object tz, object unit,
                                        bint dayfirst=False,
                                        bint yearfirst=False):
     """
-    Convert a string-like (bytes or unicode) input `ts`, along with optional
-    timezone object `tz` to a _TSObject.
+    Convert a string input `ts`, along with optional timezone object`tz`
+    to a _TSObject.
 
     The optional arguments `dayfirst` and `yearfirst` are passed to the
     dateutil parser.
 
     Parameters
     ----------
-    ts : bytes or unicode
+    ts : str
         Value to be converted to _TSObject
     tz : tzinfo or None
         timezone for the timezone-aware output

pandas/_libs/tslibs/np_datetime.pxd

@@ -72,6 +72,6 @@ cdef npy_datetime get_datetime64_value(object obj) nogil
 cdef npy_timedelta get_timedelta64_value(object obj) nogil
 cdef NPY_DATETIMEUNIT get_datetime64_unit(object obj) nogil
 
-cdef int _string_to_dts(object val, npy_datetimestruct* dts,
+cdef int _string_to_dts(str val, npy_datetimestruct* dts,
                         int* out_local, int* out_tzoffset,
                         bint want_exc) except? -1

pandas/_libs/tslibs/np_datetime.pyx

@@ -167,7 +167,7 @@ cdef inline int64_t pydate_to_dt64(date val, npy_datetimestruct *dts):
     return dtstruct_to_dt64(dts)
 
 
-cdef inline int _string_to_dts(object val, npy_datetimestruct* dts,
+cdef inline int _string_to_dts(str val, npy_datetimestruct* dts,
                                int* out_local, int* out_tzoffset,
                                bint want_exc) except? -1:
     cdef:

pandas/_libs/tslibs/parsing.pyx

@@ -86,16 +86,15 @@ cdef inline int _parse_4digit(const char* s):
     return result
 
 
-cdef inline object _parse_delimited_date(object date_string, bint dayfirst):
+cdef inline object _parse_delimited_date(str date_string, bint dayfirst):
     """
     Parse special cases of dates: MM/DD/YYYY, DD/MM/YYYY, MM/YYYY.
+
     At the beginning function tries to parse date in MM/DD/YYYY format, but
     if month > 12 - in DD/MM/YYYY (`dayfirst == False`).
     With `dayfirst == True` function makes an attempt to parse date in
     DD/MM/YYYY, if an attempt is wrong - in DD/MM/YYYY
 
-    Note
-    ----
     For MM/DD/YYYY, DD/MM/YYYY: delimiter can be a space or one of /-.
     For MM/YYYY: delimiter can be a space or one of /-
     If `date_string` can't be converted to date, then function returns
@@ -104,11 +103,13 @@ cdef inline object _parse_delimited_date(object date_string, bint dayfirst):
     Parameters
     ----------
     date_string : str
-    dayfirst : bint
+    dayfirst : bool
 
     Returns:
     --------
-    datetime, resolution
+    datetime or Nont
+    str or None
+        Describing resolution of the parsed string.
     """
     cdef:
         const char* buf
@@ -156,18 +157,19 @@ cdef inline object _parse_delimited_date(object date_string, bint dayfirst):
     raise DateParseError(f"Invalid date specified ({month}/{day})")
 
 
-cdef inline bint does_string_look_like_time(object parse_string):
+cdef inline bint does_string_look_like_time(str parse_string):
     """
     Checks whether given string is a time: it has to start either from
     H:MM or from HH:MM, and hour and minute values must be valid.
 
     Parameters
     ----------
-    date_string : str
+    parse_string : str
 
     Returns:
     --------
-    whether given string is a time
+    bool
+        Whether given string is potentially a time.
     """
     cdef:
         const char* buf
@@ -188,9 +190,10 @@ cdef inline bint does_string_look_like_time(object parse_string):
     return 0 <= hour <= 23 and 0 <= minute <= 59
 
 
-def parse_datetime_string(date_string, freq=None, dayfirst=False,
+def parse_datetime_string(date_string: str, freq=None, dayfirst=False,
                           yearfirst=False, **kwargs):
-    """parse datetime string, only returns datetime.
+    """
+    Parse datetime string, only returns datetime.
     Also cares special handling matching time patterns.
 
     Returns
@@ -270,16 +273,17 @@ def parse_time_string(arg: str, freq=None, dayfirst=None, yearfirst=None):
     return res
 
 
-cdef parse_datetime_string_with_reso(date_string, freq=None, dayfirst=False,
+cdef parse_datetime_string_with_reso(str date_string, freq=None, dayfirst=False,
                                      yearfirst=False):
-    """parse datetime string, only returns datetime
+    """
+    Parse datetime string and try to identify its resolution.
 
     Returns
     -------
-    parsed : datetime
-    parsed2 : datetime/dateutil.parser._result
-    reso : str
-        inferred resolution
+    datetime
+    datetime/dateutil.parser._result
+    str
+        Inferred resolution of the parsed string.
 
     Raises
     ------
@@ -315,18 +319,19 @@ cdef parse_datetime_string_with_reso(date_string, freq=None, dayfirst=False,
     return parsed, parsed, reso
 
 
-cpdef bint _does_string_look_like_datetime(object py_string):
+cpdef bint _does_string_look_like_datetime(str py_string):
     """
     Checks whether given string is a datetime: it has to start with '0' or
     be greater than 1000.
 
     Parameters
     ----------
-    py_string: object
+    py_string: str
 
     Returns
     -------
-    whether given string is a datetime
+    bool
+        Whether given string is potentially a datetime.
     """
     cdef:
         const char *buf
@@ -370,9 +375,6 @@ cdef inline object _parse_dateabbr_string(object date_string, object default,
     # special handling for possibilities eg, 2Q2005, 2Q05, 2005Q1, 05Q1
     assert isinstance(date_string, str)
 
-    # len(date_string) == 0
-    # should be NaT???
-
     if date_string in nat_strings:
         return NaT, NaT, ''
 
@@ -530,7 +532,7 @@ cdef dateutil_parse(object timestr, object default, ignoretz=False,
     return ret, reso
 
 
-cdef object _get_rule_month(object source, object default='DEC'):
+cdef str _get_rule_month(object source):
     """
     Return starting month of given freq, default is December.
 
@@ -546,7 +548,8 @@ cdef object _get_rule_month(object source, object default='DEC'):
         source = source.freqstr
     source = source.upper()
     if '-' not in source:
-        return default
+        # Default is December
+        return "DEC"
     else:
         return source.split('-')[1]
 
@@ -939,14 +942,14 @@ def _concat_date_cols(tuple date_cols, bint keep_trivial_numbers=True):
 
     Parameters
     ----------
-    date_cols : tuple of numpy arrays
+    date_cols : tuple[ndarray]
     keep_trivial_numbers : bool, default True
         if True and len(date_cols) == 1, then
         conversion (to string from integer/float zero) is not performed
 
     Returns
     -------
-    arr_of_rows : ndarray (dtype=object)
+    arr_of_rows : ndarray[object]
 
     Examples
     --------

pandas/_libs/tslibs/period.pyx

@@ -1191,12 +1191,15 @@ cdef int64_t period_ordinal_to_dt64(int64_t ordinal, int freq) except? -1:
     return dtstruct_to_dt64(&dts)
 
 
-def period_format(int64_t value, int freq, object fmt=None):
+cdef str period_format(int64_t value, int freq, object fmt=None):
     cdef:
         int freq_group
 
     if value == NPY_NAT:
-        return repr(NaT)
+        return "NaT"
+
+    if isinstance(fmt, str):
+        fmt = fmt.encode("utf-8")
 
     if fmt is None:
         freq_group = get_freq_group(freq)
@@ -1242,24 +1245,22 @@ cdef list extra_fmts = [(b"%q", b"^`AB`^"),
 cdef list str_extra_fmts = ["^`AB`^", "^`CD`^", "^`EF`^",
                             "^`GH`^", "^`IJ`^", "^`KL`^"]
 
-cdef object _period_strftime(int64_t value, int freq, object fmt):
+cdef str _period_strftime(int64_t value, int freq, bytes fmt):
     cdef:
         Py_ssize_t i
         npy_datetimestruct dts
         char *formatted
-        object pat, repl, result
+        bytes pat, brepl
         list found_pat = [False] * len(extra_fmts)
         int year, quarter
-
-    if isinstance(fmt, unicode):
-        fmt = fmt.encode('utf-8')
+        str result, repl
 
     get_date_info(value, freq, &dts)
     for i in range(len(extra_fmts)):
         pat = extra_fmts[i][0]
-        repl = extra_fmts[i][1]
+        brepl = extra_fmts[i][1]
         if pat in fmt:
-            fmt = fmt.replace(pat, repl)
+            fmt = fmt.replace(pat, brepl)
             found_pat[i] = True
 
     formatted = c_strftime(&dts, <char*>fmt)
@@ -2234,7 +2235,7 @@ cdef class _Period:
         object_state = None, self.freq, self.ordinal
         return (Period, object_state)
 
-    def strftime(self, fmt):
+    def strftime(self, fmt: str) -> str:
         """
         Returns the string representation of the :class:`Period`, depending
         on the selected ``fmt``. ``fmt`` must be a string

pandas/plotting/_matplotlib/converter.py

@@ -1097,6 +1097,8 @@ def __call__(self, x, pos=0):
             return ""
         else:
             fmt = self.formatdict.pop(x, "")
+            if isinstance(fmt, np.bytes_):
+                fmt = fmt.decode("utf-8")
             return Period(ordinal=int(x), freq=self.freq).strftime(fmt)