TYP: timestamps.pyi (#44339)

Author: twoertwein

pandas/_libs/tslibs/timestamps.pyi

@@ -8,7 +8,6 @@ from datetime import (
 from time import struct_time
 from typing import (
     ClassVar,
-    Type,
     TypeVar,
     overload,
 )
@@ -22,9 +21,9 @@ from pandas._libs.tslibs import (
     Timedelta,
 )
 
-_S = TypeVar("_S")
+_S = TypeVar("_S", bound=datetime)
 
-def integer_op_not_supported(obj) -> TypeError: ...
+def integer_op_not_supported(obj: object) -> TypeError: ...
 
 class Timestamp(datetime):
     min: ClassVar[Timestamp]
@@ -35,17 +34,17 @@ class Timestamp(datetime):
 
     # error: "__new__" must return a class instance (got "Union[Timestamp, NaTType]")
     def __new__(  # type: ignore[misc]
-        cls: Type[_S],
+        cls: type[_S],
         ts_input: int
         | np.integer
         | float
         | str
         | _date
         | datetime
         | np.datetime64 = ...,
-        freq=...,
+        freq: int | None | str | BaseOffset = ...,
         tz: str | _tzinfo | None | int = ...,
-        unit=...,
+        unit: str | int | None = ...,
         year: int | None = ...,
         month: int | None = ...,
         day: int | None = ...,
@@ -80,24 +79,28 @@ class Timestamp(datetime):
     @property
     def fold(self) -> int: ...
     @classmethod
-    def fromtimestamp(cls: Type[_S], t: float, tz: _tzinfo | None = ...) -> _S: ...
+    def fromtimestamp(cls: type[_S], t: float, tz: _tzinfo | None = ...) -> _S: ...
     @classmethod
-    def utcfromtimestamp(cls: Type[_S], t: float) -> _S: ...
+    def utcfromtimestamp(cls: type[_S], t: float) -> _S: ...
     @classmethod
-    def today(cls: Type[_S]) -> _S: ...
+    def today(cls: type[_S], tz: _tzinfo | str | None = ...) -> _S: ...
     @classmethod
-    def fromordinal(cls: Type[_S], n: int) -> _S: ...
+    def fromordinal(
+        cls: type[_S],
+        ordinal: int,
+        freq: str | BaseOffset | None = ...,
+        tz: _tzinfo | str | None = ...,
+    ) -> _S: ...
     @classmethod
-    def now(cls: Type[_S], tz: _tzinfo | str | None = ...) -> _S: ...
+    def now(cls: type[_S], tz: _tzinfo | str | None = ...) -> _S: ...
     @classmethod
-    def utcnow(cls: Type[_S]) -> _S: ...
+    def utcnow(cls: type[_S]) -> _S: ...
+    # error: Signature of "combine" incompatible with supertype "datetime"
     @classmethod
-    def combine(
-        cls, date: _date, time: _time, tzinfo: _tzinfo | None = ...
-    ) -> datetime: ...
+    def combine(cls, date: _date, time: _time) -> datetime: ...  # type: ignore[override]
     @classmethod
-    def fromisoformat(cls: Type[_S], date_string: str) -> _S: ...
-    def strftime(self, fmt: str) -> str: ...
+    def fromisoformat(cls: type[_S], date_string: str) -> _S: ...
+    def strftime(self, format: str) -> str: ...
     def __format__(self, fmt: str) -> str: ...
     def toordinal(self) -> int: ...
     def timetuple(self) -> struct_time: ...
@@ -116,12 +119,12 @@ class Timestamp(datetime):
         second: int = ...,
         microsecond: int = ...,
         tzinfo: _tzinfo | None = ...,
-        *,
         fold: int = ...,
     ) -> datetime: ...
     def astimezone(self: _S, tz: _tzinfo | None = ...) -> _S: ...
     def ctime(self) -> str: ...
-    def isoformat(self, sep: str = ..., timespec: str = ...) -> str: ...
+    # error: Signature of "isoformat" incompatible with supertype "datetime"
+    def isoformat(self, sep: str = ...) -> str: ...  # type: ignore[override]
     @classmethod
     def strptime(cls, date_string: str, format: str) -> datetime: ...
     def utcoffset(self) -> timedelta | None: ...
@@ -131,12 +134,18 @@ class Timestamp(datetime):
     def __lt__(self, other: datetime) -> bool: ...  # type: ignore
     def __ge__(self, other: datetime) -> bool: ...  # type: ignore
     def __gt__(self, other: datetime) -> bool: ...  # type: ignore
-    def __add__(self: _S, other: timedelta) -> _S: ...
+    # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
+    @overload  # type: ignore[override]
+    def __add__(self, other: np.ndarray) -> np.ndarray: ...
+    @overload
+    # TODO: other can also be Tick (but it cannot be resolved)
+    def __add__(self: _S, other: timedelta | np.timedelta64) -> _S: ...
     def __radd__(self: _S, other: timedelta) -> _S: ...
     @overload  # type: ignore
     def __sub__(self, other: datetime) -> timedelta: ...
     @overload
-    def __sub__(self, other: timedelta) -> datetime: ...
+    # TODO: other can also be Tick (but it cannot be resolved)
+    def __sub__(self, other: timedelta | np.timedelta64) -> datetime: ...
     def __hash__(self) -> int: ...
     def weekday(self) -> int: ...
     def isoweekday(self) -> int: ...
@@ -157,23 +166,38 @@ class Timestamp(datetime):
     def is_year_end(self) -> bool: ...
     def to_pydatetime(self, warn: bool = ...) -> datetime: ...
     def to_datetime64(self) -> np.datetime64: ...
-    def to_period(self, freq) -> Period: ...
+    def to_period(self, freq: BaseOffset | str | None = ...) -> Period: ...
     def to_julian_date(self) -> np.float64: ...
     @property
     def asm8(self) -> np.datetime64: ...
-    def tz_convert(self: _S, tz) -> _S: ...
+    def tz_convert(self: _S, tz: _tzinfo | str | None) -> _S: ...
     # TODO: could return NaT?
     def tz_localize(
-        self: _S, tz, ambiguous: str = ..., nonexistent: str = ...
+        self: _S, tz: _tzinfo | str | None, ambiguous: str = ..., nonexistent: str = ...
     ) -> _S: ...
     def normalize(self: _S) -> _S: ...
     # TODO: round/floor/ceil could return NaT?
     def round(
-        self: _S, freq, ambiguous: bool | str = ..., nonexistent: str = ...
+        self: _S, freq: str, ambiguous: bool | str = ..., nonexistent: str = ...
     ) -> _S: ...
     def floor(
-        self: _S, freq, ambiguous: bool | str = ..., nonexistent: str = ...
+        self: _S, freq: str, ambiguous: bool | str = ..., nonexistent: str = ...
     ) -> _S: ...
     def ceil(
-        self: _S, freq, ambiguous: bool | str = ..., nonexistent: str = ...
+        self: _S, freq: str, ambiguous: bool | str = ..., nonexistent: str = ...
     ) -> _S: ...
+    def day_name(self, locale: str | None = ...) -> str: ...
+    def month_name(self, locale: str | None = ...) -> str: ...
+    @property
+    def day_of_week(self) -> int: ...
+    @property
+    def day_of_month(self) -> int: ...
+    @property
+    def day_of_year(self) -> int: ...
+    @property
+    def quarter(self) -> int: ...
+    @property
+    def week(self) -> int: ...
+    def to_numpy(
+        self, dtype: np.dtype | None = ..., copy: bool = ...
+    ) -> np.datetime64: ...