Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 11 additions & 8 deletions Doc/builtins/functions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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.
Expand Down
19 changes: 11 additions & 8 deletions Doc/c-api/import.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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 <lazy-imports>`.

.. versionadded:: 3.15

Expand Down
8 changes: 5 additions & 3 deletions Doc/c-api/init_config.rst
Original file line number Diff line number Diff line change
Expand Up @@ -1607,9 +1607,11 @@ PyConfig

Control :ref:`lazy imports <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 <lazy-imports>` 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.
Expand Down
5 changes: 5 additions & 0 deletions Doc/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
20 changes: 18 additions & 2 deletions Doc/library/ast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -1145,12 +1147,22 @@ Imports
is_lazy=0)])


.. class:: ImportFrom(module, names, level)
.. versionchanged:: 3.15
Added ``is_lazy`` for :ref:`lazy imports <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::

Expand All @@ -1167,6 +1179,10 @@ Imports
is_lazy=0)])


.. versionchanged:: 3.15
Added ``is_lazy`` for :ref:`lazy imports <lazy-imports>`.


.. class:: alias(name, asname)

Both parameters are raw strings of the names. ``asname`` can be ``None`` if
Expand Down
26 changes: 22 additions & 4 deletions Doc/library/dis.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <types.LazyImportType>`.
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 <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)
Expand All @@ -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 <types.LazyImportType>`, the result can
be another proxy that represents the requested attribute.

.. versionchanged:: 3.15
Added support for lazy import proxies.


.. opcode:: JUMP_FORWARD (delta)

Expand Down
8 changes: 8 additions & 0 deletions Doc/library/importlib.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <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
Expand Down
29 changes: 19 additions & 10 deletions Doc/library/sys.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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 <lazy-imports>` 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
Expand All @@ -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``)
Expand All @@ -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.

Expand Down
25 changes: 20 additions & 5 deletions Doc/library/types.rst
Original file line number Diff line number Diff line change
Expand Up @@ -345,18 +345,33 @@ 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 <lazy-imports>`.
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

.. seealso:: :pep:`810`

.. 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
Expand Down
5 changes: 5 additions & 0 deletions Doc/reference/datamodel.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <lazy-imports>`.
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
Expand Down
17 changes: 12 additions & 5 deletions Doc/reference/import.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand All @@ -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 <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`
================
Expand Down
3 changes: 2 additions & 1 deletion Doc/reference/lexical_analysis.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <lazy-imports>` statement.

These syntactically act as keywords in their specific contexts,
but this distinction is done at the parser level, not when tokenizing.
Expand Down
Loading
Loading