ENH: Improve general datetime functions

pandas-stubs/_libs/tslibs/timedeltas.pyi

@@ -3,6 +3,7 @@ from typing import (
     ClassVar,
     Literal,
     TypeVar,
+    Union,
     overload,
 )
 
@@ -17,10 +18,7 @@ from pandas._typing import npt
 
 # This should be kept consistent with the keys in the dict timedelta_abbrevs
 # in pandas/_libs/tslibs/timedeltas.pyx
-UnitChoices: TypeAlias = Literal[
-    "Y",
-    "y",
-    "M",
+TimeDeltaUnitChoices: TypeAlias = Literal[
     "W",
     "w",
     "D",
@@ -60,6 +58,16 @@ UnitChoices: TypeAlias = Literal[
     "nanosecond",
     "n",
 ]
+
+UnitChoices: TypeAlias = Union[
+    TimeDeltaUnitChoices,
+    Literal[
+        "Y",
+        "y",
+        "M",
+    ],
+]
+
 _S = TypeVar("_S", bound=timedelta)
 
 def ints_to_pytimedelta(

pandas-stubs/core/indexes/datetimes.pyi

@@ -2,7 +2,11 @@ from datetime import (
     timedelta,
     tzinfo,
 )
-from typing import overload
+from typing import (
+    Hashable,
+    Literal,
+    overload,
+)
 
 import numpy as np
 from pandas import (
@@ -23,7 +27,6 @@ from pandas._typing import (
     AnyArrayLike,
     ArrayLike,
     DatetimeLike,
-    IntervalClosedType,
 )
 
 from pandas.core.dtypes.dtypes import DatetimeTZDtype
@@ -87,23 +90,24 @@ def date_range(
     start: str | DatetimeLike | None = ...,
     end: str | DatetimeLike | None = ...,
     periods: int | None = ...,
+    # TODO: Test timedelta and Timedelta, update pandas docs
     freq: str | timedelta | Timedelta | BaseOffset = ...,
     tz: str | tzinfo = ...,
     normalize: bool = ...,
-    name: str | None = ...,
-    inclusive: IntervalClosedType = ...,
-    **kwargs,
+    name: Hashable | None = ...,
+    inclusive: Literal["left", "right"] | None = ...,
 ) -> DatetimeIndex: ...
 def bdate_range(
     start: str | DatetimeLike | None = ...,
     end: str | DatetimeLike | None = ...,
     periods: int | None = ...,
+    # TODO: Test timedelta and Timedelta, update pandas docs
     freq: str | timedelta | Timedelta | BaseOffset = ...,
     tz: str | tzinfo = ...,
     normalize: bool = ...,
-    name: str | None = ...,
+    name: Hashable | None = ...,
     weekmask: str | None = ...,
-    holidays: list | None = ...,
-    inclusive: IntervalClosedType = ...,
-    **kwargs,
+    # TODO: Check if dt.date is allowed
+    holidays: list[str | DatetimeLike] | None = ...,
+    inclusive: Literal["left", "right"] | None = ...,
 ) -> DatetimeIndex: ...

pandas-stubs/core/indexes/period.pyi

@@ -1,4 +1,7 @@
+from typing import Hashable
+
 import numpy as np
+import pandas as pd
 from pandas.core.indexes.datetimelike import (
     DatetimeIndexOpsMixin as DatetimeIndexOpsMixin,
 )
@@ -46,5 +49,9 @@ class PeriodIndex(DatetimeIndexOpsMixin, Int64Index):
     def memory_usage(self, deep: bool = ...): ...
 
 def period_range(
-    start=..., end=..., periods=..., freq=..., name=...
+    start: str | pd.Period | None = ...,
+    end: str | pd.Period | None = ...,
+    periods: int | None = ...,
+    freq: str | pd.DateOffset | None = ...,
+    name: Hashable | None = ...,
 ) -> PeriodIndex: ...

pandas-stubs/core/indexes/timedeltas.pyi

@@ -1,5 +1,10 @@
-from typing import overload
+from typing import (
+    Hashable,
+    Literal,
+    overload,
+)
 
+from pandas import DateOffset
 from pandas.core.indexes.accessors import TimedeltaIndexProperties
 from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
 from pandas.core.indexes.datetimes import DatetimeIndex
@@ -9,7 +14,10 @@ from pandas._libs import (
     Timedelta,
     Timestamp,
 )
-from pandas._typing import num
+from pandas._typing import (
+    TimedeltaConvertibleTypes,
+    num,
+)
 
 class TimedeltaIndex(DatetimeTimedeltaMixin, TimedeltaIndexProperties):
     def __new__(
@@ -42,5 +50,10 @@ class TimedeltaIndex(DatetimeTimedeltaMixin, TimedeltaIndexProperties):
     def to_series(self, index=..., name=...) -> TimedeltaSeries: ...
 
 def timedelta_range(
-    start=..., end=..., periods=..., freq=..., name=..., closed=...
+    start: TimedeltaConvertibleTypes = ...,
+    end: TimedeltaConvertibleTypes = ...,
+    periods: int | None = ...,
+    freq: str | DateOffset | None = ...,
+    name: Hashable | None = ...,
+    closed: Literal["left", "right"] | None = ...,
 ) -> TimedeltaIndex: ...

pandas-stubs/core/tools/datetimes.pyi

@@ -1,12 +1,14 @@
 from datetime import datetime
 from typing import (
     Literal,
+    Sequence,
     TypedDict,
     Union,
     overload,
 )
 
 import numpy as np
+import pandas as pd
 from pandas import (
     Index,
     Timestamp,
@@ -25,6 +27,7 @@ from pandas._typing import (
     AnyArrayLike,
     DateTimeErrorChoices,
     IgnoreRaise,
+    npt,
 )
 
 ArrayConvertible: TypeAlias = Union[list, tuple, AnyArrayLike]
@@ -53,9 +56,6 @@ class FulldatetimeDict(YearMonthDayDict, total=False):
 
 DictConvertible: TypeAlias = Union[FulldatetimeDict, DataFrame]
 
-def should_cache(
-    arg: ArrayConvertible, unique_share: float = ..., check_count: int | None = ...
-) -> bool: ...
 @overload
 def to_datetime(
     arg: DatetimeScalar,
@@ -67,7 +67,7 @@ def to_datetime(
     exact: bool = ...,
     unit: str | None = ...,
     infer_datetime_format: bool = ...,
-    origin=...,
+    origin: int | Literal["julian", "unix"] | pd.Timestamp = ...,
     cache: bool = ...,
 ) -> Timestamp: ...
 @overload
@@ -81,11 +81,12 @@ def to_datetime(
     exact: bool = ...,
     unit: str | None = ...,
     infer_datetime_format: bool = ...,
-    origin=...,
+    origin: Literal["julian", "unix"] | pd.Timestamp = ...,
     cache: bool = ...,
 ) -> Timestamp | NaTType: ...
 @overload
 def to_datetime(
+    # TODO: Test dataframe return type
     arg: Series | DictConvertible,
     errors: DateTimeErrorChoices = ...,
     dayfirst: bool = ...,
@@ -95,12 +96,21 @@ def to_datetime(
     exact: bool = ...,
     unit: str | None = ...,
     infer_datetime_format: bool = ...,
-    origin=...,
+    origin: int | Literal["julian", "unix"] | pd.Timestamp = ...,
     cache: bool = ...,
 ) -> TimestampSeries: ...
 @overload
 def to_datetime(
-    arg: list | tuple | np.ndarray | Index | ExtensionArray,
+    # TODO: Test other types
+    arg: Sequence[int | float | datetime]
+    | list[str]
+    | tuple[int | float | str | datetime, ...]
+    | npt.NDArray[np.datetime64]
+    | npt.NDArray[np.str_]
+    | npt.NDArray[np.int_]
+    | npt.NDArray[np.float_]
+    | Index
+    | ExtensionArray,
     errors: DateTimeErrorChoices = ...,
     dayfirst: bool = ...,
     yearfirst: bool = ...,
@@ -109,7 +119,7 @@ def to_datetime(
     exact: bool = ...,
     unit: str | None = ...,
     infer_datetime_format: bool = ...,
-    origin=...,
+    # TODO: Origin needs int in pandas docs
+    origin: int | Literal["julian", "unix"] | pd.Timestamp = ...,
     cache: bool = ...,
 ) -> DatetimeIndex: ...
-def to_time(arg, format=..., infer_time_format: bool = ..., errors: str = ...): ...

pandas-stubs/core/tools/timedeltas.pyi

@@ -1,7 +1,10 @@
-# def to_timedelta(arg, unit: str = ..., errors: str = ...): ...
 from datetime import timedelta
-from typing import overload
+from typing import (
+    Sequence,
+    overload,
+)
 
+import pandas as pd
 from pandas import Index
 from pandas.core.indexes.timedeltas import TimedeltaIndex
 from pandas.core.series import (
@@ -10,29 +13,32 @@ from pandas.core.series import (
 )
 
 from pandas._libs.tslibs import Timedelta
-from pandas._libs.tslibs.timedeltas import UnitChoices
+from pandas._libs.tslibs.timedeltas import TimeDeltaUnitChoices
 from pandas._typing import (
     ArrayLike,
     DateTimeErrorChoices,
 )
 
-# Copied from pandas/_libs/tslibs/timedeltas.pyx
-
 @overload
 def to_timedelta(
     arg: str | float | timedelta,
-    unit: UnitChoices | None = ...,
+    unit: TimeDeltaUnitChoices | None = ...,
     errors: DateTimeErrorChoices = ...,
 ) -> Timedelta: ...
 @overload
 def to_timedelta(
     arg: Series,
-    unit: UnitChoices | None = ...,
+    unit: TimeDeltaUnitChoices | None = ...,
     errors: DateTimeErrorChoices = ...,
 ) -> TimedeltaSeries: ...
 @overload
 def to_timedelta(
-    arg: list | tuple | range | ArrayLike | Index,
-    unit: UnitChoices | None = ...,
+    arg: Sequence[float | timedelta]
+    | list[str | float | timedelta]
+    | tuple[str | float | timedelta, ...]
+    | range
+    | ArrayLike
+    | Index,
+    unit: TimeDeltaUnitChoices | None = ...,
     errors: DateTimeErrorChoices = ...,
 ) -> TimedeltaIndex: ...

pandas-stubs/tseries/frequencies.pyi

@@ -1,6 +1,12 @@
+from pandas import (
+    DatetimeIndex,
+    Series,
+    TimedeltaIndex,
+)
+
 from pandas.tseries.offsets import DateOffset as DateOffset
 
 def get_period_alias(offset_str: str) -> str | None: ...
 def to_offset(freq) -> DateOffset | None: ...
 def get_offset(name: str) -> DateOffset: ...
-def infer_freq(index) -> str | None: ...
+def infer_freq(index: Series | DatetimeIndex | TimedeltaIndex) -> str | None: ...