From a830c62b8c3bd71fcbf940daa469b04a96600c3b Mon Sep 17 00:00:00 2001 From: Pablo Galindo Salgado Date: Sat, 21 Nov 2026 13:22:43 +0000 Subject: [PATCH] gh-142349: Fill gaps in lazy import documentation --- Doc/builtins/functions.rst | 19 ++-- Doc/c-api/import.rst | 19 ++-- Doc/c-api/init_config.rst | 8 +- Doc/glossary.rst | 5 + Doc/library/ast.rst | 20 +++- Doc/library/dis.rst | 26 ++++- Doc/library/importlib.rst | 8 ++ Doc/library/sys.rst | 29 ++++-- Doc/library/types.rst | 25 ++++- Doc/reference/datamodel.rst | 5 + Doc/reference/import.rst | 17 +++- Doc/reference/lexical_analysis.rst | 3 +- Doc/reference/simple_stmts.rst | 70 ++++++++++++-- Doc/tutorial/modules.rst | 15 ++- Doc/using/cmdline.rst | 16 ++-- Doc/whatsnew/3.15.rst | 6 +- Lib/pydoc_data/topics.py | 149 +++++++++++++++++++++++++---- Python/clinic/sysmodule.c.h | 31 +++--- Python/sysmodule.c | 35 +++---- 19 files changed, 396 insertions(+), 110 deletions(-) diff --git a/Doc/builtins/functions.rst b/Doc/builtins/functions.rst index 8186eae56626219..01ac05794783001 100644 --- a/Doc/builtins/functions.rst +++ b/Doc/builtins/functions.rst @@ -2416,14 +2416,17 @@ are always available. They are listed here in alphabetical order. This is an advanced function that is not needed in everyday Python programming, unlike :func:`importlib.import_module`. - This function is invoked by the :keyword:`import` statement. It can be - replaced (by importing the :mod:`builtins` module and assigning to - ``builtins.__import__``) in order to change semantics of the - :keyword:`!import` statement, but doing so is **strongly** discouraged as it - is usually simpler to use import hooks (see :pep:`302`) to attain the same - goals and does not cause issues with code which assumes the default import - implementation is in use. Direct use of :func:`__import__` is also - discouraged in favor of :func:`importlib.import_module`. + Eager :keyword:`import` statements call this function. + For :ref:`lazy imports `, Python calls this function at + resolution. + + You can replace :func:`__import__` through an assignment to + ``builtins.__import__``. Import hooks (see :pep:`302`) usually provide a + simpler way to customize imports. A replacement can cause problems for code + that expects the default import implementation. + Do not replace :func:`__import__` unless import hooks cannot supply the + required behavior. + To import a module by name, use :func:`importlib.import_module`. The function imports the module *name*, potentially using the given *globals* and *locals* to determine how to interpret the name in a package context. diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 11e795a8016a3c6..319b828f27ab39e 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -371,12 +371,13 @@ Importing Modules .. 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. The ``imported_module_name`` value - is the resolved module name, so ``lazy from .spam import eggs`` passes - ``package.spam``. The callable must return ``True`` if the import should be - lazy and ``False`` otherwise. + Set the lazy import filter for the current interpreter. + The *filter* must be a callable, ``NULL``, or :c:data:`Py_None`. + Use ``NULL`` or :c:data:`Py_None` to clear the filter. + The callable receives three positional arguments: + ``(importing_module_name, imported_module_name, fromlist)``. + See :func:`sys.set_lazy_imports_filter` for the arguments and filter + behavior. Return ``0`` on success and ``-1`` with an exception set otherwise. @@ -388,11 +389,13 @@ Importing Modules .. c:enumerator:: PyImport_LAZY_NORMAL - Respect the ``lazy`` keyword in source code. This is the default mode. + Respect :keyword:`lazy` and :attr:`module.__lazy_modules__`. + This is the default mode. .. c:enumerator:: PyImport_LAZY_ALL - Make all imports lazy by default. + Make eligible module-scope imports lazy by default. + See the :ref:`lazy import restrictions `. .. versionadded:: 3.15 diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index cc96ba67c4e85be..e877fabd1c8a677 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -1607,9 +1607,11 @@ PyConfig Control :ref:`lazy imports `. - A value of ``-1`` keeps the default behaviour, where only imports marked - with the ``lazy`` keyword are lazy. A value of ``1`` makes every import - lazy. ``0`` is rejected. + A value of ``-1`` selects the default behavior, which respects + :keyword:`lazy` and :attr:`module.__lazy_modules__`. + A value of ``1`` makes eligible module-scope imports lazy by default. + The :ref:`lazy import restrictions ` apply in both modes. + A value of ``0`` is invalid. Configured by the :option:`-X lazy_imports <-X>` command line option or the :envvar:`PYTHON_LAZY_IMPORTS` environment variable. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index f0934dc2e138771..8062d2b916dd06e 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -929,6 +929,11 @@ Glossary which is evaluated when the function is called. The syntax to create a lambda function is ``lambda [parameters]: expression`` + lazy import + An import that delays module search and execution until the first use + of the imported name. A proxy represents the imported object until + resolution. See :ref:`lazy-imports`. + LBYL Look before you leap. This coding style explicitly tests for pre-conditions before making calls or lookups. This style contrasts with diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index d3456a486e76df4..388102f273d9ee3 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -1128,9 +1128,11 @@ described in other sections. Imports ~~~~~~~ -.. class:: Import(names) +.. class:: Import(names, is_lazy) An import statement. ``names`` is a list of :class:`alias` nodes. + ``is_lazy`` is ``1`` for ``lazy import`` and ``0`` for ``import``. + The field records the source syntax and does not reflect runtime controls. .. doctest:: @@ -1145,12 +1147,22 @@ Imports is_lazy=0)]) -.. class:: ImportFrom(module, names, level) + .. versionchanged:: 3.15 + Added ``is_lazy`` for :ref:`lazy imports `. + + +.. class:: ImportFrom(module, names, level, is_lazy) Represents ``from x import y``. ``module`` is a raw string of the 'from' name, without any leading dots, or ``None`` for statements such as ``from . import foo``. ``level`` is an integer holding the level of the relative import (0 means absolute import). + ``is_lazy`` is ``1`` for ``lazy from ... import`` and ``0`` for + ``from ... import``. + + The ``is_lazy`` field records the source syntax. It does not reflect + runtime controls such as :func:`sys.set_lazy_imports` or + :attr:`module.__lazy_modules__`. .. doctest:: @@ -1167,6 +1179,10 @@ Imports is_lazy=0)]) + .. versionchanged:: 3.15 + Added ``is_lazy`` for :ref:`lazy imports `. + + .. class:: alias(name, asname) Both parameters are raw strings of the names. ``asname`` can be ``None`` if diff --git a/Doc/library/dis.rst b/Doc/library/dis.rst index 1b5f0c92faf02c7..0a579e666d83a16 100644 --- a/Doc/library/dis.rst +++ b/Doc/library/dis.rst @@ -1362,10 +1362,22 @@ iterations of the loop. .. opcode:: IMPORT_NAME (namei) - Imports the module ``co_names[namei]``. ``STACK[-1]`` and ``STACK[-2]`` are - popped and provide the *fromlist* and *level* arguments of :func:`__import__`. - The module object is pushed onto the stack. The current namespace is not affected: for a proper import statement, a subsequent :opcode:`STORE_FAST` instruction - modifies the namespace. + Imports the module ``co_names[namei >> 2]``. ``STACK[-1]`` and + ``STACK[-2]`` supply the *fromlist* and *level* arguments of the import. + The instruction removes both values from the stack. + The result is a module object or a + :class:`lazy import proxy `. + The instruction pushes the result onto the stack. + + The instruction does not change the current namespace. + For ``import spam``, a subsequent store instruction binds the result. + + The two lowest bits of *namei* control :ref:`lazy imports `. + Bit ``0`` marks an explicit lazy import. Bit ``1`` forces an eager import. + If both bits are zero, the runtime lazy import controls apply. + + .. versionchanged:: 3.15 + The two lowest bits encode lazy import flags. .. opcode:: IMPORT_FROM (namei) @@ -1374,6 +1386,12 @@ iterations of the loop. The resulting object is pushed onto the stack, to be subsequently stored by a :opcode:`STORE_FAST` instruction. + For a :class:`lazy import proxy `, the result can + be another proxy that represents the requested attribute. + + .. versionchanged:: 3.15 + Added support for lazy import proxies. + .. opcode:: JUMP_FORWARD (delta) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index acccc9da416827f..4db800b05bfa11a 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1467,6 +1467,14 @@ To import a Python source file directly from a path, use the following recipe:: Implementing lazy imports ''''''''''''''''''''''''' +Python 3.15 adds :ref:`lazy imports ` through the +:keyword:`lazy` keyword. This language feature delays the module search +and execution until the first use of the imported name. + +The :class:`importlib.util.LazyLoader` example below does the module search +immediately and delays only module execution. It creates a module object in +:data:`sys.modules` before execution. + The example below shows how to implement lazy imports:: >>> import importlib.util diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index c3485204fb8b4b9..48424381ac50034 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -950,9 +950,9 @@ always available. Unless explicitly noted otherwise, all variables are read-only 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 + * ``"normal"``: Respect :keyword:`lazy` and + :attr:`module.__lazy_modules__`. This is the default mode. + * ``"all"``: Make all eligible module-scope imports potentially lazy. See also :func:`set_lazy_imports` and :pep:`810`. @@ -1829,12 +1829,16 @@ always available. Unless explicitly noted otherwise, all variables are read-only .. function:: set_lazy_imports(mode) - Sets the global lazy imports mode. The *mode* parameter must be one of - the following strings: + Set the lazy import mode for the current interpreter. + The *mode* parameter must be one of these strings: - * ``"normal"``: Only imports explicitly marked with the ``lazy`` keyword - are lazy - * ``"all"``: All top-level imports become potentially lazy + * ``"normal"``: Respect :keyword:`lazy` and + :attr:`module.__lazy_modules__`. This is the default mode. + * ``"all"``: Make all eligible module-scope imports potentially lazy. + + The :ref:`lazy import restrictions ` also apply in + ``"all"`` mode. A mode change applies to subsequent import statements. + It does not resolve lazy import proxies from earlier statements. This function is intended for advanced users who need to control lazy imports across their entire application. Library developers should @@ -1858,12 +1862,13 @@ always available. Unless explicitly noted otherwise, all variables are read-only determine whether it should actually be lazy. It should have the following signature:: - def filter(importing_module: str, imported_module: str, + def filter(importing_module: str | None, imported_module: str, fromlist: tuple[str, ...] | None) -> bool The function is called with three positional arguments: - * *importing_module* is the name of the module doing the import + * *importing_module* is the name of the module that executes the import, + or ``None`` if its globals do not contain ``__name__`` * *imported_module* is the resolved name of the module being imported (for example, ``lazy from .spam import eggs`` passes ``package.spam``) @@ -1873,6 +1878,10 @@ always available. Unless explicitly noted otherwise, all variables are read-only The filter should return ``True`` to allow the import to be lazy, or ``False`` to force an eager import. + The filter runs when the import statement executes, before proxy creation. + If the filter raises an exception, the exception propagates from that + statement. The filter cannot make an otherwise eager import lazy. + This is an advanced feature intended for specialized users who need fine-grained control over lazy import behavior. diff --git a/Doc/library/types.rst b/Doc/library/types.rst index 7a6e7aa3fae6a57..cd7c2605fc6b610 100644 --- a/Doc/library/types.rst +++ b/Doc/library/types.rst @@ -345,10 +345,20 @@ Standard names are defined for the following types: .. class:: LazyImportType - The type of lazy import proxy objects. These objects are created when a - module is lazily imported and serve as placeholders until the module is - actually accessed. This type can be used to detect lazy imports - programmatically. + The type of :ref:`lazy import proxies `. + A proxy represents a module or an imported attribute until resolution. + You cannot create instances of this type directly. + + A direct read of an imported global name resolves its proxy. + Access through :func:`globals` or + :attr:`module.__dict__` returns the proxy itself:: + + import types + lazy import json + + isinstance(globals()["json"], types.LazyImportType) # True + json.dumps({"key": "value"}) # Resolves the import. + isinstance(globals()["json"], types.LazyImportType) # False .. versionadded:: 3.15 @@ -356,7 +366,12 @@ Standard names are defined for the following types: .. method:: resolve() - Reify the lazy import and return the "real" object being imported. + Resolve the lazy import and return the imported module or attribute. + This method can leave the proxy in its namespace. + To replace the proxy explicitly, assign the result to the imported name:: + + lazy import json + json = globals()["json"].resolve() .. class:: GetSetDescriptorType diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index 02663ed465f424e..aa8f6dcdf635e8e 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1158,6 +1158,11 @@ Module objects also have the following special read-only attribute: listed here, :attr:`!__dict__` cannot be accessed as a global variable from within a module; it can only be accessed as an attribute on module objects. + Dictionary access does not resolve :ref:`lazy import proxies `. + This also applies to the dictionary that :func:`globals` returns. + See :class:`types.LazyImportType` for proxy detection and explicit + resolution. + .. impl-detail:: Because of the way CPython clears module dictionaries, the module diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst index 2ff88cb6b1fed54..10a7f24bd21376a 100644 --- a/Doc/reference/import.rst +++ b/Doc/reference/import.rst @@ -13,9 +13,9 @@ the most common way of invoking the import machinery, but it is not the only way. Functions such as :func:`importlib.import_module` and built-in :func:`__import__` can also be used to invoke the import machinery. -The :keyword:`import` statement combines two operations; it searches for the -named module, then it binds the results of that search to a name in the local -scope. The search operation of the :keyword:`!import` statement is defined as +An eager :keyword:`import` statement performs two operations. +It searches for the named module, then binds the result to a name in the local +scope. The search operation of the :keyword:`!import` statement is defined as a call to the :func:`__import__` function, with the appropriate arguments. The return value of :func:`__import__` is used to perform the name binding operation of the :keyword:`!import` statement. See the @@ -28,8 +28,8 @@ such as the importing of parent packages, and the updating of various caches (including :data:`sys.modules`), only the :keyword:`import` statement performs a name binding operation. -When an :keyword:`import` statement is executed, the standard builtin -:func:`__import__` function is called. Other mechanisms for invoking the +When an eager :keyword:`import` statement executes, Python calls the standard +built-in :func:`__import__` function. Other mechanisms for invoking the import system (such as :func:`importlib.import_module`) may choose to bypass :func:`__import__` and use their own solutions to implement import semantics. @@ -46,6 +46,13 @@ described in the sections below. import system is exposed through :data:`sys.meta_path`. In addition, native namespace package support has been implemented (see :pep:`420`). +With :ref:`lazy imports `, an import statement can bind a proxy +before the module search and execution occur. The first use of the imported +name resolves the proxy through the import system. +The sections below describe the module search and execution at that point. +Direct calls to :func:`__import__` and :func:`importlib.import_module` +remain eager in both lazy import modes. + :mod:`importlib` ================ diff --git a/Doc/reference/lexical_analysis.rst b/Doc/reference/lexical_analysis.rst index 6f7f352db3c4383..48268c043852d42 100644 --- a/Doc/reference/lexical_analysis.rst +++ b/Doc/reference/lexical_analysis.rst @@ -457,7 +457,8 @@ 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. +- ``lazy``, when used before :keyword:`import` or :keyword:`from` in a + :ref:`lazy import ` statement. These syntactically act as keywords in their specific contexts, but this distinction is done at the parser level, not when tokenizing. diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst index a964b43ebee1746..d0a6df28cae4130 100644 --- a/Doc/reference/simple_stmts.rst +++ b/Doc/reference/simple_stmts.rst @@ -893,13 +893,16 @@ Lazy imports are only permitted at module scope. Using :keyword:`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 ` cannot be -lazy. +*`` is a syntax error). Explicit :keyword:`lazy` syntax is also invalid for +:ref:`future statements `. -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. +With ``lazy from ... import``, each imported name can have its own proxy. +If the module is already initialized, Python can bind an attribute without +a proxy. +Otherwise, the first access loads the module and resolves the requested name. +Other names remain unresolved until access. +If a name refers to a submodule, access loads that submodule and its +dependencies. Example:: @@ -917,10 +920,65 @@ 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. +The sections below describe name resolution and runtime controls. See :pep:`810` for the full specification of lazy imports. .. versionadded:: 3.15 +Resolution and side effects +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Python resolves a proxy when code reads the imported name or accesses that +name as a module attribute. After resolution, Python replaces the proxy if +the namespace permits writes and the entry still contains that proxy. + +Direct access through :func:`globals` or a module's :attr:`~module.__dict__` +returns the proxy without resolution. The same applies to dictionary +iteration. :func:`dir` lists the names of a module and does not resolve +its lazy imports. +Use :class:`types.LazyImportType` to identify a proxy. +Its :meth:`~types.LazyImportType.resolve` method returns the imported object. + +The module search occurs at resolution time. Changes to :data:`sys.path` +or import hooks before resolution can change which module Python imports. +Direct calls to :func:`__import__` and :func:`importlib.import_module` +are eager. + +Module code executes when resolution loads the module. +Side effects, such as plugin registration, occur at that time. +If a program needs these side effects before the first use of an imported +name, use an eager import. +In the default ``"normal"`` mode, omit :keyword:`lazy` and exclude the module +from :attr:`~module.__lazy_modules__`. + +An import failure leaves the proxy available for a later attempt. +If resolution recursively accesses the same unresolved proxy, Python raises +:exc:`ImportCycleError`. + +Runtime controls +^^^^^^^^^^^^^^^^ + +The default ``"normal"`` mode respects explicit :keyword:`lazy` statements +and :attr:`~module.__lazy_modules__`. +The ``"all"`` mode also makes other eligible module-scope imports lazy. +Imports inside functions, class bodies, and +:keyword:`try`/:keyword:`except`/:keyword:`finally` blocks remain eager. +Star imports also remain eager. + +Set the mode with :option:`-X lazy_imports <-X>`, +:envvar:`PYTHON_LAZY_IMPORTS`, or :func:`sys.set_lazy_imports`. +:func:`sys.get_lazy_imports` returns the current mode. +A mode change applies to subsequent import statements. +It does not resolve proxies from earlier statements. + +:func:`sys.set_lazy_imports_filter` supplies a filter that can force any +potentially lazy import to be eager. This also applies to explicit +:keyword:`lazy` statements. The filter runs when the import statement executes. +A filter exception therefore occurs at the import statement. +The filter cannot make an otherwise eager import lazy. + +See also :data:`sys.lazy_modules`. + .. _lazy-modules-compat: Compatibility via ``__lazy_modules__`` diff --git a/Doc/tutorial/modules.rst b/Doc/tutorial/modules.rst index 46a226be606aeba..b2d503d6d3d3785 100644 --- a/Doc/tutorial/modules.rst +++ b/Doc/tutorial/modules.rst @@ -74,10 +74,21 @@ More on Modules =============== A module can contain executable statements as well as function definitions. -These statements are intended to initialize the module. They are executed only -the *first* time the module name is encountered in an import statement. [#]_ +These statements initialize the module. Python executes them only the +*first* time it loads the module. [#]_ (They are also run if the file is executed as a script.) +A :ref:`lazy import ` delays this execution until the first +use of the imported name. For example, in a new interpreter session:: + + >>> lazy import fibo + >>> fibo.fib(10) # Loads the module, then calls fib(). + 0 1 1 2 3 5 8 + +The ``lazy`` keyword is available in Python 3.15 and later. +Lazy imports are permitted only at module scope and outside +:keyword:`try`/:keyword:`except`/:keyword:`finally` blocks. + Each module has its own private namespace, which is used as the global namespace by all functions defined in the module. Thus, the author of a module can use global variables in the module without worrying about accidental clashes diff --git a/Doc/using/cmdline.rst b/Doc/using/cmdline.rst index ffb2587840be5a1..59a0c012659f4bc 100644 --- a/Doc/using/cmdline.rst +++ b/Doc/using/cmdline.rst @@ -720,9 +720,11 @@ Miscellaneous options .. versionadded:: 3.14 * :samp:`-X lazy_imports={all,normal}` controls lazy import behavior. - ``all`` makes all imports lazy by default, and ``normal`` (the default) - respects the ``lazy`` keyword in source code. - See also :envvar:`PYTHON_LAZY_IMPORTS`. + ``all`` makes eligible module-scope imports lazy by default. + ``normal`` (the default) respects :keyword:`lazy` and + :attr:`module.__lazy_modules__`. + The :ref:`lazy import restrictions ` apply in both modes. + See also :envvar:`PYTHON_LAZY_IMPORTS` and :func:`sys.set_lazy_imports`. .. versionadded:: 3.15 @@ -1428,9 +1430,11 @@ conflict. .. envvar:: PYTHON_LAZY_IMPORTS - Controls lazy import behavior. Accepts two values: ``all`` makes all - imports lazy by default, and ``normal`` (the default) respects the - ``lazy`` keyword in source code. + Control lazy import behavior. The variable accepts two values. + ``all`` makes eligible module-scope imports lazy by default. + ``normal`` (the default) respects :keyword:`lazy` and + :attr:`module.__lazy_modules__`. + The :ref:`lazy import restrictions ` apply in both modes. See also the :option:`-X lazy_imports <-X>` command-line option. diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst index b07c94287bdee6b..d2cfb7a4fab67eb 100644 --- a/Doc/whatsnew/3.15.rst +++ b/Doc/whatsnew/3.15.rst @@ -206,8 +206,10 @@ making it straightforward to diagnose and debug the failure. 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 two values: ``all`` makes all imports lazy by default, and ``normal`` -(the default) respects the ``lazy`` keyword in source code. The +accept two values: ``all`` makes eligible module-scope imports lazy by default, +and ``normal`` (the default) respects :keyword:`lazy` and +:attr:`module.__lazy_modules__`. The :ref:`lazy import restrictions +` apply in both modes. The :func:`sys.set_lazy_imports` and :func:`sys.get_lazy_imports` functions allow changing and querying this mode at runtime. diff --git a/Lib/pydoc_data/topics.py b/Lib/pydoc_data/topics.py index 7119825ac14e5b9..ec160014dba42b7 100644 --- a/Lib/pydoc_data/topics.py +++ b/Lib/pydoc_data/topics.py @@ -1,4 +1,4 @@ -# Autogenerated by Sphinx on Tue Nov 10 08:57:12 2026 +# Autogenerated by Sphinx on Sat Nov 21 13:18:55 2026 # as part of the release process. topics = { @@ -7256,7 +7256,8 @@ def whats_on_the_telly(penguin=None): * "type", when used in the "type" statement. -* "lazy", when used before an "import" statement. +* "lazy", when used before "import" or "from" in a lazy import + statement. These syntactically act as keywords in their specific contexts, but this distinction is done at the parser level, not when tokenizing. @@ -7607,13 +7608,15 @@ def whats_on_the_telly(penguin=None): Lazy imports are only permitted at module scope. Using "lazy" inside a function, class body, or "try"/"except"/"finally" block raises a "SyntaxError". Star imports cannot be lazy ("lazy from module import -*" is a syntax error), and future statements cannot be lazy. +*" is a syntax error). Explicit "lazy" syntax is also invalid for +future statements. -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. +With "lazy from ... import", each imported name can have its own +proxy. If the module is already initialized, Python can bind an +attribute without a proxy. Otherwise, the first access loads the +module and resolves the requested name. Other names remain unresolved +until access. If a name refers to a submodule, access loads that +submodule and its dependencies. Example: @@ -7631,11 +7634,65 @@ def whats_on_the_telly(penguin=None): "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. +The sections below describe name resolution and runtime controls. See +**PEP 810** for the full specification of lazy imports. Added in version 3.15. +Resolution and side effects +--------------------------- + +Python resolves a proxy when code reads the imported name or accesses +that name as a module attribute. After resolution, Python replaces the +proxy if the namespace permits writes and the entry still contains +that proxy. + +Direct access through "globals()" or a module’s "__dict__" returns the +proxy without resolution. The same applies to dictionary iteration. +"dir()" lists the names of a module and does not resolve its lazy +imports. Use "types.LazyImportType" to identify a proxy. Its +"resolve()" method returns the imported object. + +The module search occurs at resolution time. Changes to "sys.path" or +import hooks before resolution can change which module Python imports. +Direct calls to "__import__()" and "importlib.import_module()" are +eager. + +Module code executes when resolution loads the module. Side effects, +such as plugin registration, occur at that time. If a program needs +these side effects before the first use of an imported name, use an +eager import. In the default ""normal"" mode, omit "lazy" and exclude +the module from "__lazy_modules__". + +An import failure leaves the proxy available for a later attempt. If +resolution recursively accesses the same unresolved proxy, Python +raises "ImportCycleError". + + +Runtime controls +---------------- + +The default ""normal"" mode respects explicit "lazy" statements and +"__lazy_modules__". The ""all"" mode also makes other eligible module- +scope imports lazy. Imports inside functions, class bodies, and +"try"/"except"/"finally" blocks remain eager. Star imports also remain +eager. + +Set the mode with "-X lazy_imports", "PYTHON_LAZY_IMPORTS", or +"sys.set_lazy_imports()". "sys.get_lazy_imports()" returns the current +mode. A mode change applies to subsequent import statements. It does +not resolve proxies from earlier statements. + +"sys.set_lazy_imports_filter()" supplies a filter that can force any +potentially lazy import to be eager. This also applies to explicit +"lazy" statements. The filter runs when the import statement executes. +A filter exception therefore occurs at the import statement. The +filter cannot make an otherwise eager import lazy. + +See also "sys.lazy_modules". + + Compatibility via "__lazy_modules__" ------------------------------------ @@ -7892,13 +7949,15 @@ def (parameters): Lazy imports are only permitted at module scope. Using "lazy" inside a function, class body, or "try"/"except"/"finally" block raises a "SyntaxError". Star imports cannot be lazy ("lazy from module import -*" is a syntax error), and future statements cannot be lazy. +*" is a syntax error). Explicit "lazy" syntax is also invalid for +future statements. -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. +With "lazy from ... import", each imported name can have its own +proxy. If the module is already initialized, Python can bind an +attribute without a proxy. Otherwise, the first access loads the +module and resolves the requested name. Other names remain unresolved +until access. If a name refers to a submodule, access loads that +submodule and its dependencies. Example: @@ -7916,11 +7975,65 @@ def (parameters): "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. +The sections below describe name resolution and runtime controls. See +**PEP 810** for the full specification of lazy imports. Added in version 3.15. +Resolution and side effects +=========================== + +Python resolves a proxy when code reads the imported name or accesses +that name as a module attribute. After resolution, Python replaces the +proxy if the namespace permits writes and the entry still contains +that proxy. + +Direct access through "globals()" or a module’s "__dict__" returns the +proxy without resolution. The same applies to dictionary iteration. +"dir()" lists the names of a module and does not resolve its lazy +imports. Use "types.LazyImportType" to identify a proxy. Its +"resolve()" method returns the imported object. + +The module search occurs at resolution time. Changes to "sys.path" or +import hooks before resolution can change which module Python imports. +Direct calls to "__import__()" and "importlib.import_module()" are +eager. + +Module code executes when resolution loads the module. Side effects, +such as plugin registration, occur at that time. If a program needs +these side effects before the first use of an imported name, use an +eager import. In the default ""normal"" mode, omit "lazy" and exclude +the module from "__lazy_modules__". + +An import failure leaves the proxy available for a later attempt. If +resolution recursively accesses the same unresolved proxy, Python +raises "ImportCycleError". + + +Runtime controls +================ + +The default ""normal"" mode respects explicit "lazy" statements and +"__lazy_modules__". The ""all"" mode also makes other eligible module- +scope imports lazy. Imports inside functions, class bodies, and +"try"/"except"/"finally" blocks remain eager. Star imports also remain +eager. + +Set the mode with "-X lazy_imports", "PYTHON_LAZY_IMPORTS", or +"sys.set_lazy_imports()". "sys.get_lazy_imports()" returns the current +mode. A mode change applies to subsequent import statements. It does +not resolve proxies from earlier statements. + +"sys.set_lazy_imports_filter()" supplies a filter that can force any +potentially lazy import to be eager. This also applies to explicit +"lazy" statements. The filter runs when the import statement executes. +A filter exception therefore occurs at the import statement. The +filter cannot make an otherwise eager import lazy. + +See also "sys.lazy_modules". + + Compatibility via "__lazy_modules__" ==================================== @@ -14491,6 +14604,10 @@ def foo(): variable from within a module; it can only be accessed as an attribute on module objects. + Dictionary access does not resolve lazy import proxies. This also + applies to the dictionary that "globals()" returns. See + "types.LazyImportType" for proxy detection and explicit resolution. + **CPython implementation detail:** Because of the way CPython clears module dictionaries, the module dictionary will be cleared when the module falls out of scope even if the dictionary still has diff --git a/Python/clinic/sysmodule.c.h b/Python/clinic/sysmodule.c.h index 11bd8ba5bc2d5f2..bffd28005c35058 100644 --- a/Python/clinic/sysmodule.c.h +++ b/Python/clinic/sysmodule.c.h @@ -1927,11 +1927,13 @@ PyDoc_STRVAR(sys_set_lazy_imports_filter__doc__, "\n" "Set the lazy imports filter callback.\n" "\n" -"The filter is a callable which disables lazy imports when they\n" -"would otherwise be enabled. Returns True if the import is still enabled\n" -"or False to disable it. The callable is called with:\n" +"The filter receives three positional arguments:\n" "\n" -"(importing_module_name, resolved_imported_module_name, [fromlist])\n" +"(importing_module_name, resolved_imported_module_name, fromlist)\n" +"\n" +"The filter returns True to allow a lazy import, or False to force an\n" +"eager import.\n" +"The filter runs when the import statement executes.\n" "\n" "Pass None to clear the filter."); @@ -2011,15 +2013,13 @@ PyDoc_STRVAR(sys_set_lazy_imports__doc__, "set_lazy_imports($module, /, mode)\n" "--\n" "\n" -"Sets the global lazy imports mode.\n" +"Set the lazy import mode for the current interpreter.\n" "\n" -"The mode parameter must be one of the following strings:\n" -"- \"all\": All top-level imports become potentially lazy\n" -"- \"normal\": Only explicitly marked imports (with \'lazy\' keyword) are\n" -" lazy\n" +"The mode parameter must be one of these strings:\n" +"- \"all\": Make eligible module-scope imports potentially lazy.\n" +"- \"normal\": Respect the \'lazy\' keyword and __lazy_modules__.\n" "\n" -"In addition to the mode, lazy imports can be controlled via the filter\n" -"provided to sys.set_lazy_imports_filter"); +"The filter from sys.set_lazy_imports_filter can force an eager import."); #define SYS_SET_LAZY_IMPORTS_METHODDEF \ {"set_lazy_imports", _PyCFunction_CAST(sys_set_lazy_imports), METH_FASTCALL|METH_KEYWORDS, sys_set_lazy_imports__doc__}, @@ -2077,10 +2077,11 @@ PyDoc_STRVAR(sys_get_lazy_imports__doc__, "get_lazy_imports($module, /)\n" "--\n" "\n" -"Gets the global lazy imports mode.\n" +"Return the lazy import mode for the current interpreter.\n" "\n" -"Returns \"all\" if all top level imports are potentially lazy.\n" -"Returns \"normal\" if only explicitly marked imports are lazy."); +"The mode is \"all\" if eligible module-scope imports are potentially lazy.\n" +"The default mode, \"normal\", respects the \'lazy\' keyword and\n" +"__lazy_modules__."); #define SYS_GET_LAZY_IMPORTS_METHODDEF \ {"get_lazy_imports", (PyCFunction)sys_get_lazy_imports, METH_NOARGS, sys_get_lazy_imports__doc__}, @@ -2217,4 +2218,4 @@ _jit_is_active(PyObject *module, PyObject *Py_UNUSED(ignored)) #ifndef SYS_GETANDROIDAPILEVEL_METHODDEF #define SYS_GETANDROIDAPILEVEL_METHODDEF #endif /* !defined(SYS_GETANDROIDAPILEVEL_METHODDEF) */ -/*[clinic end generated code: output=dbca81c5072bd0e8 input=a9049054013a1b77]*/ +/*[clinic end generated code: output=5f64e1143b0add69 input=a9049054013a1b77]*/ diff --git a/Python/sysmodule.c b/Python/sysmodule.c index f8c72b096eb4529..df250fa9c92a9fd 100644 --- a/Python/sysmodule.c +++ b/Python/sysmodule.c @@ -2778,18 +2778,20 @@ sys.set_lazy_imports_filter Set the lazy imports filter callback. -The filter is a callable which disables lazy imports when they -would otherwise be enabled. Returns True if the import is still enabled -or False to disable it. The callable is called with: +The filter receives three positional arguments: -(importing_module_name, resolved_imported_module_name, [fromlist]) +(importing_module_name, resolved_imported_module_name, fromlist) + +The filter returns True to allow a lazy import, or False to force an +eager import. +The filter runs when the import statement executes. Pass None to clear the filter. [clinic start generated code]*/ static PyObject * sys_set_lazy_imports_filter_impl(PyObject *module, PyObject *filter) -/*[clinic end generated code: output=10251d49469c278c input=fd51ed8df6ab54b7]*/ +/*[clinic end generated code: output=10251d49469c278c input=c19391861fdd55d5]*/ { if (PyImport_SetLazyImportsFilter(filter) < 0) { return NULL; @@ -2823,21 +2825,19 @@ sys.set_lazy_imports mode: object -Sets the global lazy imports mode. +Set the lazy import mode for the current interpreter. -The mode parameter must be one of the following strings: -- "all": All top-level imports become potentially lazy -- "normal": Only explicitly marked imports (with 'lazy' keyword) are - lazy +The mode parameter must be one of these strings: +- "all": Make eligible module-scope imports potentially lazy. +- "normal": Respect the 'lazy' keyword and __lazy_modules__. -In addition to the mode, lazy imports can be controlled via the filter -provided to sys.set_lazy_imports_filter +The filter from sys.set_lazy_imports_filter can force an eager import. [clinic start generated code]*/ static PyObject * sys_set_lazy_imports_impl(PyObject *module, PyObject *mode) -/*[clinic end generated code: output=1ff34ba6c4feaf73 input=db3242f0ff6e5dcc]*/ +/*[clinic end generated code: output=1ff34ba6c4feaf73 input=b8d9528c12efa7f0]*/ { PyImport_LazyImportsMode lazy_mode; if (!PyUnicode_Check(mode)) { @@ -2866,16 +2866,17 @@ sys_set_lazy_imports_impl(PyObject *module, PyObject *mode) /*[clinic input] sys.get_lazy_imports -Gets the global lazy imports mode. +Return the lazy import mode for the current interpreter. -Returns "all" if all top level imports are potentially lazy. -Returns "normal" if only explicitly marked imports are lazy. +The mode is "all" if eligible module-scope imports are potentially lazy. +The default mode, "normal", respects the 'lazy' keyword and +__lazy_modules__. [clinic start generated code]*/ static PyObject * sys_get_lazy_imports_impl(PyObject *module) -/*[clinic end generated code: output=4147dec48c51ae99 input=6f8dd4f2c82893f2]*/ +/*[clinic end generated code: output=4147dec48c51ae99 input=ca95d71297deea55]*/ { switch (PyImport_GetLazyImportsMode()) { case PyImport_LAZY_NORMAL: