From 29215a0fe331324492a6980f2b339ec7d719366c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Filipe=20La=C3=ADns?= <lains@riseup.net>
Date: Fri, 10 Oct 2025 14:03:51 +0100
Subject: [PATCH] gh-139899: Introduce MetaPathFinder.discover and
 PathEntryFinder.discover
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Filipe Laíns <lains@riseup.net>
---
 Doc/library/importlib.rst                     | 20 +++++++++++
 Lib/importlib/_bootstrap_external.py          | 36 +++++++++++++++++++
 Lib/importlib/abc.py                          | 17 +++++++++
 ...-10-10-14-08-58.gh-issue-139899.09leRY.rst |  2 ++
 4 files changed, 75 insertions(+)
 create mode 100644 Misc/NEWS.d/next/Library/2025-10-10-14-08-58.gh-issue-139899.09leRY.rst

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index 7eb048fcfc28f9..b990ffadb0f867 100644
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -275,6 +275,16 @@ ABC hierarchy::
       .. versionchanged:: 3.4
          Returns ``None`` when called instead of :data:`NotImplemented`.
 
+   .. method:: discover(parent=None)
+
+      An optional method which searches for possible specs with given *parent*.
+      If *parent* is *None*, :meth:`MetaPathFinder.discover` will search for
+      top-level modules.
+
+      Returns an iterable of possible specs.
+
+      .. versionadded:: next
+
 
 .. class:: PathEntryFinder
 
@@ -307,6 +317,16 @@ ABC hierarchy::
       :meth:`importlib.machinery.PathFinder.invalidate_caches`
       when invalidating the caches of all cached finders.
 
+   .. method:: discover(parent=None)
+
+      An optional method which searches for possible specs with given *parent*.
+      If *parent* is *None*, :meth:`PathEntryFinder.discover` will search for
+      top-level modules.
+
+      Returns an iterable of possible specs.
+
+      .. versionadded:: next
+
 
 .. class:: Loader
 
diff --git a/Lib/importlib/_bootstrap_external.py b/Lib/importlib/_bootstrap_external.py
index 9269bb77806c83..87ade1e295b5f9 100644
--- a/Lib/importlib/_bootstrap_external.py
+++ b/Lib/importlib/_bootstrap_external.py
@@ -1317,6 +1317,21 @@ def find_spec(cls, fullname, path=None, target=None):
         else:
             return spec
 
+    @classmethod
+    def discover(cls, parent=None):
+        if parent is None:
+            path = sys.path
+        else:
+            path = parent.__spec__.submodule_search_locations
+
+        for entry in path:
+            if not isinstance(entry, str):
+                continue
+            if (finder := cls._path_importer_cache(entry)) is None:
+                continue
+            if discover := getattr(finder, 'discover', None):
+                yield from discover(parent)
+
     @staticmethod
     def find_distributions(*args, **kwargs):
         """
@@ -1466,6 +1481,27 @@ def path_hook_for_FileFinder(path):
 
         return path_hook_for_FileFinder
 
+    def _find_children(self):
+        for entry in _os.scandir(self.path):
+            if entry.name == _PYCACHE:
+                continue
+            # packages
+            if entry.is_dir() and '.' not in entry.name:
+                yield entry.name
+            # files
+            if entry.is_file():
+                yield from [
+                    entry.name.removesuffix(suffix)
+                    for suffix, _ in self._loaders
+                    if entry.name.endswith(suffix)
+                ]
+
+    def discover(self, parent=None):
+        module_prefix = f'{parent.__name__}.' if parent else ''
+        for child_name in self._find_children():
+            if spec := self.find_spec(module_prefix + child_name):
+                yield spec
+
     def __repr__(self):
         return f'FileFinder({self.path!r})'
 
diff --git a/Lib/importlib/abc.py b/Lib/importlib/abc.py
index 1e47495f65fa02..2de21e8095c742 100644
--- a/Lib/importlib/abc.py
+++ b/Lib/importlib/abc.py
@@ -45,6 +45,15 @@ def invalidate_caches(self):
         This method is used by importlib.invalidate_caches().
         """
 
+    def discover(self, parent=None):
+        """An optional method which searches for possible specs with given *parent*.
+        If *parent* is *None*, MetaPathFinder.discover will search for top-level modules.
+
+        Returns an iterable of possible specs.
+        """
+        return ()
+
+
 _register(MetaPathFinder, machinery.BuiltinImporter, machinery.FrozenImporter,
           machinery.PathFinder, machinery.WindowsRegistryFinder)
 
@@ -58,6 +67,14 @@ def invalidate_caches(self):
         This method is used by PathFinder.invalidate_caches().
         """
 
+    def discover(self, parent=None):
+        """An optional method which searches for possible specs with given *parent*.
+        If *parent* is *None*, PathEntryFinder.discover will search for top-level modules.
+
+        Returns an iterable of possible specs.
+        """
+        return ()
+
 _register(PathEntryFinder, machinery.FileFinder)
 
 
diff --git a/Misc/NEWS.d/next/Library/2025-10-10-14-08-58.gh-issue-139899.09leRY.rst b/Misc/NEWS.d/next/Library/2025-10-10-14-08-58.gh-issue-139899.09leRY.rst
new file mode 100644
index 00000000000000..5851566609188f
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2025-10-10-14-08-58.gh-issue-139899.09leRY.rst
@@ -0,0 +1,2 @@
+Introduced :meth:`MetaPathFinder.discover` and
+:meth:`PathEntryFinder.discover`.