Implement more of PEP 810

Author: pablogsal

Doc/library/sys.rst

@@ -911,6 +911,43 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. versionadded:: 3.11
 
+
+.. function:: get_lazy_imports()
+
+   Returns the current lazy imports mode as a string.
+
+   * ``"normal"``: Only imports explicitly marked with the ``lazy`` keyword are lazy
+   * ``"all"``: All top-level imports are potentially lazy
+   * ``"none"``: All lazy imports are suppressed (even explicitly marked ones)
+
+   See also :func:`set_lazy_imports` and :pep:`810`.
+
+   .. versionadded:: 3.15
+
+
+.. function:: get_lazy_imports_filter()
+
+   Returns the current lazy imports filter function, or ``None`` if no filter
+   is set.
+
+   The filter function is called for every potentially lazy import to determine
+   whether it should actually be lazy. See :func:`set_lazy_imports_filter` for
+   details on the filter function signature.
+
+   .. versionadded:: 3.15
+
+
+.. function:: get_lazy_modules()
+
+   Returns a set of fully-qualified module names that have been lazily imported.
+   This is primarily useful for diagnostics and introspection.
+
+   Note that modules are removed from this set when they are reified (actually
+   loaded on first use).
+
+   .. versionadded:: 3.15
+
+
 .. function:: getrefcount(object)
 
    Return the reference count of the *object*.  The count returned is generally one
@@ -1715,6 +1752,57 @@ always available. Unless explicitly noted otherwise, all variables are read-only
 
    .. versionadded:: 3.11
 
+
+.. function:: set_lazy_imports(mode)
+
+   Sets the global lazy imports mode. The *mode* parameter must be one of the
+   following strings:
+
+   * ``"normal"``: Only imports explicitly marked with the ``lazy`` keyword are lazy
+   * ``"all"``: All top-level imports become potentially lazy
+   * ``"none"``: All lazy imports are suppressed (even explicitly marked ones)
+
+   This function is intended for advanced users who need to control lazy imports
+   across their entire application. Library developers should generally not use
+   this function as it affects the runtime execution of applications.
+
+   In addition to the mode, lazy imports can be controlled via the filter
+   provided by :func:`set_lazy_imports_filter`.
+
+   See also :func:`get_lazy_imports` and :pep:`810`.
+
+   .. versionadded:: 3.15
+
+
+.. function:: set_lazy_imports_filter(filter)
+
+   Sets the lazy imports filter callback. The *filter* parameter must be a
+   callable or ``None`` to clear the filter.
+
+   The filter function is called for every potentially lazy import to determine
+   whether it should actually be lazy. It must have the following signature::
+
+      def filter(importing_module: str, imported_module: str,
+                 fromlist: tuple[str, ...] | None) -> bool
+
+   Where:
+
+   * *importing_module* is the name of the module doing the import
+   * *imported_module* is the name of the module being imported
+   * *fromlist* is the tuple of names being imported (for ``from ... import``
+     statements), or ``None`` for regular imports
+
+   The filter should return ``True`` to allow the import to be lazy, or
+   ``False`` to force an eager import.
+
+   This is an advanced feature intended for specialized users who need
+   fine-grained control over lazy import behavior.
+
+   See also :func:`get_lazy_imports_filter` and :pep:`810`.
+
+   .. versionadded:: 3.15
+
+
 .. function:: setprofile(profilefunc)
 
    .. index::

Doc/whatsnew/3.15.rst

@@ -65,6 +65,8 @@ Summary -- Release highlights
 
 .. PEP-sized items next.
 
