Naming and inheritance for importlib (#12775)

tungol · web-flow · commit 0301510114a8 · 2024-10-29T11:09:00.000+01:00
This MR breaks out _frozen_importlib_external (which is the same
thing as importlib._bootstrap_external) and _frozen_importlib
(which is the same thing as importlib._bootstrap).
diff --git a/stdlib/@tests/stubtest_allowlists/common.txt b/stdlib/@tests/stubtest_allowlists/common.txt
@@ -13,6 +13,10 @@ _collections_abc.ItemsView.__reversed__
 _collections_abc.KeysView.__reversed__
 _collections_abc.ValuesView.__reversed__
 _ctypes.CFuncPtr  # stubtest erroneously thinks it can't be subclassed
+_frozen_importlib_external.ExtensionFileLoader.get_filename  # Wrapped with _check_name decorator which changes runtime signature
+_frozen_importlib_external.FileLoader.get_filename  # Wrapped with _check_name decorator which changes runtime signature
+_frozen_importlib_external.FileLoader.get_resource_reader  # Wrapped with _check_name decorator which changes runtime signature
+_frozen_importlib_external.FileLoader.load_module  # Wrapped with _check_name decorator which changes runtime signature
 _threading_local.local.__new__
 ast.Bytes.__new__
 ast.Ellipsis.__new__
@@ -45,6 +49,10 @@ hmac.new  # Stub is a white lie; see comments in the stub
 http.HTTPStatus.description  # set in __new__
 http.HTTPStatus.phrase  # set in __new__
 http.client.HTTPConnection.response_class  # the actual type at runtime is abc.ABCMeta
+importlib._bootstrap_external.ExtensionFileLoader.get_filename  # Wrapped with _check_name decorator which changes runtime signature
+importlib._bootstrap_external.FileLoader.get_filename  # Wrapped with _check_name decorator which changes runtime signature
+importlib._bootstrap_external.FileLoader.get_resource_reader  # Wrapped with _check_name decorator which changes runtime signature
+importlib._bootstrap_external.FileLoader.load_module  # Wrapped with _check_name decorator which changes runtime signature
 importlib.abc.FileLoader.get_filename  # Wrapped with _check_name decorator which changes runtime signature
 importlib.abc.FileLoader.load_module  # Wrapped with _check_name decorator which changes runtime signature
 importlib.abc.Loader.exec_module  # See Lib/importlib/_abc.py. Might be defined for backwards compatibility
@@ -261,6 +269,12 @@ idlelib
 importlib.machinery.WindowsRegistryFinder.DEBUG_BUILD
 importlib.machinery.WindowsRegistryFinder.REGISTRY_KEY
 importlib.machinery.WindowsRegistryFinder.REGISTRY_KEY_DEBUG
+_frozen_importlib_external.WindowsRegistryFinder.DEBUG_BUILD
+_frozen_importlib_external.WindowsRegistryFinder.REGISTRY_KEY
+_frozen_importlib_external.WindowsRegistryFinder.REGISTRY_KEY_DEBUG
+importlib._bootstrap_external.WindowsRegistryFinder.DEBUG_BUILD
+importlib._bootstrap_external.WindowsRegistryFinder.REGISTRY_KEY
+importlib._bootstrap_external.WindowsRegistryFinder.REGISTRY_KEY_DEBUG
 
 # Undocumented implementation details
 profile.Profile.dispatch
diff --git a/stdlib/VERSIONS b/stdlib/VERSIONS
@@ -34,6 +34,8 @@ _curses: 3.0-
 _decimal: 3.3-
 _dummy_thread: 3.0-3.8
 _dummy_threading: 3.0-3.8
+_frozen_importlib: 3.0-
+_frozen_importlib_external: 3.5-
 _heapq: 3.0-
 _imp: 3.0-
 _interpchannels: 3.13-
@@ -161,6 +163,8 @@ imghdr: 3.0-3.12
 imp: 3.0-3.11
 importlib: 3.0-
 importlib._abc: 3.10-
+importlib._bootstrap: 3.0-
+importlib._bootstrap_external: 3.5-
 importlib.metadata: 3.8-
 importlib.metadata._meta: 3.10-
 importlib.metadata.diagnose: 3.13-
diff --git a/stdlib/_frozen_importlib.pyi b/stdlib/_frozen_importlib.pyi
@@ -0,0 +1,112 @@
+import importlib.abc
+import importlib.machinery
+import sys
+import types
+from _typeshed.importlib import LoaderProtocol
+from collections.abc import Mapping, Sequence
+from types import ModuleType
+from typing import Any
+
+# Signature of `builtins.__import__` should be kept identical to `importlib.__import__`
+def __import__(
+    name: str,
+    globals: Mapping[str, object] | None = None,
+    locals: Mapping[str, object] | None = None,
+    fromlist: Sequence[str] = (),
+    level: int = 0,
+) -> ModuleType: ...
+def spec_from_loader(
+    name: str, loader: LoaderProtocol | None, *, origin: str | None = None, is_package: bool | None = None
+) -> importlib.machinery.ModuleSpec | None: ...
+def module_from_spec(spec: importlib.machinery.ModuleSpec) -> types.ModuleType: ...
+def _init_module_attrs(
+    spec: importlib.machinery.ModuleSpec, module: types.ModuleType, *, override: bool = False
+) -> types.ModuleType: ...
+
+class ModuleSpec:
+    def __init__(
+        self,
+        name: str,
+        loader: importlib.abc.Loader | None,
+        *,
+        origin: str | None = None,
+        loader_state: Any = None,
+        is_package: bool | None = None,
+    ) -> None: ...
+    name: str
+    loader: importlib.abc.Loader | None
+    origin: str | None
+    submodule_search_locations: list[str] | None
+    loader_state: Any
+    cached: str | None
+    @property
+    def parent(self) -> str | None: ...
+    has_location: bool
+    def __eq__(self, other: object) -> bool: ...
+
+class BuiltinImporter(importlib.abc.MetaPathFinder, importlib.abc.InspectLoader):
+    # MetaPathFinder
+    if sys.version_info < (3, 12):
+        @classmethod
+        def find_module(cls, fullname: str, path: Sequence[str] | None = None) -> importlib.abc.Loader | None: ...
+
+    @classmethod
+    def find_spec(
+        cls, fullname: str, path: Sequence[str] | None = None, target: types.ModuleType | None = None
+    ) -> ModuleSpec | None: ...
+    # InspectLoader
+    @classmethod
+    def is_package(cls, fullname: str) -> bool: ...
+    @classmethod
+    def load_module(cls, fullname: str) -> types.ModuleType: ...
+    @classmethod
+    def get_code(cls, fullname: str) -> None: ...
+    @classmethod
+    def get_source(cls, fullname: str) -> None: ...
+    # Loader
+    if sys.version_info < (3, 12):
+        @staticmethod
+        def module_repr(module: types.ModuleType) -> str: ...
+    if sys.version_info >= (3, 10):
+        @staticmethod
+        def create_module(spec: ModuleSpec) -> types.ModuleType | None: ...
+        @staticmethod
+        def exec_module(module: types.ModuleType) -> None: ...
+    else:
+        @classmethod
+        def create_module(cls, spec: ModuleSpec) -> types.ModuleType | None: ...
+        @classmethod
+        def exec_module(cls, module: types.ModuleType) -> None: ...
+
+class FrozenImporter(importlib.abc.MetaPathFinder, importlib.abc.InspectLoader):
+    # MetaPathFinder
+    if sys.version_info < (3, 12):
+        @classmethod
+        def find_module(cls, fullname: str, path: Sequence[str] | None = None) -> importlib.abc.Loader | None: ...
+
+    @classmethod
+    def find_spec(
+        cls, fullname: str, path: Sequence[str] | None = None, target: types.ModuleType | None = None
+    ) -> ModuleSpec | None: ...
+    # InspectLoader
+    @classmethod
+    def is_package(cls, fullname: str) -> bool: ...
+    @classmethod
+    def load_module(cls, fullname: str) -> types.ModuleType: ...
+    @classmethod
+    def get_code(cls, fullname: str) -> None: ...
+    @classmethod
+    def get_source(cls, fullname: str) -> None: ...
+    # Loader
+    if sys.version_info < (3, 12):
+        @staticmethod
+        def module_repr(m: types.ModuleType) -> str: ...
+    if sys.version_info >= (3, 10):
+        @staticmethod
+        def create_module(spec: ModuleSpec) -> types.ModuleType | None: ...
+    else:
+        @classmethod
+        def create_module(cls, spec: ModuleSpec) -> types.ModuleType | None: ...
+
+    @staticmethod
+    def exec_module(module: types.ModuleType) -> None: ...
diff --git a/stdlib/_frozen_importlib_external.pyi b/stdlib/_frozen_importlib_external.pyi
@@ -0,0 +1,178 @@
+import _ast
+import _io
+import importlib.abc
+import importlib.machinery
+import sys
+import types
+from _typeshed import ReadableBuffer, StrOrBytesPath, StrPath
+from _typeshed.importlib import LoaderProtocol
+from collections.abc import Callable, Iterable, Iterator, Mapping, MutableSequence, Sequence
+from importlib.machinery import ModuleSpec
+from importlib.metadata import DistributionFinder, PathDistribution
+from typing import Any, Literal
+from typing_extensions import Self, deprecated
+
+if sys.version_info >= (3, 10):
+    import importlib.readers
+
+if sys.platform == "win32":
+    path_separators: Literal["\\/"]
+    path_sep: Literal["\\"]
+    path_sep_tuple: tuple[Literal["\\"], Literal["/"]]
+else:
+    path_separators: Literal["/"]
+    path_sep: Literal["/"]
+    path_sep_tuple: tuple[Literal["/"]]
+
+MAGIC_NUMBER: bytes
+
+def cache_from_source(path: str, debug_override: bool | None = None, *, optimization: Any | None = None) -> str: ...
+def source_from_cache(path: str) -> str: ...
+def decode_source(source_bytes: ReadableBuffer) -> str: ...
+def spec_from_file_location(
+    name: str,
+    location: StrOrBytesPath | None = None,
+    *,
+    loader: LoaderProtocol | None = None,
+    submodule_search_locations: list[str] | None = ...,
+) -> importlib.machinery.ModuleSpec | None: ...
+
+class WindowsRegistryFinder(importlib.abc.MetaPathFinder):
+    if sys.version_info < (3, 12):
+        @classmethod
+        def find_module(cls, fullname: str, path: Sequence[str] | None = None) -> importlib.abc.Loader | None: ...
+
+    @classmethod
+    def find_spec(
+        cls, fullname: str, path: Sequence[str] | None = None, target: types.ModuleType | None = None
+    ) -> ModuleSpec | None: ...
+
+class PathFinder(importlib.abc.MetaPathFinder):
+    if sys.version_info >= (3, 10):
+        @staticmethod
+        def invalidate_caches() -> None: ...
+    else:
+        @classmethod
+        def invalidate_caches(cls) -> None: ...
+    if sys.version_info >= (3, 10):
+        @staticmethod
+        def find_distributions(context: DistributionFinder.Context = ...) -> Iterable[PathDistribution]: ...
+    else:
+        @classmethod
+        def find_distributions(cls, context: DistributionFinder.Context = ...) -> Iterable[PathDistribution]: ...
+
+    @classmethod
+    def find_spec(
+        cls, fullname: str, path: Sequence[str] | None = None, target: types.ModuleType | None = None
+    ) -> ModuleSpec | None: ...
+    if sys.version_info < (3, 12):
+        @classmethod
+        def find_module(cls, fullname: str, path: Sequence[str] | None = None) -> importlib.abc.Loader | None: ...
+
+SOURCE_SUFFIXES: list[str]
+DEBUG_BYTECODE_SUFFIXES: list[str]
+OPTIMIZED_BYTECODE_SUFFIXES: list[str]
+BYTECODE_SUFFIXES: list[str]
+EXTENSION_SUFFIXES: list[str]
+
+class FileFinder(importlib.abc.PathEntryFinder):
+    path: str
+    def __init__(self, path: str, *loader_details: tuple[type[importlib.abc.Loader], list[str]]) -> None: ...
+    @classmethod
+    def path_hook(
+        cls, *loader_details: tuple[type[importlib.abc.Loader], list[str]]
+    ) -> Callable[[str], importlib.abc.PathEntryFinder]: ...
+
+class _LoaderBasics:
+    def is_package(self, fullname: str) -> bool: ...
+    def create_module(self, spec: ModuleSpec) -> types.ModuleType | None: ...
+    def exec_module(self, module: types.ModuleType) -> None: ...
+    def load_module(self, fullname: str) -> types.ModuleType: ...
+
+class SourceLoader(_LoaderBasics):
+    def path_mtime(self, path: str) -> float: ...
+    def set_data(self, path: str, data: bytes) -> None: ...
+    def get_source(self, fullname: str) -> str | None: ...
+    def path_stats(self, path: str) -> Mapping[str, Any]: ...
+    def source_to_code(
+        self, data: ReadableBuffer | str | _ast.Module | _ast.Expression | _ast.Interactive, path: ReadableBuffer | StrPath
+    ) -> types.CodeType: ...
+    def get_code(self, fullname: str) -> types.CodeType | None: ...
+
+class FileLoader:
+    name: str
+    path: str
+    def __init__(self, fullname: str, path: str) -> None: ...
+    def get_data(self, path: str) -> bytes: ...
+    def get_filename(self, name: str | None = None) -> str: ...
+    def load_module(self, name: str | None = None) -> types.ModuleType: ...
+    if sys.version_info >= (3, 10):
+        def get_resource_reader(self, module: types.ModuleType) -> importlib.readers.FileReader: ...
+    else:
+        def get_resource_reader(self, module: types.ModuleType) -> Self | None: ...
+        def open_resource(self, resource: str) -> _io.FileIO: ...
+        def resource_path(self, resource: str) -> str: ...
+        def is_resource(self, name: str) -> bool: ...
+        def contents(self) -> Iterator[str]: ...
+
+class SourceFileLoader(importlib.abc.FileLoader, FileLoader, importlib.abc.SourceLoader, SourceLoader):  # type: ignore[misc]  # incompatible method arguments in base classes
+    def set_data(self, path: str, data: ReadableBuffer, *, _mode: int = 0o666) -> None: ...
+    def path_stats(self, path: str) -> Mapping[str, Any]: ...
+
+class SourcelessFileLoader(importlib.abc.FileLoader, FileLoader, _LoaderBasics):
+    def get_code(self, fullname: str) -> types.CodeType | None: ...
+    def get_source(self, fullname: str) -> None: ...
+
+class ExtensionFileLoader(FileLoader, _LoaderBasics, importlib.abc.ExecutionLoader):
+    def __init__(self, name: str, path: str) -> None: ...
+    def get_filename(self, name: str | None = None) -> str: ...
+    def get_source(self, fullname: str) -> None: ...
+    def create_module(self, spec: ModuleSpec) -> types.ModuleType: ...
+    def exec_module(self, module: types.ModuleType) -> None: ...
+    def get_code(self, fullname: str) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __hash__(self) -> int: ...
+
+if sys.version_info >= (3, 11):
+    class NamespaceLoader(importlib.abc.InspectLoader):
+        def __init__(
+            self, name: str, path: MutableSequence[str], path_finder: Callable[[str, tuple[str, ...]], ModuleSpec]
+        ) -> None: ...
+        def is_package(self, fullname: str) -> Literal[True]: ...
+        def get_source(self, fullname: str) -> Literal[""]: ...
+        def get_code(self, fullname: str) -> types.CodeType: ...
+        def create_module(self, spec: ModuleSpec) -> None: ...
+        def exec_module(self, module: types.ModuleType) -> None: ...
+        @deprecated("load_module() is deprecated; use exec_module() instead")
+        def load_module(self, fullname: str) -> types.ModuleType: ...
+        def get_resource_reader(self, module: types.ModuleType) -> importlib.readers.NamespaceReader: ...
+        if sys.version_info < (3, 12):
+            @staticmethod
+            @deprecated("module_repr() is deprecated, and has been removed in Python 3.12")
+            def module_repr(module: types.ModuleType) -> str: ...
+
+    _NamespaceLoader = NamespaceLoader
+else:
+    class _NamespaceLoader:
+        def __init__(
+            self, name: str, path: MutableSequence[str], path_finder: Callable[[str, tuple[str, ...]], ModuleSpec]
+        ) -> None: ...
+        def is_package(self, fullname: str) -> Literal[True]: ...
+        def get_source(self, fullname: str) -> Literal[""]: ...
+        def get_code(self, fullname: str) -> types.CodeType: ...
+        def create_module(self, spec: ModuleSpec) -> None: ...
+        def exec_module(self, module: types.ModuleType) -> None: ...
+        @deprecated("load_module() is deprecated; use exec_module() instead")
+        def load_module(self, fullname: str) -> types.ModuleType: ...
+        if sys.version_info >= (3, 10):
+            @staticmethod
+            @deprecated("module_repr() is deprecated, and has been removed in Python 3.12")
+            def module_repr(module: types.ModuleType) -> str: ...
+            def get_resource_reader(self, module: types.ModuleType) -> importlib.readers.NamespaceReader: ...
+        else:
+            @classmethod
+            @deprecated("module_repr() is deprecated, and has been removed in Python 3.12")
+            def module_repr(cls, module: types.ModuleType) -> str: ...
+
+if sys.version_info >= (3, 13):
+    class AppleFrameworkLoader(ExtensionFileLoader, importlib.abc.ExecutionLoader): ...
diff --git a/stdlib/importlib/__init__.pyi b/stdlib/importlib/__init__.pyi
@@ -1,19 +1,10 @@
 import sys
-from collections.abc import Mapping, Sequence
+from importlib._bootstrap import __import__ as __import__
 from importlib.abc import Loader
 from types import ModuleType
 
 __all__ = ["__import__", "import_module", "invalidate_caches", "reload"]
 
-# Signature of `builtins.__import__` should be kept identical to `importlib.__import__`
-def __import__(
-    name: str,
-    globals: Mapping[str, object] | None = None,
-    locals: Mapping[str, object] | None = None,
-    fromlist: Sequence[str] = (),
-    level: int = 0,
-) -> ModuleType: ...
-
 # `importlib.import_module` return type should be kept the same as `builtins.__import__`
 def import_module(name: str, package: str | None = None) -> ModuleType: ...
 
diff --git a/stdlib/importlib/_bootstrap.pyi b/stdlib/importlib/_bootstrap.pyi
@@ -0,0 +1,2 @@
+from _frozen_importlib import *
+from _frozen_importlib import __import__ as __import__, _init_module_attrs as _init_module_attrs
diff --git a/stdlib/importlib/_bootstrap_external.pyi b/stdlib/importlib/_bootstrap_external.pyi
@@ -0,0 +1,2 @@
+from _frozen_importlib_external import *
+from _frozen_importlib_external import _NamespaceLoader as _NamespaceLoader
diff --git a/stdlib/importlib/abc.pyi b/stdlib/importlib/abc.pyi
@@ -4,6 +4,7 @@ import types
 from _typeshed import ReadableBuffer, StrPath
 from abc import ABCMeta, abstractmethod
 from collections.abc import Iterator, Mapping, Sequence
+from importlib import _bootstrap_external
 from importlib.machinery import ModuleSpec
 from io import BufferedReader
 from typing import IO, Any, Literal, Protocol, overload, runtime_checkable
@@ -56,7 +57,7 @@ class ExecutionLoader(InspectLoader):
     @abstractmethod
     def get_filename(self, fullname: str) -> str: ...
 
-class SourceLoader(ResourceLoader, ExecutionLoader, metaclass=ABCMeta):
+class SourceLoader(_bootstrap_external.SourceLoader, ResourceLoader, ExecutionLoader, metaclass=ABCMeta):  # type: ignore[misc]  # incompatible definitions of source_to_code in the base classes
     def path_mtime(self, path: str) -> float: ...
     def set_data(self, path: str, data: bytes) -> None: ...
     def get_source(self, fullname: str) -> str | None: ...
@@ -101,7 +102,7 @@ else:
         # Not defined on the actual class, but expected to exist.
         def find_spec(self, fullname: str, target: types.ModuleType | None = ...) -> ModuleSpec | None: ...
 
-class FileLoader(ResourceLoader, ExecutionLoader, metaclass=ABCMeta):
+class FileLoader(_bootstrap_external.FileLoader, ResourceLoader, ExecutionLoader, metaclass=ABCMeta):
     name: str
     path: str
     def __init__(self, fullname: str, path: str) -> None: ...
diff --git a/stdlib/importlib/machinery.pyi b/stdlib/importlib/machinery.pyi
diff --git a/stdlib/importlib/util.pyi b/stdlib/importlib/util.pyi

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+from _frozen_importlib import *`
	`2`	`+from _frozen_importlib import __import__ as __import__, _init_module_attrs as _init_module_attrs`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+from _frozen_importlib_external import *`
	`2`	`+from _frozen_importlib_external import _NamespaceLoader as _NamespaceLoader`