follow implementation more closely in zoneinfo (#11189)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

pyproject.toml

@@ -158,6 +158,7 @@ extra-standard-library = [
     "genericpath",
     "opcode",
     "pyexpat",
+    "zoneinfo",
 ]
 known-first-party = ["_metadata", "_utils"]
 

stdlib/zoneinfo/__init__.pyi

@@ -1,38 +1,35 @@
-from _typeshed import StrPath
-from collections.abc import Iterable, Sequence
+import sys
+from collections.abc import Iterable
 from datetime import datetime, timedelta, tzinfo
-from typing import Any, Protocol
 from typing_extensions import Self
 
-__all__ = ["ZoneInfo", "reset_tzpath", "available_timezones", "TZPATH", "ZoneInfoNotFoundError", "InvalidTZPathWarning"]
+# TODO: remove this version check
+# In theory we shouldn't need this version check. Pyright complains about the imports
+# from zoneinfo.* when run on 3.8 and 3.7 without this. Updates to typeshed's
+# pyright test script are probably needed, see #11189
+if sys.version_info >= (3, 9):
+    from zoneinfo._common import ZoneInfoNotFoundError as ZoneInfoNotFoundError, _IOBytes
+    from zoneinfo._tzpath import (
+        TZPATH as TZPATH,
+        InvalidTZPathWarning as InvalidTZPathWarning,
+        available_timezones as available_timezones,
+        reset_tzpath as reset_tzpath,
+    )
 
-class _IOBytes(Protocol):
-    def read(self, size: int, /) -> bytes: ...
-    def seek(self, size: int, whence: int = ..., /) -> Any: ...
+    __all__ = ["ZoneInfo", "reset_tzpath", "available_timezones", "TZPATH", "ZoneInfoNotFoundError", "InvalidTZPathWarning"]
 
-class ZoneInfo(tzinfo):
-    @property
-    def key(self) -> str: ...
-    def __init__(self, key: str) -> None: ...
-    @classmethod
-    def no_cache(cls, key: str) -> Self: ...
-    @classmethod
-    def from_file(cls, fobj: _IOBytes, /, key: str | None = None) -> Self: ...
-    @classmethod
-    def clear_cache(cls, *, only_keys: Iterable[str] | None = None) -> None: ...
-    def tzname(self, dt: datetime | None, /) -> str | None: ...
-    def utcoffset(self, dt: datetime | None, /) -> timedelta | None: ...
-    def dst(self, dt: datetime | None, /) -> timedelta | None: ...
+    class ZoneInfo(tzinfo):
+        @property
+        def key(self) -> str: ...
+        def __init__(self, key: str) -> None: ...
+        @classmethod
+        def no_cache(cls, key: str) -> Self: ...
+        @classmethod
+        def from_file(cls, fobj: _IOBytes, /, key: str | None = None) -> Self: ...
+        @classmethod
+        def clear_cache(cls, *, only_keys: Iterable[str] | None = None) -> None: ...
+        def tzname(self, dt: datetime | None, /) -> str | None: ...
+        def utcoffset(self, dt: datetime | None, /) -> timedelta | None: ...
+        def dst(self, dt: datetime | None, /) -> timedelta | None: ...
 
-# Note: Both here and in clear_cache, the types allow the use of `str` where
-# a sequence of strings is required. This should be remedied if a solution
-# to this typing bug is found: https://github.com/python/typing/issues/256
-def reset_tzpath(to: Sequence[StrPath] | None = None) -> None: ...
-def available_timezones() -> set[str]: ...
-
-TZPATH: tuple[str, ...]
-
-class ZoneInfoNotFoundError(KeyError): ...
-class InvalidTZPathWarning(RuntimeWarning): ...
-
-def __dir__() -> list[str]: ...
+    def __dir__() -> list[str]: ...

stdlib/zoneinfo/_common.pyi

@@ -0,0 +1,13 @@
+import io
+from typing import Any, Protocol
+
+class _IOBytes(Protocol):
+    def read(self, size: int, /) -> bytes: ...
+    def seek(self, size: int, whence: int = ..., /) -> Any: ...
+
+def load_tzdata(key: str) -> io.BufferedReader: ...
+def load_data(
+    fobj: _IOBytes,
+) -> tuple[tuple[int, ...], tuple[int, ...], tuple[int, ...], tuple[int, ...], tuple[str, ...], bytes | None]: ...
+
+class ZoneInfoNotFoundError(KeyError): ...

stdlib/zoneinfo/_tzpath.pyi

@@ -0,0 +1,13 @@
+from _typeshed import StrPath
+from collections.abc import Sequence
+
+# Note: Both here and in clear_cache, the types allow the use of `str` where
+# a sequence of strings is required. This should be remedied if a solution
+# to this typing bug is found: https://github.com/python/typing/issues/256
+def reset_tzpath(to: Sequence[StrPath] | None = None) -> None: ...
+def find_tzfile(key: str) -> str | None: ...
+def available_timezones() -> set[str]: ...
+
+TZPATH: tuple[str, ...]
+
+class InvalidTZPathWarning(RuntimeWarning): ...