GH-119668: expose importlib.machinery.NamespacePath

Doc/library/importlib.rst

@@ -1006,6 +1006,14 @@ 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 ``__path__``.  When
+   this changes, the module's own path is recomputed, using path_finder. For
+   top-level modules, the parent module's path is :py:data:`sys.path`.
+
+
 .. class:: SourceFileLoader(fullname, path)
 
    A concrete implementation of :class:`importlib.abc.SourceLoader` by

Lib/importlib/_bootstrap_external.py

@@ -1347,7 +1347,7 @@ def get_filename(self, fullname):
         return self.path
 
 
-class _NamespacePath:
+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,
@@ -1406,7 +1406,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()
@@ -1415,12 +1415,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
@@ -1475,9 +1478,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()
@@ -1563,7 +1566,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 :py:class:`importlib.NamespacePath`.