TYP: expand acceptable types for pd.to_datetime() (pandas-dev#46273)

Author: Dr-Irv

pandas/core/tools/datetimes.py

@@ -10,6 +10,7 @@
     Hashable,
     List,
     Tuple,
+    TypedDict,
     Union,
     cast,
     overload,
@@ -79,16 +80,42 @@
 if TYPE_CHECKING:
     from pandas._libs.tslibs.nattype import NaTType
 
-    from pandas import Series
+    from pandas import (
+        DataFrame,
+        Series,
+    )
 
 # ---------------------------------------------------------------------
 # types used in annotations
 
-ArrayConvertible = Union[List, Tuple, AnyArrayLike, "Series"]
+ArrayConvertible = Union[List, Tuple, AnyArrayLike]
 Scalar = Union[int, float, str]
 DatetimeScalar = Union[Scalar, datetime]
 
 DatetimeScalarOrArrayConvertible = Union[DatetimeScalar, ArrayConvertible]
+
+DatetimeDictArg = Union[List[Scalar], Tuple[Scalar, ...], AnyArrayLike]
+
+
+class YearMonthDayDict(TypedDict, total=True):
+    year: DatetimeDictArg
+    month: DatetimeDictArg
+    day: DatetimeDictArg
+
+
+class FulldatetimeDict(YearMonthDayDict, total=False):
+    hour: DatetimeDictArg
+    hours: DatetimeDictArg
+    minute: DatetimeDictArg
+    minutes: DatetimeDictArg
+    second: DatetimeDictArg
+    seconds: DatetimeDictArg
+    ms: DatetimeDictArg
+    us: DatetimeDictArg
+    ns: DatetimeDictArg
+
+
+DictConvertible = Union[FulldatetimeDict, "DataFrame"]
 start_caching_at = 50
 
 
@@ -640,13 +667,13 @@ def to_datetime(
     infer_datetime_format: bool = ...,
     origin=...,
     cache: bool = ...,
-) -> Timestamp | NaTType:
+) -> Timestamp:
     ...
 
 
 @overload
 def to_datetime(
-    arg: Series,
+    arg: Series | DictConvertible,
     errors: str = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
@@ -663,7 +690,7 @@ def to_datetime(
 
 @overload
 def to_datetime(
-    arg: list | tuple | np.ndarray,
+    arg: list | tuple | Index | ArrayLike,
     errors: str = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
@@ -679,7 +706,7 @@ def to_datetime(
 
 
 def to_datetime(
-    arg: DatetimeScalarOrArrayConvertible,
+    arg: DatetimeScalarOrArrayConvertible | DictConvertible,
     errors: str = "raise",
     dayfirst: bool = False,
     yearfirst: bool = False,
@@ -1067,10 +1094,10 @@ def to_datetime(
             # "Union[float, str, datetime, List[Any], Tuple[Any, ...], ExtensionArray,
             # ndarray[Any, Any], Series]"; expected "Union[List[Any], Tuple[Any, ...],
             # Union[Union[ExtensionArray, ndarray[Any, Any]], Index, Series], Series]"
-            arg = cast(
+            argc = cast(
                 Union[list, tuple, ExtensionArray, np.ndarray, "Series", Index], arg
             )
-            cache_array = _maybe_cache(arg, format, cache, convert_listlike)
+            cache_array = _maybe_cache(argc, format, cache, convert_listlike)
         except OutOfBoundsDatetime:
             # caching attempts to create a DatetimeIndex, which may raise
             # an OOB. If that's the desired behavior, then just reraise...
@@ -1081,9 +1108,9 @@ def to_datetime(
 
             cache_array = Series([], dtype=object)  # just an empty array
         if not cache_array.empty:
-            result = _convert_and_box_cache(arg, cache_array)
+            result = _convert_and_box_cache(argc, cache_array)
         else:
-            result = convert_listlike(arg, format)
+            result = convert_listlike(argc, format)
     else:
         result = convert_listlike(np.array([arg]), format)[0]
         if isinstance(arg, bool) and isinstance(result, np.bool_):

pandas/io/excel/_odfreader.py

@@ -214,9 +214,7 @@ def _get_cell_value(self, cell, convert_float: bool) -> Scalar | NaTType:
             cell_value = cell.attributes.get((OFFICENS, "date-value"))
             return pd.to_datetime(cell_value)
         elif cell_type == "time":
-            # cast needed because `pd.to_datetime can return NaTType,
-            # but we know this is a valid time
-            stamp = cast(pd.Timestamp, pd.to_datetime(str(cell)))
+            stamp = pd.to_datetime(str(cell))
             # cast needed here because Scalar doesn't include datetime.time
             return cast(Scalar, stamp.time())
         else: