Address more of Adam's comments.

Author: Yhg1s

peps/pep-0810.rst

@@ -19,7 +19,13 @@ Post-History:
 Abstract
 ========
 
-This PEP introduces syntax for lazy imports as an explicit language feature.
+This PEP introduces syntax for lazy imports as an explicit language feature:
+
+.. code-block:: python
+
+  lazy import json
+  lazy from json import dumps
+
 Lazy imports defer the loading and execution of a module until the first time
 the imported name is used, in contrast to 'normal' imports, which eagerly load
 and execute a module at the point of the import statement. 
@@ -36,9 +42,9 @@ Motivation
 ==========
 
 The dominant convention in Python code is to place all imports at the module
-level, typically at the beginning of the file. This avoids repetition, makes dependencies clear
-and minimizes runtime overhead by only evaluating an import statement once
-per module.
+level, typically at the beginning of the file. This avoids repetition, makes
+import dependencies clear and minimizes runtime overhead by only evaluating
+an import statement once per module.
 
 A major drawback with this approach is that importing the first
 module for an execution of Python (the "main" module) often triggers an immediate
@@ -65,7 +71,7 @@ The standard library provides the :class:`~importlib.util.LazyLoader` class to s
 problems. It permits imports at the module level to work *mostly* like inline
 imports do. Many scientific Python libraries have adopted a similar pattern, formalized
 in `SPEC 1 <https://scientific-python.org/specs/spec-0001/>`__. There's also the
-third-party `lazy_loader <https://pypi.org/project/lazy-loader/>`_ package.
+third-party :pypi:`lazy_loader` package, yet another implementation of lazy imports.
 Imports used solely for static type checking are another source of potentially unneeded
 imports, and there are similarly disparate approaches to minimizing the overhead.
 The various approaches used here to defer or remove eager imports do not cover
@@ -106,21 +112,13 @@ performance-sensitive areas of a codebase. As this feature is introduced to the
 community, we want to make the experience of onboarding optional, progressive, and
 adaptable to the needs of each project.
 
-In addition to the new lazy import syntax, we *also* propose a way to
-control lazy imports at the application level: globally disabling or
-enabling lazy imports, and selectively disabling.
-This global lazy imports flag is provided for debugging, testing, and experimentation,
-and is not expected to be the common way to control lazy imports.
+Lazy imports provide several concrete advantages:
 
-The design of lazy imports provides several concrete advantages:
-
-* Command-line tools are often invoked directly by a user, so latency — in particular
-  startup latency — is quite noticeable. These programs are also typically
-  short-lived processes (contrasted with, e.g., a web server). Most conventions
-  would have a CLI with multiple subcommands import every dependency up front,
-  even if the user only requests ``tool --help`` (or ``tool subcommand --help``).
+* Command-line tools are often invoked directly by a user, so latency -- in particular
+  startup latency -- is quite noticeable. These programs are also typically
+  short-lived processes (contrasted with, e.g., a web server).
   With lazy imports, only the code paths actually reached will import a module.
-  This can reduce startup time by 50–70% in practice, providing a visceral improvement
+  This can reduce startup time by 50-70% in practice, providing a significant improvement
   to a common user experience and improving Python's competitiveness in domains
   where fast startup matters most.
 
@@ -133,7 +131,7 @@ The design of lazy imports provides several concrete advantages:
   function and type objects, incurring memory costs. In long-lived processes,
   this noticeably raises baseline memory usage. Lazy imports defer these costs
   until a module is needed, keeping unused subsystems unloaded. Memory savings of
-  30–40% have been observed in real workloads.
+  30-40% have been observed in real workloads.
 
 Rationale
 =========
@@ -161,8 +159,8 @@ Another important decision is to represent lazy imports with proxy objects in
 the module's namespace, rather than by modifying dictionary lookup. Earlier
 approaches experimented with embedding laziness into dictionaries, but this
 blurred abstractions and risked affecting unrelated parts of the runtime. The
