GH1432 Partial resolution

Author: loicdiridollou

pandas-stubs/_libs/tslibs/timestamps.pyi

@@ -32,6 +32,7 @@ from pandas._libs.tslibs import (
     Tick,
     Timedelta,
 )
+from pandas._libs.tslibs.nattype import NaTType
 from pandas._typing import (
     PeriodFrequency,
     ShapeT,
@@ -228,7 +229,7 @@ class Timestamp(datetime, SupportsIndex):
     def __radd__(
         self, other: np_ndarray[ShapeT, np.timedelta64]
     ) -> np_ndarray[ShapeT, np.datetime64]: ...
-    # TODO: pandas-dev/pandas-stubs#1432 test dt64
+    def __rsub__(self, other: datetime | np.datetime64) -> Timedelta: ...
     @overload  # type: ignore[override]
     def __sub__(self, other: datetime | np.datetime64) -> Timedelta: ...
     @overload
@@ -284,7 +285,15 @@ class Timestamp(datetime, SupportsIndex):
     @property
     def asm8(self) -> np.datetime64: ...
     def tz_convert(self, tz: TimeZones) -> Self: ...
-    # TODO: pandas-dev/pandas-stubs#1432 could return NaT?
+    @overload
+    def tz_localize(  # type: ignore[overload-overlap] # pyright: ignore[reportOverlappingOverload]
+        self,
+        tz: TimeZones,
+        ambiguous: _Ambiguous = "raise",
+        *,
+        nonexistent: Literal["NaT"],
+    ) -> Self | NaTType: ...
+    @overload
     def tz_localize(
         self,
         tz: TimeZones,

pandas-stubs/io/orc.pyi

@@ -1,6 +1,8 @@
 from typing import Any
 
+from fsspec.spec import AbstractFileSystem  # pyright: ignore[reportMissingTypeStubs]
 from pandas import DataFrame
+from pyarrow.fs import FileSystem
 
 from pandas._libs.lib import _NoDefaultDoNotUse
 from pandas._typing import (
@@ -14,8 +16,6 @@ def read_orc(
     path: FilePath | ReadBuffer[bytes],
     columns: list[HashableT] | None = None,
     dtype_backend: DtypeBackend | _NoDefaultDoNotUse = "numpy_nullable",
-    # TODO: pandas-dev/pandas-stubs#1432 type with the correct pyarrow types
-    # filesystem: pyarrow.fs.FileSystem | fsspec.spec.AbstractFileSystem
-    filesystem: Any | None = None,
+    filesystem: FileSystem | AbstractFileSystem | None = None,
     **kwargs: Any,
 ) -> DataFrame: ...

pyproject.toml

@@ -70,6 +70,7 @@ beautifulsoup4 = ">=4.14.2"
 html5lib = ">=1.1"
 python-calamine = ">=0.2.0"
 pyarrow-stubs = { version = ">=20.0.0.20250928", python = "<4" }
+fsspec = "^2025.10.0"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

tests/scalars/test_scalars.py

@@ -1385,9 +1385,20 @@ def test_timestamp_misc_methods() -> None:
         pd.Timestamp,
     )
     check(
-        assert_type(ts.tz_localize("US/Pacific", nonexistent="NaT"), pd.Timestamp),
+        assert_type(
+            ts.tz_localize("US/Pacific", nonexistent="NaT"), pd.Timestamp | NaTType
+        ),
         pd.Timestamp,
     )
+    check(
+        assert_type(
+            pd.Timestamp(2025, 3, 9, 2, 30, 0).tz_localize(
+                "US/Eastern", nonexistent="NaT"
+            ),
+            pd.Timestamp | NaTType,
+        ),
+        NaTType,
+    )
     check(
         assert_type(ts.tz_localize("US/Pacific", nonexistent="raise"), pd.Timestamp),
         pd.Timestamp,

tests/test_timefuncs.py

@@ -95,9 +95,13 @@ def test_types_init() -> None:
 def test_types_arithmetic() -> None:
     ts = pd.to_datetime("2021-03-01")
     ts2 = pd.to_datetime("2021-01-01")
+    ts_np = np.datetime64("2021-01-01")
     delta = pd.to_timedelta("1 day")
 
     check(assert_type(ts - ts2, pd.Timedelta), pd.Timedelta)
+    check(assert_type(ts - ts_np, pd.Timedelta), pd.Timedelta)
+    # TODO: pandas-dev/pandas-stubs#1432 mypy sees datetime.timedelta but pyright is correct
+    # check(assert_type(ts_np - ts, pd.Timedelta), pd.Timedelta)
     check(assert_type(ts + delta, pd.Timestamp), pd.Timestamp)
     check(assert_type(ts - delta, pd.Timestamp), pd.Timestamp)
     check(assert_type(ts - dt.datetime(2021, 1, 3), pd.Timedelta), pd.Timedelta)