Use protocols instead of importlib.abc.Loader/MetaPathFinder/PathEntryFinder

stdlib/@tests/test_cases/check_importlib.py

@@ -1,7 +1,14 @@
+from __future__ import annotations
+
 import importlib.abc
+import importlib.util
 import pathlib
 import sys
 import zipfile
+from collections.abc import Sequence
+from importlib.machinery import ModuleSpec
+from types import ModuleType
+from typing_extensions import Self
 
 # Assert that some Path classes are Traversable.
 if sys.version_info >= (3, 9):
@@ -11,3 +18,30 @@ def traverse(t: importlib.abc.Traversable) -> None:
 
     traverse(pathlib.Path())
     traverse(zipfile.Path(""))
+
+
+class MetaFinder:
+    @classmethod
+    def find_spec(cls, fullname: str, path: Sequence[str] | None, target: ModuleType | None = None) -> ModuleSpec | None:
+        return None  # simplified mock for demonstration purposes only
+
+
+class PathFinder:
+    @classmethod
+    def path_hook(cls, path_entry: str) -> type[Self]:
+        return cls  # simplified mock for demonstration purposes only
+
+    @classmethod
+    def find_spec(cls, fullname: str, target: ModuleType | None = None) -> ModuleSpec | None:
+        return None  # simplified mock for demonstration purposes only
+
+
+class Loader:
+    @classmethod
+    def load_module(cls, fullname: str) -> ModuleType:
+        return ModuleType(fullname)
+
+
+sys.meta_path.append(MetaFinder)
+sys.path_hooks.append(PathFinder.path_hook)
+importlib.util.spec_from_loader("xxxx42xxxx", Loader)

stdlib/_typeshed/importlib.pyi

@@ -0,0 +1,18 @@
+# Implicit protocols used in importlib.
+# We intentionally omit deprecated and optional methods.
+
+from collections.abc import Sequence
+from importlib.machinery import ModuleSpec
+from types import ModuleType
+from typing import Protocol
+
+__all__ = ["LoaderProtocol", "MetaPathFinderProtocol", "PathEntryFinderProtocol"]
+
+class LoaderProtocol(Protocol):
+    def load_module(self, fullname: str, /) -> ModuleType: ...
+
+class MetaPathFinderProtocol(Protocol):
+    def find_spec(self, fullname: str, path: Sequence[str] | None, target: ModuleType | None = ..., /) -> ModuleSpec | None: ...
+
+class PathEntryFinderProtocol(Protocol):
+    def find_spec(self, fullname: str, target: ModuleType | None = ...) -> ModuleSpec | None: ...

stdlib/importlib/abc.pyi

@@ -64,7 +64,7 @@ class SourceLoader(ResourceLoader, ExecutionLoader, metaclass=ABCMeta):
 
 # The base classes differ starting in 3.10:
 if sys.version_info >= (3, 10):
-    # Please keep in sync with sys._MetaPathFinder
+    # Please keep in sync with _typeshed.MetaPathFinderProtocol
     class MetaPathFinder(metaclass=ABCMeta):
         if sys.version_info < (3, 12):
             def find_module(self, fullname: str, path: Sequence[str] | None) -> Loader | None: ...
@@ -85,7 +85,7 @@ if sys.version_info >= (3, 10):
         def find_spec(self, fullname: str, target: types.ModuleType | None = ...) -> ModuleSpec | None: ...
 
 else:
-    # Please keep in sync with sys._MetaPathFinder
+    # Please keep in sync with _typeshed.MetaPathFinderProtocol
     class MetaPathFinder(Finder):
         def find_module(self, fullname: str, path: Sequence[str] | None) -> Loader | None: ...
         def invalidate_caches(self) -> None: ...

stdlib/importlib/util.pyi

@@ -3,6 +3,7 @@ import importlib.machinery
 import sys
 import types
 from _typeshed import ReadableBuffer, StrOrBytesPath
+from _typeshed.importlib import LoaderProtocol
 from collections.abc import Callable
 from typing import Any
 from typing_extensions import ParamSpec
@@ -23,13 +24,13 @@ def source_from_cache(path: str) -> str: ...
 def decode_source(source_bytes: ReadableBuffer) -> str: ...
 def find_spec(name: str, package: str | None = None) -> importlib.machinery.ModuleSpec | None: ...
 def spec_from_loader(
-    name: str, loader: importlib.abc.Loader | None, *, origin: str | None = None, is_package: bool | None = None
+    name: str, loader: LoaderProtocol | None, *, origin: str | None = None, is_package: bool | None = None
 ) -> importlib.machinery.ModuleSpec | None: ...
 def spec_from_file_location(
     name: str,
     location: StrOrBytesPath | None = None,
     *,
-    loader: importlib.abc.Loader | None = None,
+    loader: LoaderProtocol | None = None,
     submodule_search_locations: list[str] | None = ...,
 ) -> importlib.machinery.ModuleSpec | None: ...
 def module_from_spec(spec: importlib.machinery.ModuleSpec) -> types.ModuleType: ...