+* :pep:`810`: :ref:`Explicit lazy imports for faster startup times
+  <whatsnew315-pep810>`
 * :pep:`799`: :ref:`A dedicated profiling package for organizing Python
   profiling tools <whatsnew315-sampling-profiler>`
 * :pep:`686`: :ref:`Python now uses UTF-8 as the default encoding
@@ -77,6 +79,97 @@ Summary -- Release highlights
 New features
 ============
 
+.. _whatsnew315-pep810:
+
+:pep:`810`: Explicit lazy imports
+---------------------------------
+
+Large Python applications often suffer from slow startup times. A significant
+contributor to this problem is the import system: when a module is imported,
+Python must locate the file, read it from disk, compile it to bytecode, and
+execute all top-level code. For applications with deep dependency trees, this
+process can take seconds, even when most of the imported code is never actually
+used during a particular run.
+
+Developers have worked around this by moving imports inside functions, using
+``importlib`` to load modules on demand, or restructuring code to avoid
+unnecessary dependencies. These approaches work but make code harder to read
+and maintain, scatter import statements throughout the codebase, and require
+discipline to apply consistently.
+
+Python now provides a cleaner solution through explicit lazy imports using the
+new ``lazy`` soft keyword. When you mark an import as lazy, Python defers the
+actual module loading until the imported name is first used. This gives you
+the organizational benefits of declaring all imports at the top of the file
+while only paying the loading cost for modules you actually use.
+
+The ``lazy`` keyword works with both ``import`` and ``from ... import`` statements.
+When you write ``lazy import heavy_module``, Python does not immediately load the
+module. Instead, it creates a lightweight proxy object. The actual module loading
+happens transparently when you first access the name:
+
+.. code-block:: python
+
+   lazy import json
+   lazy from datetime import datetime
+
+   print("Starting up...")  # json and datetime not loaded yet
+
+   data = json.loads('{"key": "value"}')  # json loads here
+   now = datetime()  # datetime loads here
+
+This mechanism is particularly useful for applications that import many modules
+at the top level but may only use a subset of them in any given run. The deferred
+loading reduces startup latency without requiring code restructuring or conditional
+imports scattered throughout the codebase.
+
+When a lazy import eventually fails (for example, if the module does not exist),
+Python raises the exception at the point of first use rather than at import time.
+The traceback includes both the location where the name was accessed and the
+original import statement, making it straightforward to diagnose the problem.
+
+For cases where you want to enable lazy loading globally without modifying source
+code, Python provides the :option:`-X lazy_imports <-X>` command-line option and
+the :envvar:`PYTHON_LAZY_IMPORTS` environment variable. Both accept three values:
+``all`` makes all imports lazy by default, ``none`` disables lazy imports entirely
+(even explicit ``lazy`` statements become eager), and ``normal`` (the default)
+respects the ``lazy`` keyword in source code. The :func:`sys.set_lazy_imports` and
+:func:`sys.get_lazy_imports` functions allow changing and querying this mode at
+runtime.
+
+For more selective control, :func:`sys.set_lazy_imports_filter` accepts a callable
+that determines whether a specific module should be loaded lazily. The filter
+receives the fully-qualified module name and returns a boolean. This allows
+patterns like making only your own application's modules lazy while keeping
+third-party dependencies eager:
+
+.. code-block:: python
+
+   import sys
+
+   sys.set_lazy_imports_filter(lambda name: name.startswith("myapp."))
+   sys.set_lazy_imports("all")
+
+   import myapp.slow_module  # lazy (matches filter)
+   import json               # eager (does not match filter)
+
+For debugging and introspection, :func:`sys.get_lazy_modules` returns a set
+containing the names of all modules that have been lazily imported but not yet
+loaded. The proxy type itself is available as :data:`types.LazyImportType` for
+code that needs to detect lazy imports programmatically.
+
+There are some restrictions on where ``lazy`` can appear. Lazy imports are only
+permitted at module scope; using ``lazy`` inside a function, class body, or
+``try``/``except``/``finally`` block raises a :exc:`SyntaxError`. Star imports
+cannot be lazy (``lazy from module import *`` is a syntax error), and future
+imports cannot be lazy either (``lazy from __future__ import ...`` raises
+:exc:`SyntaxError`).
+
+.. seealso:: :pep:`810` for the full specification and rationale.
+
+(Contributed by Pablo Galindo Salgado and Dino Viehland.)
+
+
 .. _whatsnew315-sampling-profiler:
 
 :pep:`799`: High frequency statistical sampling profiler

Include/internal/pycore_interp_structs.h

@@ -318,6 +318,7 @@ struct _import_state {
     PyObject *lazy_imports_filter;
     PyObject *lazy_importing_modules;
     PyObject *lazy_modules;
+    PyObject *lazy_modules_set;  /* Set of fully-qualified module names lazily imported (PEP 810) */
     /* The global import lock. */
     _PyRecursiveMutex lock;
     /* diagnostic info in PyImport_ImportModuleLevelObject() */