diff --git a/pandas-stubs/core/tools/datetimes.pyi b/pandas-stubs/core/tools/datetimes.pyi index af8c4fdb4..7b3be825c 100644 --- a/pandas-stubs/core/tools/datetimes.pyi +++ b/pandas-stubs/core/tools/datetimes.pyi @@ -1,6 +1,7 @@ from datetime import datetime as datetime from typing import ( List, + Literal, Optional, Tuple, TypedDict, @@ -18,6 +19,7 @@ from pandas.core.series import ( TimestampSeries, ) +from pandas._libs.tslibs import NaTType from pandas._typing import ( AnyArrayLike as AnyArrayLike, ArrayLike as ArrayLike, @@ -61,7 +63,7 @@ def should_cache( @overload def to_datetime( arg: DatetimeScalar, - errors: DateTimeErrorChoices = ..., + errors: Literal["ignore", "raise"] = ..., dayfirst: bool = ..., yearfirst: bool = ..., utc: bool | None = ..., @@ -73,6 +75,20 @@ def to_datetime( cache: bool = ..., ) -> Timestamp: ... @overload +def to_datetime( + arg: DatetimeScalar, + errors: Literal["coerce"], + dayfirst: bool = ..., + yearfirst: bool = ..., + utc: bool | None = ..., + format: str | None = ..., + exact: bool = ..., + unit: str | None = ..., + infer_datetime_format: bool = ..., + origin=..., + cache: bool = ..., +) -> Timestamp | NaTType: ... +@overload def to_datetime( arg: Series | DictConvertible, errors: DateTimeErrorChoices = ..., diff --git a/tests/test_timefuncs.py b/tests/test_timefuncs.py index 8572cd485..8fb296675 100644 --- a/tests/test_timefuncs.py +++ b/tests/test_timefuncs.py @@ -4,6 +4,7 @@ from typing import ( TYPE_CHECKING, Optional, + Union, ) import numpy as np @@ -11,6 +12,8 @@ import pandas as pd from typing_extensions import assert_type +from pandas._libs import NaTType + if TYPE_CHECKING: from pandas.core.series import ( TimedeltaSeries, @@ -209,3 +212,29 @@ def test_comparisons_datetimeindex() -> None: assert_type((dti <= ts), np_ndarray_bool) assert_type((dti == ts), np_ndarray_bool) assert_type((dti != ts), np_ndarray_bool) + + +def test_to_datetime_nat() -> None: + # GH 88 + assert isinstance( + assert_type(pd.to_datetime("2021-03-01", errors="ignore"), "pd.Timestamp"), + pd.Timestamp, + ) + assert isinstance( + assert_type(pd.to_datetime("2021-03-01", errors="raise"), "pd.Timestamp"), + pd.Timestamp, + ) + assert isinstance( + assert_type( + pd.to_datetime("2021-03-01", errors="coerce"), + "Union[pd.Timestamp, NaTType]", + ), + pd.Timestamp, + ) + assert isinstance( + assert_type( + pd.to_datetime("not a date", errors="coerce"), + "Union[pd.Timestamp, NaTType]", + ), + NaTType, + )