stdlib/pkgutil.pyi

@@ -1,7 +1,7 @@
 import sys
 from _typeshed import SupportsRead
+from _typeshed.importlib import LoaderProtocol, MetaPathFinderProtocol, PathEntryFinderProtocol
 from collections.abc import Callable, Iterable, Iterator
-from importlib.abc import Loader, MetaPathFinder, PathEntryFinder
 from typing import IO, Any, NamedTuple, TypeVar
 from typing_extensions import deprecated
 
@@ -23,7 +23,7 @@ if sys.version_info < (3, 12):
 _PathT = TypeVar("_PathT", bound=Iterable[str])
 
 class ModuleInfo(NamedTuple):
-    module_finder: MetaPathFinder | PathEntryFinder
+    module_finder: MetaPathFinderProtocol | PathEntryFinderProtocol
     name: str
     ispkg: bool
 
@@ -37,11 +37,11 @@ if sys.version_info < (3, 12):
         def __init__(self, fullname: str, file: IO[str], filename: str, etc: tuple[str, str, int]) -> None: ...
 
 @deprecated("Use importlib.util.find_spec() instead. Will be removed in Python 3.14.")
-def find_loader(fullname: str) -> Loader | None: ...
-def get_importer(path_item: str) -> PathEntryFinder | None: ...
+def find_loader(fullname: str) -> LoaderProtocol | None: ...
+def get_importer(path_item: str) -> MetaPathFinderProtocol | PathEntryFinderProtocol | None: ...
 @deprecated("Use importlib.util.find_spec() instead. Will be removed in Python 3.14.")
-def get_loader(module_or_name: str) -> Loader | None: ...
-def iter_importers(fullname: str = "") -> Iterator[MetaPathFinder | PathEntryFinder]: ...
+def get_loader(module_or_name: str) -> LoaderProtocol | None: ...
+def iter_importers(fullname: str = "") -> Iterator[MetaPathFinderProtocol | PathEntryFinderProtocol]: ...
 def iter_modules(path: Iterable[str] | None = None, prefix: str = "") -> Iterator[ModuleInfo]: ...
 def read_code(stream: SupportsRead[bytes]) -> Any: ...  # undocumented
 def walk_packages(

stdlib/sys/__init__.pyi

@@ -1,9 +1,8 @@
 import sys
 from _typeshed import OptExcInfo, ProfileFunction, TraceFunction, structseq
+from _typeshed.importlib import MetaPathFinderProtocol, PathEntryFinderProtocol
 from builtins import object as _object
 from collections.abc import AsyncGenerator, Callable, Sequence
-from importlib.abc import PathEntryFinder
-from importlib.machinery import ModuleSpec
 from io import TextIOWrapper
 from types import FrameType, ModuleType, TracebackType
 from typing import Any, Final, Literal, NoReturn, Protocol, TextIO, TypeVar, final
@@ -15,10 +14,6 @@ _T = TypeVar("_T")
 _ExitCode: TypeAlias = str | int | None
 _OptExcInfo: TypeAlias = OptExcInfo  # noqa: Y047  # TODO: obsolete, remove fall 2022 or later
 
-# Intentionally omits one deprecated and one optional method of `importlib.abc.MetaPathFinder`
-class _MetaPathFinder(Protocol):
-    def find_spec(self, fullname: str, path: Sequence[str] | None, target: ModuleType | None = ..., /) -> ModuleSpec | None: ...
-
 # ----- sys variables -----
 if sys.platform != "win32":
     abiflags: str
@@ -44,13 +39,13 @@ if sys.version_info >= (3, 12):
     last_exc: BaseException  # or undefined.
 maxsize: int
 maxunicode: int
-meta_path: list[_MetaPathFinder]
+meta_path: list[MetaPathFinderProtocol]
 modules: dict[str, ModuleType]
 if sys.version_info >= (3, 10):
     orig_argv: list[str]
 path: list[str]
-path_hooks: list[Callable[[str], PathEntryFinder]]
-path_importer_cache: dict[str, PathEntryFinder | None]
+path_hooks: list[Callable[[str], PathEntryFinderProtocol]]
+path_importer_cache: dict[str, PathEntryFinderProtocol | None]
 platform: str
 if sys.version_info >= (3, 9):
     platlibdir: str