gh-142349: Implement PEP 810 - Explicit lazy imports

Doc/c-api/import.rst

@@ -341,6 +341,43 @@ Importing Modules
 
    .. versionadded:: 3.14
 
+.. c:function:: PyImport_LazyImportsMode PyImport_GetLazyImportsMode()
+
+   Gets the current lazy imports mode.
+
+   .. versionadded:: 3.15
+
+.. c:function:: PyObject* PyImport_GetLazyImportsFilter()
+
+   Gets the current lazy imports filter. Returns a new reference.
+
+   .. versionadded:: 3.15
+
+.. c:function:: PyObject* PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)
+
+   Similar to :c:func:`PyImport_ImportModuleAttr`, but names are UTF-8 encoded
+   strings instead of Python :class:`str` objects.
+
+   .. versionadded:: 3.15
+
+.. c:function:: PyObject* PyImport_SetLazyImportsFilter(PyObject *filter)
+
+   Sets the current lazy imports filter. The function should be a callable that
+   will receive (importing_module_name, imported_module_name, [fromlist]) when
+   an import can potentially be lazy. Returns True if the import should be lazy
+   or False otherwise.
+
+   .. versionadded:: 3.15
+
+.. c:type:: PyImport_LazyImportsMode
+
+   Enumeration of possible lazy import modes:
+   - ``PyImport_LAZY_NORMAL``
+   - ``PyImport_LAZY_ALL``
+   - ``PyImport_LAZY_NONE``
+
+   .. versionadded:: 3.12
+
 .. c:function:: PyObject* PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject* (*initfunc)(void))
 
    This function is a building block that enables embedders to implement

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
@@ -1719,6 +1756,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 @@
 
 .. 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 @@
 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

Grammar/python.gram

@@ -121,9 +121,9 @@ simple_stmts[asdl_stmt_seq*]:
 simple_stmt[stmt_ty] (memo):
     | assignment
     | &"type" type_alias
+    | &('import' | 'from' | "lazy" ) import_stmt
     | e=star_expressions { _PyAST_Expr(e, EXTRA) }
     | &'return' return_stmt
-    | &('import' | 'from') import_stmt
     | &'raise' raise_stmt
     | &'pass' pass_stmt
     | &'del' del_stmt
@@ -216,21 +216,23 @@ assert_stmt[stmt_ty]:
     | invalid_assert_stmt
     | 'assert' a=expression b=[',' z=expression { z }] { _PyAST_Assert(a, b, EXTRA) }
 
-import_stmt[stmt_ty]:
+import_stmt[stmt_ty](memo):
     | invalid_import
     | import_name
     | import_from
 
 # Import statements
 # -----------------
 
-import_name[stmt_ty]: 'import' a=dotted_as_names { _PyAST_Import(a, EXTRA) }
+import_name[stmt_ty]:
+    | lazy="lazy"? 'import' a=dotted_as_names { _PyAST_Import(a, lazy ? 1 : 0, EXTRA) }
+
 # note below: the ('.' | '...') is necessary because '...' is tokenized as ELLIPSIS
 import_from[stmt_ty]:
-    | 'from' a=('.' | '...')* b=dotted_name 'import' c=import_from_targets {
-        _PyPegen_checked_future_import(p, b->v.Name.id, c, _PyPegen_seq_count_dots(a), EXTRA) }
-    | 'from' a=('.' | '...')+ 'import' b=import_from_targets {
-        _PyAST_ImportFrom(NULL, b, _PyPegen_seq_count_dots(a), EXTRA) }
+    | lazy="lazy"? 'from' a=('.' | '...')* b=dotted_name 'import' c=import_from_targets {
+        _PyPegen_checked_future_import(p, b->v.Name.id, c, _PyPegen_seq_count_dots(a), lazy ? 1 : 0, EXTRA) }
+    | lazy="lazy"? 'from' a=('.' | '...')+ 'import' b=import_from_targets {
+        _PyAST_ImportFrom(NULL, b, _PyPegen_seq_count_dots(a), lazy ? 1 : 0, EXTRA) }
 import_from_targets[asdl_alias_seq*]:
     | '(' a=import_from_as_names [','] ')' { a }
     | import_from_as_names !','

