ENH: Overload to_datetime when errors is coerce

Have to_datetime possibly returning NaTType when errors are coerce and scalar input

Author: bashtage

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 = ...,

tests/test_timefuncs.py

@@ -4,13 +4,16 @@
 from typing import (
     TYPE_CHECKING,
     Optional,
+    Union,
 )
 
 import numpy as np
 from numpy import typing as npt
 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,11 @@ 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:
+    assert_type(pd.to_datetime("2021-03-01", errors="ignore"), "pd.Timestamp")
+    assert_type(pd.to_datetime("2021-03-01", errors="raise"), "pd.Timestamp")
+    assert_type(
+        pd.to_datetime("2021-03-01", errors="coerce"), "Union[pd.Timestamp, NaTType]"
+    )