gh-148588: Document __lazy_modules__ compatibility mode for lazy imports

Add documentation for the __lazy_modules__ module attribute in two places:

- Doc/reference/simple_stmts.rst: new subsection under the lazy imports
  section explaining the compatibility mode, its semantics (module-scope
  only, overridden by -X lazy_imports=none), and a usage example.

- Doc/reference/datamodel.rst: new module.__lazy_modules__ attribute entry
  with a cross-reference to the detailed explanation in simple_stmts.

Also extend the What's New in Python 3.15 lazy-imports entry with a short
paragraph and example demonstrating __lazy_modules__.

Author: johnslavik

Doc/reference/datamodel.rst

@@ -926,6 +926,7 @@ Attribute assignment updates the module's namespace dictionary, e.g.,
    single: __doc__ (module attribute)
    single: __annotations__ (module attribute)
    single: __annotate__ (module attribute)
+   single: __lazy_modules__ (module attribute)
    pair: module; namespace
 
 .. _import-mod-attrs:
@@ -1121,6 +1122,19 @@ the following writable attributes:
 
    .. versionadded:: 3.14
 
+.. attribute:: module.__lazy_modules__
+
+   An optional sequence of absolute module name strings.  When defined at
+   module scope, any regular :keyword:`import` statement in that module whose
+   target module name appears in this sequence is treated as a
+   :ref:`lazy import <lazy-imports>`, as if the :keyword:`lazy` keyword had
+   been used.  Imports inside functions, class bodies, or
+   :keyword:`try`/:keyword:`except`/:keyword:`finally` blocks are unaffected.
+
+   See :ref:`lazy-modules-compat` for details and examples.
+
+   .. versionadded:: 3.15
+
 Module dictionaries
 ^^^^^^^^^^^^^^^^^^^
 

Doc/reference/simple_stmts.rst

@@ -920,6 +920,46 @@ See :pep:`810` for the full specification of lazy imports.
 
 .. versionadded:: 3.15
 
+.. _lazy-modules-compat:
+
+Compatibility mode via ``__lazy_modules__``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. index::
+   single: __lazy_modules__
+
+As an alternative to using the :keyword:`lazy` keyword, a module can opt
+into lazy loading for specific imports by defining a module-level
+:attr:`~module.__lazy_modules__` variable.  When present, it must be a
+sequence of absolute module name strings.  Any regular (non-``lazy``)
+:keyword:`import` statement at module scope whose target appears in
+:attr:`!__lazy_modules__` is treated as a lazy import, exactly as if the
+:keyword:`lazy` keyword had been used.
+
+This provides a way to enable lazy loading for specific dependencies without
+changing individual ``import`` statements — useful when migrating existing
+code or when the imports are generated programmatically::
+
+   __lazy_modules__ = ["json", "pathlib"]
+
+   import json     # loaded lazily (name is in __lazy_modules__)
+   import os       # loaded eagerly (name not in __lazy_modules__)
+
+   import pathlib  # loaded lazily
+
+Relative imports are resolved to their absolute name before the lookup, so
+the sequence must always contain absolute module names.
+
+Imports inside functions, class bodies, or
+:keyword:`try`/:keyword:`except`/:keyword:`finally` blocks are always eager,
+regardless of :attr:`!__lazy_modules__`.
+
+Setting ``-X lazy_imports=none`` (or the :envvar:`PYTHON_LAZY_IMPORTS`
+environment variable to ``none``) overrides :attr:`!__lazy_modules__` and
+forces all imports to be eager.
+
+.. versionadded:: 3.15
+
 .. _future:
 
 Future statements

Doc/whatsnew/3.15.rst

@@ -182,6 +182,17 @@ function, class body, or ``try``/``except``/``finally`` block raises a
 (``lazy from module import *`` and ``lazy from __future__ import ...`` both
 raise :exc:`SyntaxError`).
 
+For code that cannot use the ``lazy`` keyword directly — for example, when
+migrating a large existing codebase — a module can define
+:attr:`~module.__lazy_modules__` as a sequence of absolute module name
+strings.  Regular ``import`` statements for those modules are then treated
+as lazy, with the same semantics as the ``lazy`` keyword::
+
+   __lazy_modules__ = ["json", "pathlib"]
+
+   import json     # lazy
+   import os       # still eager
+
 .. seealso:: :pep:`810` for the full specification and rationale.
 
 (Contributed by Pablo Galindo Salgado and Dino Viehland in :gh:`142349`.)

Misc/NEWS.d/next/Documentation/2026-04-15-00-06-40.gh-issue-148588.gC7AEZ.rst

@@ -0,0 +1,3 @@
+Document :attr:`module.__lazy_modules__`, the compatibility-mode mechanism
+for opting specific imports into lazy loading without the :keyword:`lazy`
+keyword, in the language reference and the "What's New in Python 3.15" page.