TYP: tslib.pyi (#40473)

Author: jbrockmendel

pandas/_libs/tslib.pyi

@@ -0,0 +1,29 @@
+from datetime import tzinfo
+
+import numpy as np
+
+def format_array_from_datetime(
+    values: np.ndarray,   # np.ndarray[np.int64]
+    tz: tzinfo | None = ...,
+    format: str | None = ...,
+    na_rep: object = ...
+) -> np.ndarray: ...  # np.ndarray[object]
+
+
+def array_with_unit_to_datetime(
+    values: np.ndarray,
+    unit: str,
+    errors: str = ...,
+) -> tuple[np.ndarray, tzinfo | None]: ...
+
+
+def array_to_datetime(
+    values: np.ndarray,  # np.ndarray[object]
+    errors: str = ...,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    utc: bool = ...,
+    require_iso8601: bool = ...,
+    allow_mixed: bool = ...,
+) -> tuple[np.ndarray, tzinfo | None]: ...
+# returned ndarray may be object dtype or datetime64[ns]

pandas/_libs/tslib.pyx

@@ -100,7 +100,7 @@ def format_array_from_datetime(
     tzinfo tz=None,
     str format=None,
     object na_rep=None
-):
+) -> np.ndarray:
     """
     return a np object array of the string formatted values
 
@@ -113,6 +113,9 @@ def format_array_from_datetime(
     na_rep : optional, default is None
           a nat format
 
+    Returns
+    -------
+    np.ndarray[object]
     """
     cdef:
         int64_t val, ns, N = len(values)
