revert Timestamp and Timedelta constructors typing allowing NaTType r…

…eturn (pandas-dev#48112)

* revert Timestamp and Timedelta constructors typing allowing NaTType return

* exclude 2 files from pyright.  Fix up tz methods for NaTType

* add tz and tzinfo methods

* remove check that tz doesn't exist for NaT

pandas/_libs/tslibs/nattype.pyi

@@ -67,8 +67,17 @@ class NaTType:
     def round(self) -> NaTType: ...
     def floor(self) -> NaTType: ...
     def ceil(self) -> NaTType: ...
-    def tz_convert(self) -> NaTType: ...
-    def tz_localize(self) -> NaTType: ...
+    @property
+    def tzinfo(self) -> None: ...
+    @property
+    def tz(self) -> None: ...
+    def tz_convert(self, tz: _tzinfo | str | None) -> NaTType: ...
+    def tz_localize(
+        self,
+        tz: _tzinfo | str | None,
+        ambiguous: str = ...,
+        nonexistent: str = ...,
+    ) -> NaTType: ...
     def replace(
         self,
         year: int | None = ...,

pandas/_libs/tslibs/nattype.pyx

@@ -1203,6 +1203,13 @@ default 'raise'
         NaT
         """,
     )
+    @property
+    def tz(self) -> None:
+        return None
+
+    @property
+    def tzinfo(self) -> None:
+        return None
 
 
 c_NaT = NaTType()  # C-visible

pandas/_libs/tslibs/timedeltas.pyi

@@ -82,15 +82,13 @@ class Timedelta(timedelta):
     max: ClassVar[Timedelta]
     resolution: ClassVar[Timedelta]
     value: int  # np.int64
-    def __new__(
+    # error: "__new__" must return a class instance (got "Union[Timestamp, NaTType]")
+    def __new__(  # type: ignore[misc]
         cls: type[_S],
         value=...,
         unit: str | None = ...,
         **kwargs: float | np.integer | np.floating,
-    ) -> _S: ...
-    # GH 46171
-    # While Timedelta can return pd.NaT, having the constructor return
-    # a Union with NaTType makes things awkward for users of pandas
+    ) -> _S | NaTType: ...
     @classmethod
     def _from_value_and_reso(cls, value: np.int64, reso: int) -> Timedelta: ...
     @property

pandas/_libs/tslibs/timestamps.pyi

@@ -16,6 +16,7 @@ import numpy as np
 
 from pandas._libs.tslibs import (
     BaseOffset,
+    NaTType,
     Period,
     Tick,
     Timedelta,
@@ -31,7 +32,8 @@ class Timestamp(datetime):
 
     resolution: ClassVar[Timedelta]
     value: int  # np.int64
-    def __new__(
+    # error: "__new__" must return a class instance (got "Union[Timestamp, NaTType]")
+    def __new__(  # type: ignore[misc]
         cls: type[_DatetimeT],
         ts_input: np.integer | float | str | _date | datetime | np.datetime64 = ...,
         freq: int | None | str | BaseOffset = ...,
@@ -48,10 +50,7 @@ class Timestamp(datetime):
         tzinfo: _tzinfo | None = ...,
         *,
         fold: int | None = ...,
-    ) -> _DatetimeT: ...
-    # GH 46171
-    # While Timestamp can return pd.NaT, having the constructor return
-    # a Union with NaTType makes things awkward for users of pandas
+    ) -> _DatetimeT | NaTType: ...
     def _set_freq(self, freq: BaseOffset | None) -> None: ...
     @classmethod
     def _from_value_and_reso(

pandas/tests/scalar/test_nat.py

@@ -190,7 +190,7 @@ def test_nat_iso_format(get_nat):
 @pytest.mark.parametrize(
     "klass,expected",
     [
-        (Timestamp, ["freqstr", "normalize", "to_julian_date", "to_period", "tz"]),
+        (Timestamp, ["freqstr", "normalize", "to_julian_date", "to_period"]),
         (
             Timedelta,
             [

pyright_reportGeneralTypeIssues.json

@@ -16,6 +16,7 @@
         "pandas/util/version",
         # and all files that currently don't pass
         "pandas/_testing/__init__.py",
+        "pandas/_testing/_hypothesis.py",
         "pandas/core/algorithms.py",
         "pandas/core/apply.py",
         "pandas/core/array_algos/take.py",
@@ -57,6 +58,7 @@
         "pandas/core/indexes/multi.py",
         "pandas/core/indexes/numeric.py",
         "pandas/core/indexes/period.py",
+        "pandas/core/indexes/timedeltas.py",
         "pandas/core/indexing.py",
         "pandas/core/internals/api.py",
         "pandas/core/internals/array_manager.py",