Merge branch 'lazy' into lazy-future-error

Author: StanFromIreland

Doc/c-api/import.rst

@@ -353,19 +353,23 @@ Importing Modules
 
    .. versionadded:: next
 
-.. c:function:: PyObject* PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)
+.. c:function:: int PyImport_SetLazyImportsMode(PyImport_LazyImportsMode mode)
 
    Similar to :c:func:`PyImport_ImportModuleAttr`, but names are UTF-8 encoded
    strings instead of Python :class:`str` objects.
 
+   This function always returns ``0``.
+
    .. versionadded:: next
 
-.. c:function:: PyObject* PyImport_SetLazyImportsFilter(PyObject *filter)
+.. c:function:: int PyImport_SetLazyImportsFilter(PyObject *filter)
+
+   Sets the current lazy imports filter. The *filter* should be a callable that
+   will receive ``(importing_module_name, imported_module_name, [fromlist])``
+   when an import can potentially be lazy and that must return ``True`` if
+   the import should be lazy and ``False`` otherwise.
 
-   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.
+   Return ``0`` on success and ``-1`` with an exception set otherwise.
 
    .. versionadded:: next
 

Doc/library/types.rst

@@ -350,7 +350,7 @@ Standard names are defined for the following types:
    actually accessed. This type can be used to detect lazy imports
    programmatically.
 
-   .. versionadded:: 3.15
+   .. versionadded:: next
 
    .. seealso:: :pep:`810`
 

Doc/reference/lexical_analysis.rst

@@ -457,6 +457,7 @@ Some names are only reserved under specific contexts. These are known as
 
 - ``match``, ``case``, and ``_``, when used in the :keyword:`match` statement.
 - ``type``, when used in the :keyword:`type` statement.
+- ``lazy``, when used before an :keyword:`import` statement.
 
 These syntactically act as keywords in their specific contexts,
 but this distinction is done at the parser level, not when tokenizing.
@@ -468,6 +469,9 @@ identifier names.
 .. versionchanged:: 3.12
    ``type`` is now a soft keyword.
 
+.. versionchanged:: next
+   ``lazy`` is now a soft keyword.
+
 .. index::
    single: _, identifiers
    single: __, identifiers

Doc/reference/simple_stmts.rst

@@ -748,14 +748,15 @@ The :keyword:`!import` statement
    pair: name; binding
    pair: keyword; from
    pair: keyword; as
+   pair: keyword; lazy
    pair: exception; ImportError
    single: , (comma); import statement
 
 .. productionlist:: python-grammar
-   import_stmt: "import" `module` ["as" `identifier`] ("," `module` ["as" `identifier`])*
-              : | "from" `relative_module` "import" `identifier` ["as" `identifier`]
+   import_stmt: ["lazy"] "import" `module` ["as" `identifier`] ("," `module` ["as" `identifier`])*
+              : | ["lazy"] "from" `relative_module` "import" `identifier` ["as" `identifier`]
               : ("," `identifier` ["as" `identifier`])*
-              : | "from" `relative_module` "import" "(" `identifier` ["as" `identifier`]
+              : | ["lazy"] "from" `relative_module` "import" "(" `identifier` ["as" `identifier`]
               : ("," `identifier` ["as" `identifier`])* [","] ")"
               : | "from" `relative_module` "import" "*"
    module: (`identifier` ".")* `identifier`
@@ -870,6 +871,56 @@ determine dynamically the modules to be loaded.
 
 .. audit-event:: import module,filename,sys.path,sys.meta_path,sys.path_hooks import
 
