Clarify that sys.lazy_modules may contain extra items

encukou · encukou · commit 62f2fcce7904 · 2026-08-11T10:21:17.000+02:00
As an author of a debugging/introspection tool, I need an
honest description of what's in `lazy_modules` and what
kind of post-processing I'm expected to do.
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -1485,11 +1485,24 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 .. data:: lazy_modules
 
    A :class:`set` of fully qualified module name strings that have been lazily
-   imported in the current interpreter but not yet loaded.  When a
-   lazily imported module is accessed for the first time, its name is removed
-   from this set.
+   imported in the current interpreter but not yet loaded.
+   When a lazily imported module is accessed for the first time, its name is
+   typically removed from this set.
 
-   This attribute is intended for debugging and introspection.
+   The set may contain some additional strings.
+   It is intended for debugging and introspection, and consumers are expected
+   to verify each entry's status.
+
+   .. impl-detail::
+
+      Currently, :data:`!lazy_modules` may also contain:
+
+      * names of *attributes* (non-modules), such as ``"pathlib.Path"`` after
+        running ``lazy from pathlib import Path``, and
+      * names of items than have already been accessed.
+
+      In future versions of Python, these may be removed, and/or additional
+      extras may be added.
 
    See also :func:`set_lazy_imports` and :pep:`810`.
 