Include/cpython/initconfig.h

@@ -190,6 +190,7 @@ typedef struct PyConfig {
     int enable_gil;
     int tlbc_enabled;
 #endif
+    int lazy_imports;
 
     /* --- Path configuration inputs ------------ */
     int pathconfig_warnings;

Include/import.h

@@ -88,6 +88,18 @@ PyAPI_FUNC(int) PyImport_AppendInittab(
     PyObject* (*initfunc)(void)
     );
 
+typedef enum  {
+    PyImport_LAZY_NORMAL,
+    PyImport_LAZY_ALL,
+    PyImport_LAZY_NONE,
+} PyImport_LazyImportsMode;
+
+PyAPI_FUNC(int) PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode);
+PyAPI_FUNC(int) PyImport_SetLazyImportsFilter(PyObject *filter);
+
+PyAPI_FUNC(PyImport_LazyImportsMode) PyImport_GetLazyImportsMode(void);
+PyAPI_FUNC(PyObject *) PyImport_GetLazyImportsFilter(void);
+
 #ifndef Py_LIMITED_API
 #  define Py_CPYTHON_IMPORT_H
 #  include "cpython/import.h"

Include/internal/pycore_ceval.h

@@ -311,7 +311,14 @@ PyAPI_FUNC(void) _PyEval_FormatExcCheckArg(PyThreadState *tstate, PyObject *exc,
 PyAPI_FUNC(void) _PyEval_FormatExcUnbound(PyThreadState *tstate, PyCodeObject *co, int oparg);
 PyAPI_FUNC(void) _PyEval_FormatKwargsError(PyThreadState *tstate, PyObject *func, PyObject *kwargs);
 PyAPI_FUNC(PyObject *) _PyEval_ImportFrom(PyThreadState *, PyObject *, PyObject *);
-PyAPI_FUNC(PyObject *) _PyEval_ImportName(PyThreadState *, _PyInterpreterFrame *, PyObject *, PyObject *, PyObject *);
+PyAPI_FUNC(PyObject *) _PyEval_LazyImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals,
+            PyObject *locals, PyObject *name, PyObject *fromlist, PyObject *level, int lazy);
+PyAPI_FUNC(PyObject *) _PyEval_LazyImportFrom(PyThreadState *tstate, PyObject *v, PyObject *name);
+PyAPI_FUNC(PyObject *) _PyEval_ImportName(PyThreadState *tstate, PyObject *builtins, PyObject *globals, PyObject *locals,
+            PyObject *name, PyObject *fromlist, PyObject *level);
+PyObject *
+_PyEval_ImportNameWithImport(PyThreadState *tstate, PyObject *import_func, PyObject *globals, PyObject *locals,
+                             PyObject *name, PyObject *fromlist, PyObject *level);
 PyAPI_FUNC(PyObject *)_PyEval_MatchClass(PyThreadState *tstate, PyObject *subject, PyObject *type, Py_ssize_t nargs, PyObject *kwargs);
 PyAPI_FUNC(PyObject *)_PyEval_MatchKeys(PyThreadState *tstate, PyObject *map, PyObject *keys);
 PyAPI_FUNC(void) _PyEval_MonitorRaise(PyThreadState *tstate, _PyInterpreterFrame *frame, _Py_CODEUNIT *instr);

Include/internal/pycore_compile.h

@@ -131,6 +131,7 @@ int _PyCompile_PushFBlock(struct _PyCompiler *c, _Py_SourceLocation loc,
 void _PyCompile_PopFBlock(struct _PyCompiler *c, enum _PyCompile_FBlockType t,
                           _PyJumpTargetLabel block_label);
 _PyCompile_FBlockInfo *_PyCompile_TopFBlock(struct _PyCompiler *c);
+bool _PyCompile_InExceptionHandler(struct _PyCompiler *c);
 
 int _PyCompile_EnterScope(struct _PyCompiler *c, identifier name, int scope_type,
                           void *key, int lineno, PyObject *private,