diff --git a/pandas/_libs/tslib.pyi b/pandas/_libs/tslib.pyi new file mode 100644 index 0000000000000..641e62e7c8973 --- /dev/null +++ b/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] diff --git a/pandas/_libs/tslib.pyx b/pandas/_libs/tslib.pyx index 337e131f0a2c9..02c64fac0c009 100644 --- a/pandas/_libs/tslib.pyx +++ b/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) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 4a032c60d386d..c0a8c20832fa8 100644 --- a/pandas/core/arrays/datetimes.py +++ b/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"), diff --git a/pandas/core/tools/datetimes.py b/pandas/core/tools/datetimes.py index c1c14ade320a3..2fd91c07ff4ac 100644 --- a/pandas/core/tools/datetimes.py +++ b/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 diff --git a/pandas/tests/indexes/multi/test_constructors.py b/pandas/tests/indexes/multi/test_constructors.py index 79a60c14f5eac..63b0bd235e57c 100644 --- a/pandas/tests/indexes/multi/test_constructors.py +++ b/pandas/tests/indexes/multi/test_constructors.py @@ -7,8 +7,6 @@ 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 @@ -16,6 +14,7 @@ Index, MultiIndex, Series, + Timestamp, date_range, ) import pandas._testing as tm diff --git a/pandas/tests/indexes/test_base.py b/pandas/tests/indexes/test_base.py index 53d3187ee5664..1e9348dc410d7 100644 --- a/pandas/tests/indexes/test_base.py +++ b/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, diff --git a/pandas/tests/io/json/test_ujson.py b/pandas/tests/io/json/test_ujson.py index b6c565bdeace5..c0337d1ad3ffe 100644 --- a/pandas/tests/io/json/test_ujson.py +++ b/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 diff --git a/pandas/tests/io/parser/common/test_common_basic.py b/pandas/tests/io/parser/common/test_common_basic.py index 297cbbe66cb6b..572bc09c96886 100644 --- a/pandas/tests/io/parser/common/test_common_basic.py +++ b/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 diff --git a/pandas/tests/io/parser/test_parse_dates.py b/pandas/tests/io/parser/test_parse_dates.py index 257dce7d28972..c7b5efa5bf0c9 100644 --- a/pandas/tests/io/parser/test_parse_dates.py +++ b/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 diff --git a/pandas/tests/io/parser/usecols/test_parse_dates.py b/pandas/tests/io/parser/usecols/test_parse_dates.py index 7f813b8733061..44ea3866dd793 100644 --- a/pandas/tests/io/parser/usecols/test_parse_dates.py +++ b/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 diff --git a/pandas/tests/tools/test_to_datetime.py b/pandas/tests/tools/test_to_datetime.py index 91f6c100419b6..cefbea529e366 100644 --- a/pandas/tests/tools/test_to_datetime.py +++ b/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,7 +1171,7 @@ 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 @@ -1179,7 +1179,7 @@ def test_unit(self, cache): 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):