Revamp `sys.lazy_modules`

[johnslavik]

Documentation

or make it private, or make it private but expose a mappingproxy.
What are your preferences?

I presume that the PEP must be updated as well (see #145057).

cc @pablogsal @DinoV

Linked PRs

• gh-148587: Make sys.lazy_modules immutable #149408
• [3.15] gh-148587: Make sys.lazy_modules match PEP and keep internal lazy submodules tra… #150014
• gh-148587: Make sys.lazy_modules match PEP and keep internal lazy submodules tracking internal #150086

[johnslavik]

I'm waiting for your feedback in this one!

[pablogsal]

I don't think we should document sys.lazy_modules in its current form.

PEP 810 already mentions sys.lazy_modules, so I don't think we can treat the concept as purely private anymore. But the current implementation exposes a live mutable dict[str, set[str]] that is part of the lazy-import machinery, which is stronger than the contract described in the PEP today.

I also don't think a plain mappingproxy is enough here: it would protect the top-level mapping, but the nested set values would still be mutable. My preference would be:

1. Update PEP 810 to match the intended public contract.
2. Keep the runtime bookkeeping structure private/internal.
3. If we want public diagnostics, expose an immutable snapshot instead of the live container.

Since 814 landed, the public shape could be something like frozendict[str, frozenset[str]]. That gives us a proper read-only introspection API without freezing the internal representation or blessing mutation of interpreter state.

[pablogsal]

CC @Yhg1s @DinoV

[johnslavik]

expose an immutable snapshot instead of the live container.

@pablogsal, does it have to be sys.lazy_modules "module-level property" or could it be a function like sys.get_lazy_modules()?
Both preserve the concept, but the function fits more here I believe (snapshots should be lazy + open/close principle i.e. we can extend the function in the future to do more useful things in debugging if needed). My instinct is that it would be good to ship it before beta freeze.