GH-119668: expose importlib.machinery.NamespacePath

Doc/library/importlib.rst

@@ -985,6 +985,17 @@ find and load modules.
       :exc:`ImportError` is raised.
 
 
+.. class:: NamespacePath(name, path, path_finder)
+
+   Represents a namespace package's path.
+
+   It uses the module *name* to find its parent module, and from there it looks
+   up the parent's :attr:`module.__path__`.  When this changes, the module's own
+   path is recomputed, using *path_finder*. The initial value is set to *path*.
+
+   For top-level modules, the parent module's path is :data:`sys.path`.
+
+
 .. class:: SourceFileLoader(fullname, path)
 
    A concrete implementation of :class:`importlib.abc.SourceLoader` by

Lib/importlib/_bootstrap_external.py

@@ -1079,12 +1079,15 @@ def get_filename(self, fullname):
         return self.path
 
 
-class _NamespacePath:
-    """Represents a namespace package's path.  It uses the module name
-    to find its parent module, and from there it looks up the parent's
-    __path__.  When this changes, the module's own path is recomputed,
-    using path_finder.  For top-level modules, the parent module's path
-    is sys.path."""
+class NamespacePath:
+    """Represents a namespace package's path.
+
+    It uses the module *name* to find its parent module, and from there it looks
+    up the parent's __path__. When this changes, the module's own path is
+    recomputed, using *path_finder*. The initial value is set to *path*.
+
+    For top-level modules, the parent module's path is sys.path.
+    """
 
     # When invalidate_caches() is called, this epoch is incremented
     # https://bugs.python.org/issue45703
@@ -1138,7 +1141,7 @@ def __len__(self):
         return len(self._recalculate())
 
     def __repr__(self):
-        return f'_NamespacePath({self._path!r})'
+        return f'NamespacePath({self._path!r})'
 
     def __contains__(self, item):
         return item in self._recalculate()
@@ -1147,12 +1150,15 @@ def append(self, item):
         self._path.append(item)
 
 
+_NamespacePath = NamespacePath  # for backwards compatibility
+
+
 # This class is actually exposed publicly in a namespace package's __loader__
 # attribute, so it should be available through a non-private name.
 # https://github.com/python/cpython/issues/92054
 class NamespaceLoader:
     def __init__(self, name, path, path_finder):
-        self._path = _NamespacePath(name, path, path_finder)
+        self._path = NamespacePath(name, path, path_finder)
 
     def is_package(self, fullname):
         return True
@@ -1207,9 +1213,9 @@ def invalidate_caches():
                 del sys.path_importer_cache[name]
             elif hasattr(finder, 'invalidate_caches'):
                 finder.invalidate_caches()
-        # Also invalidate the caches of _NamespacePaths
+        # Also invalidate the caches of NamespacePaths
         # https://bugs.python.org/issue45703
-        _NamespacePath._epoch += 1
+        NamespacePath._epoch += 1
 
         from importlib.metadata import MetadataPathFinder
         MetadataPathFinder.invalidate_caches()
@@ -1295,7 +1301,7 @@ def find_spec(cls, fullname, path=None, target=None):
                 # We found at least one namespace path.  Return a spec which
                 # can create the namespace package.
                 spec.origin = None
-                spec.submodule_search_locations = _NamespacePath(fullname, namespace_path, cls._get_spec)
+                spec.submodule_search_locations = NamespacePath(fullname, namespace_path, cls._get_spec)
                 return spec
             else:
                 return None

Lib/importlib/machinery.py

@@ -14,6 +14,7 @@
 from ._bootstrap_external import ExtensionFileLoader
 from ._bootstrap_external import AppleFrameworkLoader
 from ._bootstrap_external import NamespaceLoader
+from ._bootstrap_external import NamespacePath
 
 
 def all_suffixes():

Misc/NEWS.d/next/Library/2024-05-28-17-14-30.gh-issue-119668.RrIGpn.rst

@@ -0,0 +1 @@
+Expose :class:`importlib.machinery.NamespacePath`.