PEP 810: Clarify sys.lazy_modules contract

peps/pep-0810.rst

@@ -385,10 +385,11 @@ Lazy import mechanism
 
 When an import is lazy, ``__lazy_import__`` is called instead of
 ``__import__``. ``__lazy_import__`` has the same function signature as
-``__import__``. It adds the module name to ``sys.lazy_modules``, a set of
-fully-qualified module names which have been lazily imported at some point
-(primarily for diagnostics and introspection), and returns a
-:class:`!types.LazyImportType` object for the module.
+``__import__``. It records the lazy import in an internal registry that
+is exposed through ``sys.lazy_modules`` as a read-only mapping from each
+module's fully qualified name to the (frozen) set of its lazily-imported
+submodule names (primarily for diagnostics and introspection), and returns
+a :class:`!types.LazyImportType` object for the module.
 
 The implementation of ``from ... import`` (the ``IMPORT_FROM`` bytecode
 implementation) checks if the module it's fetching from is a lazy module
@@ -398,11 +399,11 @@ instead.
 The end result of this process is that lazy imports (regardless of how they
 are enabled) result in lazy objects being assigned to global variables.
 
-Lazy module objects do not appear in ``sys.modules``, they're just listed in
-the ``sys.lazy_modules`` set. Under normal operation lazy objects should only
-end up stored in global variables, and the common ways to access those
-variables (regular variable access, module attributes) will resolve lazy
-imports (reify) and replace them when they're accessed.
+Lazy module objects do not appear in ``sys.modules``. Under normal
+operation lazy objects should only end up stored in global variables, and
+the common ways to access those variables (regular variable access, module
+attributes) will resolve lazy imports (reify) and replace them when they're
+accessed.
 
 It is still possible to expose lazy objects through other means, like
 debuggers. This is not considered a problem.
@@ -418,10 +419,11 @@ uses the state of the import system (e.g. ``sys.path``, ``sys.meta_path``,
 ``sys.path_hooks`` and ``__import__``) at **reification** time, **not** the
 state when the ``lazy import`` statement was evaluated.
 
-When the module is reified, it's removed from ``sys.lazy_modules`` (even if
-there are still other unreified lazy references to it). When a package is
-reified and submodules in the package were also previously lazily imported,
-those submodules are *not* automatically reified but they *are* added to the
+When the module is reified, its fully qualified name is removed from the
+registry exposed via ``sys.lazy_modules`` (even if there are still other
+unreified lazy references to the module). When a package is reified and
+submodules in the package were also previously lazily imported, those
+submodules are *not* automatically reified but they *are* added to the
 reified package's globals (unless the package already assigned something
 else to the name of the submodule).