@@ -200,7 +203,7 @@ def array_with_unit_to_datetime(
 
     Parameters
     ----------
-    values : ndarray of object
+    values : ndarray
          Date-like objects to convert.
     unit : str
          Time unit to use during conversion.
@@ -411,7 +414,9 @@ cpdef array_to_datetime(
 
     Returns
     -------
-    tuple (ndarray, tzoffset)
+    np.ndarray
+        May be datetime64[ns] or object dtype
+    tzinfo or None
     """
     cdef:
         Py_ssize_t i, n = len(values)
@@ -635,7 +640,7 @@ cpdef array_to_datetime(
     return result, tz_out
 
 
-cdef ignore_errors_out_of_bounds_fallback(ndarray[object] values):
+cdef ndarray[object] ignore_errors_out_of_bounds_fallback(ndarray[object] values):
     """
     Fallback for array_to_datetime if an OutOfBoundsDatetime is raised
     and errors == "ignore"
@@ -689,7 +694,7 @@ cdef _array_to_datetime_object(
 
     Parameters
     ----------
-    values : ndarray of object
+    values : ndarray[object]
          date-like objects to convert
     errors : str
          error behavior when parsing
@@ -700,7 +705,8 @@ cdef _array_to_datetime_object(
 
     Returns
     -------
-    tuple (ndarray, None)
+    np.ndarray[object]
+    Literal[None]
     """
     cdef:
         Py_ssize_t i, n = len(values)

pandas/core/arrays/datetimes.py

@@ -2154,7 +2154,7 @@ def objects_to_datetime64ns(
     data = np.array(data, copy=False, dtype=np.object_)
 
     flags = data.flags
-    order = "F" if flags.f_contiguous else "C"
+    order: Literal["F", "C"] = "F" if flags.f_contiguous else "C"
     try:
         result, tz_parsed = tslib.array_to_datetime(
             data.ravel("K"),

pandas/core/tools/datetimes.py

@@ -307,9 +307,9 @@ def _convert_listlike_datetimes(
         None or string for the Index name
     tz : object
         None or 'utc'
-    unit : string
+    unit : str
         None or string of the frequency of the passed data
-    errors : string
+    errors : str
         error handing behaviors from to_datetime, 'raise', 'coerce', 'ignore'
     infer_datetime_format : bool, default False
         inferring format behavior from to_datetime
@@ -529,7 +529,7 @@ def _to_datetime_with_format(
     return result  # type: ignore[return-value]
 
 
-def _to_datetime_with_unit(arg, unit, name, tz, errors: Optional[str]) -> Index:
+def _to_datetime_with_unit(arg, unit, name, tz, errors: str) -> Index:
     """
     to_datetime specalized to the case where a 'unit' is passed.
     """
@@ -1035,7 +1035,7 @@ def coerce(values):
     return values
 
 
-def _attempt_YYYYMMDD(arg: np.ndarray, errors: Optional[str]) -> Optional[np.ndarray]:
+def _attempt_YYYYMMDD(arg: np.ndarray, errors: str) -> Optional[np.ndarray]:
     """
     try to parse the YYYYMMDD/%Y%m%d format, try to deal with NaT-like,
     arg is a passed in as an object dtype, but could really be ints/strings

pandas/tests/indexes/multi/test_constructors.py

@@ -7,15 +7,14 @@
 import numpy as np
 import pytest
 
-from pandas._libs.tslib import Timestamp
-
 from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
 
 import pandas as pd
 from pandas import (
     Index,
     MultiIndex,
     Series,
+    Timestamp,
     date_range,
 )
 import pandas._testing as tm

pandas/tests/indexes/test_base.py

@@ -10,7 +10,6 @@
 import numpy as np
 import pytest
 
-from pandas._libs.tslib import Timestamp
 from pandas.compat import (
     IS64,
     np_datetime64_compat,
@@ -29,6 +28,7 @@
     RangeIndex,
     Series,
     TimedeltaIndex,
+    Timestamp,
     UInt64Index,
     date_range,
     isna,

pandas/tests/io/json/test_ujson.py

@@ -14,7 +14,6 @@
 import pytz
 
 import pandas._libs.json as ujson
-from pandas._libs.tslib import Timestamp
 from pandas.compat import (
     IS64,
     is_platform_windows,
@@ -28,6 +27,7 @@
     NaT,
     Series,
     Timedelta,
+    Timestamp,
     date_range,
 )
 import pandas._testing as tm

pandas/tests/io/parser/common/test_common_basic.py

@@ -11,7 +11,6 @@
 import numpy as np
 import pytest
 
-from pandas._libs.tslib import Timestamp
 from pandas.errors import (
     EmptyDataError,
     ParserError,
@@ -21,6 +20,7 @@
     DataFrame,
     Index,
     Series,
+    Timestamp,
     compat,
 )
 import pandas._testing as tm

pandas/tests/io/parser/test_parse_dates.py

@@ -19,7 +19,6 @@
 import pytest
 import pytz
 
-from pandas._libs.tslib import Timestamp
 from pandas._libs.tslibs import parsing
 from pandas._libs.tslibs.parsing import parse_datetime_string
 from pandas.compat import (
@@ -34,6 +33,7 @@
     Index,
     MultiIndex,
     Series,
+    Timestamp,
 )
 import pandas._testing as tm
 from pandas.core.indexes.datetimes import date_range

pandas/tests/io/parser/usecols/test_parse_dates.py

@@ -6,11 +6,10 @@
 
 import pytest
 
-from pandas._libs.tslib import Timestamp
-
 from pandas import (
     DataFrame,
     Index,
+    Timestamp,
 )
 import pandas._testing as tm
 

pandas/tests/tools/test_to_datetime.py

@@ -1157,7 +1157,7 @@ def test_unit(self, cache):
         tm.assert_index_equal(result, expected)
 
         msg = "cannot convert input 11111111 with the unit 'D'"
-        with pytest.raises(tslib.OutOfBoundsDatetime, match=msg):
+        with pytest.raises(OutOfBoundsDatetime, match=msg):
             to_datetime(values, unit="D", errors="raise", cache=cache)
 
         values = [1420043460000, iNaT, NaT, np.nan, "NaT"]
@@ -1171,15 +1171,15 @@ def test_unit(self, cache):
         tm.assert_index_equal(result, expected)
 
         msg = "cannot convert input 1420043460000 with the unit 's'"
-        with pytest.raises(tslib.OutOfBoundsDatetime, match=msg):
+        with pytest.raises(OutOfBoundsDatetime, match=msg):
             to_datetime(values, errors="raise", unit="s", cache=cache)
 
         # if we have a string, then we raise a ValueError
         # and NOT an OutOfBoundsDatetime
         for val in ["foo", Timestamp("20130101")]:
             try:
                 to_datetime(val, errors="raise", unit="s", cache=cache)
-            except tslib.OutOfBoundsDatetime as err:
+            except OutOfBoundsDatetime as err:
                 raise AssertionError("incorrect exception raised") from err
             except ValueError:
                 pass
@@ -2347,7 +2347,7 @@ def test_epoch(self, units, epochs, epoch_1960, units_from_epochs):
             ("random_string", ValueError),
             ("epoch", ValueError),
             ("13-24-1990", ValueError),
-            (datetime(1, 1, 1), tslib.OutOfBoundsDatetime),
+            (datetime(1, 1, 1), OutOfBoundsDatetime),
         ],
     )
     def test_invalid_origins(self, origin, exc, units, units_from_epochs):