align typing with pandas source (#1219)

* align typing with pandas source

* respond to PR comments

Author: Dr-Irv

pandas-stubs/_libs/tslibs/nattype.pyi

@@ -4,6 +4,7 @@ from datetime import (
     timedelta,
     tzinfo as _tzinfo,
 )
+from typing import Literal
 
 import numpy as np
 from typing_extensions import (
@@ -13,7 +14,9 @@ from typing_extensions import (
 
 from pandas._libs.tslibs.period import Period
 from pandas._typing import (
+    Frequency,
     NpDtype,
+    TimestampNonexistent,
     TimeUnit,
 )
 
@@ -75,11 +78,31 @@ class NaTType:
     def now(self, tz: _tzinfo | str | None = ...) -> NaTType: ...
     def to_pydatetime(self) -> NaTType: ...
     def date(self) -> NaTType: ...
-    def round(self) -> NaTType: ...
-    def floor(self) -> NaTType: ...
-    def ceil(self) -> NaTType: ...
+    def round(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
+    def floor(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
+    def ceil(
+        self,
+        freq: Frequency,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
     def tz_convert(self) -> NaTType: ...
-    def tz_localize(self) -> NaTType: ...
+    def tz_localize(
+        self,
+        tz: _tzinfo | str | None,
+        ambiguous: bool | Literal["raise"] | NaTType = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> NaTType: ...
     def replace(
         self,
         year: int | None = ...,

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -40,15 +40,14 @@ from pandas._libs.tslibs import (
     Timedelta,
 )
 from pandas._typing import (
+    TimestampNonexistent,
     TimeUnit,
     np_ndarray_bool,
     npt,
 )
 
 _Ambiguous: TypeAlias = bool | Literal["raise", "NaT"]
-_Nonexistent: TypeAlias = (
-    Literal["raise", "NaT", "shift_backward", "shift_forward"] | Timedelta | timedelta
-)
+
 # Repeated from `_typing.pyi` so as to satisfy mixed strict / non-strict paths.
 # https://github.com/pandas-dev/pandas-stubs/pull/1151#issuecomment-2715130190
 TimeZones: TypeAlias = str | _tzinfo | None | int
@@ -278,27 +277,27 @@ class Timestamp(datetime, SupportsIndex):
         self,
         tz: TimeZones,
         ambiguous: _Ambiguous = ...,
-        nonexistent: _Nonexistent = ...,
+        nonexistent: TimestampNonexistent = ...,
     ) -> Self: ...
     def normalize(self) -> Self: ...
     # TODO: round/floor/ceil could return NaT?
     def round(
         self,
         freq: str,
         ambiguous: _Ambiguous = ...,
-        nonexistent: _Nonexistent = ...,
+        nonexistent: TimestampNonexistent = ...,
     ) -> Self: ...
     def floor(
         self,
         freq: str,
         ambiguous: _Ambiguous = ...,
-        nonexistent: _Nonexistent = ...,
+        nonexistent: TimestampNonexistent = ...,
     ) -> Self: ...
     def ceil(
         self,
         freq: str,
         ambiguous: _Ambiguous = ...,
-        nonexistent: _Nonexistent = ...,
+        nonexistent: TimestampNonexistent = ...,
     ) -> Self: ...
     def day_name(self, locale: str | None = ...) -> str: ...
     def month_name(self, locale: str | None = ...) -> str: ...