Add stubs for importlib.(resources.)readers (#10928)

Co-authored-by: Sebastian Rittau <srittau@rittau.biz>

pyrightconfig.stricter.json

@@ -10,6 +10,7 @@
         "stubs/**/@tests/test_cases",
         "stdlib/distutils/command",
         "stdlib/distutils/dist.pyi",
+        "stdlib/importlib/readers.pyi",
         "stdlib/lib2to3/fixes/*.pyi",
         "stdlib/_tkinter.pyi",
         "stdlib/tkinter/__init__.pyi",

stdlib/VERSIONS

@@ -152,8 +152,10 @@ imp: 2.7-3.11
 importlib: 2.7-
 importlib.metadata: 3.8-
 importlib.metadata._meta: 3.10-
+importlib.readers: 3.10-
 importlib.resources: 3.7-
 importlib.resources.abc: 3.11-
+importlib.resources.readers: 3.11-
 inspect: 2.7-
 io: 2.7-
 ipaddress: 3.3-

stdlib/importlib/abc.pyi

@@ -14,7 +14,7 @@ from abc import ABCMeta, abstractmethod
 from collections.abc import Iterator, Mapping, Sequence
 from importlib.machinery import ModuleSpec
 from io import BufferedRandom, BufferedReader, BufferedWriter, FileIO, TextIOWrapper
-from typing import IO, Any, BinaryIO, NoReturn, Protocol, overload, runtime_checkable
+from typing import IO, Any, BinaryIO, Protocol, overload, runtime_checkable
 from typing_extensions import Literal
 
 if sys.version_info >= (3, 11):
@@ -203,8 +203,12 @@ if sys.version_info >= (3, 9):
         @property
         @abstractmethod
         def name(self) -> str: ...
-        @abstractmethod
-        def __truediv__(self, child: str) -> Traversable: ...
+        if sys.version_info >= (3, 10):
+            def __truediv__(self, child: str) -> Traversable: ...
+        else:
+            @abstractmethod
+            def __truediv__(self, child: str) -> Traversable: ...
+
         @abstractmethod
         def read_bytes(self) -> bytes: ...
         @abstractmethod
@@ -214,6 +218,6 @@ if sys.version_info >= (3, 9):
         @abstractmethod
         def files(self) -> Traversable: ...
         def open_resource(self, resource: str) -> BufferedReader: ...
-        def resource_path(self, resource: Any) -> NoReturn: ...
+        def resource_path(self, resource: Any) -> str: ...
         def is_resource(self, path: str) -> bool: ...
         def contents(self) -> Iterator[str]: ...

stdlib/importlib/readers.pyi

@@ -0,0 +1,61 @@
+# On py311+, things are actually defined in importlib.resources.readers,
+# and re-exported here,
+# but doing it this way leads to less code duplication for us
+
+import pathlib
+import sys
+from _typeshed import Incomplete, StrPath
+from collections.abc import Iterable, Iterator
+from io import BufferedReader
+from typing import NoReturn, TypeVar
+from typing_extensions import Literal, Never
+
+if sys.version_info >= (3, 11):
+    import importlib.resources.abc as abc
+else:
+    import importlib.abc as abc
+
+if sys.version_info >= (3, 10):
+    if sys.version_info >= (3, 11):
+        __all__ = ["FileReader", "ZipReader", "MultiplexedPath", "NamespaceReader"]
+
+    if sys.version_info < (3, 11):
+        _T = TypeVar("_T")
+
+        def remove_duplicates(items: Iterable[_T]) -> Iterator[_T]: ...
+
+    class FileReader(abc.TraversableResources):
+        path: pathlib.Path
+        def __init__(self, loader) -> None: ...
+        def resource_path(self, resource: StrPath) -> str: ...
+        def files(self) -> pathlib.Path: ...
+
+    class ZipReader(abc.TraversableResources):
+        prefix: str
+        archive: Incomplete
+        def __init__(self, loader, module: str) -> None: ...
+        def open_resource(self, resource: str) -> BufferedReader: ...
+        def is_resource(self, path: StrPath) -> bool: ...
+        def files(self): ...
+
+    class MultiplexedPath(abc.Traversable):
+        def __init__(self, *paths: abc.Traversable) -> None: ...
+        def iterdir(self) -> Iterator[abc.Traversable]: ...
+        def read_bytes(self) -> NoReturn: ...
+        def read_text(self, *args: Never, **kwargs: Never) -> NoReturn: ...  # type: ignore[override]
+        def is_dir(self) -> Literal[True]: ...
+        def is_file(self) -> Literal[False]: ...
+        if sys.version_info >= (3, 12):
+            def joinpath(self, *descendants: str) -> abc.Traversable: ...
+        else:
+            def joinpath(self, child: str) -> abc.Traversable: ...  # type: ignore[override]
+            __truediv__ = joinpath
+        def open(self, *args: Never, **kwargs: Never) -> NoReturn: ...  # type: ignore[override]
+        @property
+        def name(self) -> str: ...
+
+    class NamespaceReader(abc.TraversableResources):
+        path: MultiplexedPath
+        def __init__(self, namespace_path) -> None: ...
+        def resource_path(self, resource: str) -> str: ...
+        def files(self) -> MultiplexedPath: ...

stdlib/importlib/resources/readers.pyi

@@ -0,0 +1,14 @@
+# On py311+, things are actually defined here
+# and re-exported from importlib.readers,
+# but doing it this way leads to less code duplication for us
+
+import sys
+from collections.abc import Iterable, Iterator
+from typing import TypeVar
+
+if sys.version_info >= (3, 11):
+    from importlib.readers import *
+
+    _T = TypeVar("_T")
+
+    def remove_duplicates(items: Iterable[_T]) -> Iterator[_T]: ...

tests/stubtest_allowlists/py310.txt

@@ -24,9 +24,6 @@ types.GenericAlias.__call__  # Would be complicated to fix properly, Any could s
 typing._SpecialForm.__mro_entries__
 weakref.ProxyType.__reversed__  # Doesn't really exist
 
-# Modules that exist at runtime, but are missing from typeshed
-importlib.readers
-
 # Modules that exist at runtime, but shouldn't be added to typeshed
 ctypes.test
 ctypes\.test\..+

tests/stubtest_allowlists/py311.txt

@@ -18,8 +18,6 @@ typing.NewType.__call__
 typing.NewType.__mro_entries__
 
 # Modules that exist at runtime, but are missing from typeshed
-importlib.readers
-importlib.resources.readers
 importlib.resources.simple
 importlib.simple
 

tests/stubtest_allowlists/py312.txt

@@ -1,7 +1,5 @@
 # Modules that exist at runtime, but are missing from typeshed
 zipfile._path.glob
-importlib.readers
-importlib.resources.readers
 importlib.resources.simple
 importlib.simple