-dictionary is a fundamental data structure in Python—literally every object is
-built on top of dicts—and adding hooks to dictionaries would prevent critical
+dictionary is a fundamental data structure in Python -- literally every object is
+built on top of dicts -- and adding hooks to dictionaries would prevent critical
 optimizations and complicate the entire runtime. The proxy approach is simpler:
 it behaves like a placeholder until first use, at which point it resolves the
 import and rebinds the name. From then on, the binding is indistinguishable
@@ -171,7 +169,7 @@ rest of the interpreter unchanged.
 
 Compatibility for library authors was also a key concern. Many maintainers need
 a migration path that allows them to support both new and old versions of
-Python at once. For this reason, the proposal includes the ``__lazy_modules__``
+Python at once. For this reason, the proposal includes the :data:`!__lazy_modules__`
 global as a transitional mechanism. A module can declare which imports should
 be treated as lazy (by listing the module names as strings), and on Python 3.15
 or later those imports will become lazy automatically, as if they were imported
@@ -188,10 +186,6 @@ be done from the "outside in", permitting CLI authors to introduce lazy imports
 and speed up user-facing tools, without requiring changes to every library the
 tool might use.
 
-By combining explicit syntax, a simple runtime model, a compatibility layer,
-and gradual adoption, this proposal balances performance improvements with the
-clarity and stability that Python users expect.
-
 
 Other design decisions
 ----------------------
@@ -205,8 +199,8 @@ Other design decisions
 
 * In addition, it is useful to provide a mechanism to activate or deactivate lazy
   imports at a global level. While the primary design centers on explicit syntax,
-  there are scenarios—such as large applications, testing environments, or
-  frameworks—where enabling laziness consistently across many modules provides
+  there are scenarios -- such as large applications, testing environments, or
+  frameworks -- where enabling laziness consistently across many modules provides
   the most benefit. A global switch makes it easy to experiment with or enforce
   consistent behavior, while still working in combination with the filtering API
   to respect exclusions or tool-specific configuration. This ensures that global
@@ -291,7 +285,7 @@ Example:
 
   print('json' in sys.modules)  # True - now loaded
 
-A module may contain a ``__lazy_modules__`` attribute, which is a sequence of
+A module may contain a :data:`!__lazy_modules__` attribute, which is a sequence of
 fully qualified module names (strings) to make *potentially lazy* (as if the
 ``lazy`` keyword was used). This attribute is checked on each ``import``
 statement to determine whether the import should be made *potentially lazy*.
@@ -434,7 +428,7 @@ Example using ``__dict__`` from external code:
   print('json' in sys.modules)  # True - reified by __dict__ access
   print(type(d['json']))  # <class 'module'>
 
-However, calling ``globals()`` does **not** trigger reification — it returns
+However, calling ``globals()`` does **not** trigger reification -- it returns
 the module's dictionary, and accessing lazy objects through that dictionary
 still returns lazy proxy objects that need to be manually reified upon use.
 A lazy object can be resolved explicitly by calling the ``get`` method.
@@ -461,8 +455,11 @@ Example using ``globals()``:
   print('json' in sys.modules)  # True - now loaded
 
 
-Implementation
-==============
+Reference Implementation
+========================
+
+A reference implementation is available at:
+https://github.com/LazyImportsCabal/cpython/tree/lazy
 
 Bytecode and adaptive specialization
 -------------------------------------
@@ -638,7 +635,7 @@ Backwards Compatibility
 =======================
 
 Lazy imports are **opt-in**. Existing programs continue to run unchanged unless
-a project explicitly enables laziness (via ``lazy`` syntax, ``__lazy_modules__``,
+a project explicitly enables laziness (via ``lazy`` syntax, :data:`!__lazy_modules__`,
 or an interpreter-wide switch).
 
 Unchanged semantics
@@ -848,7 +845,7 @@ to a lazy object that resolves to ``foo.bar`` on first use.
 **Q: Does** ``lazy from module import Class`` **load the entire module or just the class?**
 
 A: It loads the **entire module**, not just the class. This is because Python's
-import system always executes the complete module file—there's no mechanism to
+import system always executes the complete module file -- there's no mechanism to
 execute only part of a ``.py`` file. When you first access ``Class``, Python:
 
 1. Loads and executes the entire ``module.py`` file
@@ -878,7 +875,7 @@ statement.
                                    # (and UnusedClass gets defined too)
 
 **Key point**: Lazy imports defer *when* a module loads, not *what* gets loaded.
-You cannot selectively load only parts of a module—Python's import system doesn't
+You cannot selectively load only parts of a module -- Python's import system doesn't
 support partial module execution.
 
 **Q: What about type annotations and** ``TYPE_CHECKING`` **imports?**
@@ -930,7 +927,7 @@ A: Migration is incremental:
 1. Identify slow-loading modules using profiling tools
 2. Add ``lazy`` keyword to imports that aren't needed immediately
 3. Test that side-effect timing changes don't break functionality
-4. Use ``__lazy_modules__`` for compatibility with older Python versions
+4. Use :data:`!__lazy_modules__` for compatibility with older Python versions
 
 **Q: What about star imports** (``from module import *``)?
 
@@ -959,7 +956,7 @@ module. Individual lazy objects can be resolved by calling their ``get()`` metho
 **Q: What's the difference between** ``globals()`` **and** ``mod.__dict__`` **for lazy imports?**
 
 A: Calling ``globals()`` returns the module's dictionary without reifying lazy
-imports — you'll see lazy proxy objects when accessing them through the returned
+imports -- you'll see lazy proxy objects when accessing them through the returned
 dictionary. However, accessing ``mod.__dict__`` from external code reifies all lazy
 imports in that module first. This design ensures:
 
@@ -1037,7 +1034,7 @@ with ``lazy``.
 
 **Q: What about forwards compatibility with older Python versions?**
 
-A: Use the ``__lazy_modules__`` global for compatibility:
+A: Use the :data:`!__lazy_modules__` global for compatibility:
 
 .. code-block:: python
 
@@ -1046,15 +1043,15 @@ A: Use the ``__lazy_modules__`` global for compatibility:
   import expensive_module
   from expensive_module_2 import MyClass
 
-The ``__lazy_modules__`` attribute is a list of module name strings. When an import
+The :data:`!__lazy_modules__` attribute is a list of module name strings. When an import
 statement is executed, Python checks if the module name being imported appears in
-``__lazy_modules__``. If it does, the import is treated as if it had the ``lazy``
+:data:`!__lazy_modules__`. If it does, the import is treated as if it had the ``lazy``
 keyword (becoming *potentially lazy*). On Python versions before 3.15 that don't
-support lazy imports, the ``__lazy_modules__`` attribute is simply ignored and
+support lazy imports, the :data:`!__lazy_modules__` attribute is simply ignored and
 imports proceed eagerly as normal.
 
 This provides a migration path until you can rely on the ``lazy`` keyword. For
-maximum predictability, it's recommended to define ``__lazy_modules__`` once,
+maximum predictability, it's recommended to define :data:`!__lazy_modules__` once,
 before any imports. But as it is checked on each import, it can be modified between
 ``import`` statements.
 
@@ -1120,7 +1117,7 @@ accesses the other during import time, you'll still get an error.
       def get_by_user(username):
           return f"Posts by {username}"
 
-This works because neither module accesses the other at module level—the access
+This works because neither module accesses the other at module level -- the access
 happens later when ``get_posts()`` is called.
 
 **Example that fails** (access during import):
@@ -1204,12 +1201,6 @@ A: A lazily imported module does **not** appear in ``sys.modules`` until it's re
 
 A: Not "why"... memorize! :)
 
-Reference Implementation
-========================
-
-A reference implementation is available at:
-https://github.com/LazyImportsCabal/cpython/tree/lazy
-
 Alternate Implementation Ideas
 ==============================
 
@@ -1218,15 +1209,15 @@ of this PEP. While the current proposal represents what we believe to be the bes
 of simplicity, performance, and maintainability, these alternatives offer different
 trade-offs that may be valuable for implementers to consider or for future refinements.
 
-Leveraging a Subclass of Dict
+Leveraging a subclass of dict
 -----------------------------
 
 Instead of updating the internal dict object to directly add the fields needed to support lazy imports,
 we could create a subclass of the dict object to be used specifically for Lazy Import enablement. This
 would still be a leaky abstraction though - methods can be called directly such as ``dict.__getitem__``
 and it would impact the performance of globals lookup in the interpreter.
 
-Alternate Keyword Names
+Alternate keyword names
 -----------------------
 
 For this PEP, we decided to propose ``lazy`` for the explicit keyword as it felt the most familar to those
@@ -1237,7 +1228,7 @@ options to support explicit lazy imports. The most compelling alternates were ``
 Rejected Ideas
 ==============
 
-Modification of the Dict Object
+Modification of the dict object
 -------------------------------
 
 The initial PEP for lazy imports (PEP 690) relied heavily on the modification of the internal dict
@@ -1253,29 +1244,29 @@ Adding any kind of hook or special behavior to dicts to support lazy imports wou
 1. Prevent critical interpreter optimizations including future JIT compilation
 2. Add complexity to a data structure that must remain simple and fast
 3. Affect every part of Python, not just import behavior
-4. Violate separation of concerns—the hash table shouldn't know about the import system
+4. Violate separation of concerns -- the hash table shouldn't know about the import system
 
 Past decisions that violated this principle of keeping core abstractions clean have caused
 significant pain in the CPython ecosystem, making optimization difficult and introducing
 subtle bugs.
 
-Placing the ``lazy`` Keyword in the Middle of From Imports
+Placing the ``lazy`` keyword in the middle of from imports
 ----------------------------------------------------------
 
 While we found ``from foo lazy import bar`` to be a really intuitive placement for the new explicit syntax,
 we quickly learned that placing the ``lazy`` keyword here is already syntactically allowed in Python. This
 is because ``from . lazy import bar`` is legal syntax (because whitespace
 does not matter.)
 
-Placing the ``lazy`` Keyword at the End of Import Statements
+Placing the ``lazy`` keyword at the end of import statements
 ------------------------------------------------------------
 
 We discussed appending lazy to the end of import statements like such ``import foo lazy`` or
 ``from foo import bar, baz lazy`` but ultimately decided that this approach provided less clarity.
 For example, if multiple modules are imported in a single statement, it is unclear if the lazy binding
 applies to all of the imported objects or just a subset of the items.
 
-Returning a Proxy Dict from ``globals()``
+Returning a proxy dict from ``globals()``
 ------------------------------------------
 
 An alternative to reifying on ``globals()`` or exposing lazy objects would be to
@@ -1308,13 +1299,13 @@ for several reasons:
 
 **The key distinction**: Adding a lazy import and calling ``globals()`` is the
 module author's concern and under their control. However, accessing ``mod.__dict__``
-from external code is a different scenario — it crosses module boundaries and affects
+from external code is a different scenario -- it crosses module boundaries and affects
 someone else's code. Therefore, ``mod.__dict__`` access reifies all lazy imports to
 ensure external code sees fully realized modules, while ``globals()`` preserves lazy
 objects for the module's own introspection needs.
 
 **Technical challenges**: It is impossible to safely reify on-demand when ``globals()``
-is called because we cannot return a proxy dictionary — this would break common usages
+is called because we cannot return a proxy dictionary -- this would break common usages
 like passing the result to ``exec()`` or other built-ins that expect a real dictionary.
 The only alternative would be to eagerly reify all lazy imports whenever ``globals()``
 is called, but this behavior would be surprising and potentially expensive.
@@ -1339,7 +1330,7 @@ Note that three options were considered:
 We chose the third option because it properly delineates responsibility: if you add lazy imports
 to your module and call ``globals()``, you're responsible for handling the lazy objects.
 But external code accessing your module's ``__dict__`` shouldn't need to know about your
-lazy imports—it gets fully resolved modules.
+lazy imports -- it gets fully resolved modules.
 
 Acknowledgements
 ================