+
+.. _lazy-imports:
+.. _lazy:
+
+Lazy imports
+------------
+
+.. index::
+   pair: lazy; import
+   single: lazy import
+
+The :keyword:`lazy` keyword marks an import as lazy. It is a :ref:`soft keyword
+<soft-keywords>` that only has special meaning when it appears immediately
+before an :keyword:`import` or :keyword:`from` statement.
+
+When an import statement is preceded by the :keyword:`lazy` keyword,
+the import becomes *lazy*: the module is not loaded immediately at the import
+statement. Instead, a lazy proxy object is created and bound to the name. The
+actual module is loaded on first use of that name.
+
+Lazy imports are only permitted at module scope. Using ``lazy`` inside a
+function, class body, or :keyword:`try`/:keyword:`except`/:keyword:`finally`
+block raises a :exc:`SyntaxError`. Star imports cannot be lazy (``lazy from
+module import *`` is a syntax error), and :ref:`future statements <future>`
+cannot be lazy.
+
+When using ``lazy from ... import``, each imported name is bound to a lazy
+proxy object. The first access to any of these names triggers loading of the
+entire module and resolves only that specific name to its actual value. Other
+names remain as lazy proxies until they are accessed.
+
+Example::
+
+   lazy import json
+
+   print('json' in sys.modules)  # False - module not loaded yet
+
+   # First use triggers loading
+   result = json.dumps({"hello": "world"})
+
+   print('json' in sys.modules)  # True - now loaded
+
+If an error occurs during module loading (such as :exc:`ImportError` or
+:exc:`SyntaxError`), it is raised at the point where the lazy import is first
+used, not at the import statement itself.
+
+See :pep:`810` for the full specification of lazy imports.
+
+.. versionadded:: next
+
 .. _future:
 
 Future statements

Doc/using/cmdline.rst

@@ -700,7 +700,7 @@ Miscellaneous options
      (the default) respects the ``lazy`` keyword in source code.
      See also :envvar:`PYTHON_LAZY_IMPORTS`.
 
-     .. versionadded:: 3.15
+     .. versionadded:: next
 
    It also allows passing arbitrary values and retrieving them through the
    :data:`sys._xoptions` dictionary.
@@ -1356,7 +1356,7 @@ conflict.
 
    See also the :option:`-X lazy_imports <-X>` command-line option.
 
-   .. versionadded:: 3.15
+   .. versionadded:: next
 
 Debug-mode variables
 ~~~~~~~~~~~~~~~~~~~~

Doc/whatsnew/3.15.rst

@@ -139,15 +139,17 @@ 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:
+receives three arguments: the importing module's name (or ``None``), the imported
+module's name, and the fromlist (or ``None`` for regular imports). It should
+return ``True`` to allow the import to be lazy, or ``False`` to force eager loading.
+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_filter(lambda importing, imported, fromlist: imported.startswith("myapp."))
    sys.set_lazy_imports("all")
 
    import myapp.slow_module  # lazy (matches filter)

Include/import.h

@@ -88,7 +88,7 @@ PyAPI_FUNC(int) PyImport_AppendInittab(
     PyObject* (*initfunc)(void)
     );
 
-typedef enum  {
+typedef enum {
     PyImport_LAZY_NORMAL,
     PyImport_LAZY_ALL,
     PyImport_LAZY_NONE,

Include/internal/pycore_magic_number.h

@@ -287,7 +287,7 @@ Known values:
     Python 3.15a1 3654 (Fix missing exception handlers in logical expression)
     Python 3.15a1 3655 (Fix miscompilation of some module-level annotations)
     Python 3.15a1 3656 (Add TRACE_RECORD instruction, for platforms with switch based interpreter)
-    Python 3.15a1 3657 Lazy imports IMPORT_NAME opcode changes
+    Python 3.15a3 3657 (Lazy imports IMPORT_NAME opcode changes)
 
 
     Python 3.16 will start with 3700

Lib/rlcompleter.py

@@ -192,7 +192,7 @@ def attr_matches(self, text):
 
                     if (isinstance(thisobject, types.ModuleType)
                         and
-                        isinstance(thisobject.__dict__.get(word),types.LazyImportType)
+                        isinstance(thisobject.__dict__.get(word), types.LazyImportType)
                     ):
                         value = thisobject.__dict__.get(word)
                     else: