Make all imports lazy by default.
- .. c:enumerator:: PyImport_LAZY_NONE
-
- Disable lazy imports entirely. Even explicit ``lazy`` statements become
- eager imports.
-
.. versionadded:: 3.15
.. c:function:: PyObject* PyImport_CreateModuleFromInitfunc(PyObject *spec, PyObject* (*initfunc)(void))
<underlying-type type-id='type-id-45'/>
<enumerator name='PyImport_LAZY_NORMAL' value='0'/>
<enumerator name='PyImport_LAZY_ALL' value='1'/>
- <enumerator name='PyImport_LAZY_NONE' value='2'/>
</enum-decl>
<typedef-decl name='PyImport_LazyImportsMode' type-id='type-id-1652' filepath='./Include/import.h' line='95' column='1' id='type-id-1651'/>
<typedef-decl name='conversion_func' type-id='type-id-1456' filepath='./Include/internal/pycore_ceval.h' line='282' column='1' id='type-id-1653'/>
* ``"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`.
* ``"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
:keyword:`try`/:keyword:`except`/:keyword:`finally` blocks are always eager,
regardless of :attr:`!__lazy_modules__`.
-Setting ``-X lazy_imports=none`` (or the :envvar:`PYTHON_LAZY_IMPORTS`
-environment variable to ``none``) overrides :attr:`!__lazy_modules__` and
-forces all imports to be eager.
-
.. versionadded:: 3.15
.. _future:
library/asyncio-task.html: terminating-a-task-group
+# Removed APIs
+c-api/import.html: c.PyImport_LazyImportsMode.PyImport_LAZY_NONE
+
## Old names for grammar tokens
reference/expressions.html: grammar-token-python-grammar-comp_for
reference/expressions.html: grammar-token-python-grammar-comp_if
.. versionadded:: 3.14
- * :samp:`-X lazy_imports={all,none,normal}` controls lazy import behavior.
- ``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.
+ * :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`.
.. versionadded:: 3.15
.. envvar:: PYTHON_LAZY_IMPORTS
- Controls lazy import behavior. Accepts 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.
+ 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.
See also the :option:`-X lazy_imports <-X>` command-line option.
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.
+accept two values: ``all`` makes all imports lazy by default, 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.
typedef enum {
PyImport_LAZY_NORMAL,
- PyImport_LAZY_ALL,
- PyImport_LAZY_NONE
+ PyImport_LAZY_ALL
} PyImport_LazyImportsMode;
#ifndef Py_LIMITED_API
class GlobalLazyImportModeTests(LazyImportTestCase):
"""Tests for sys.set_lazy_imports() global mode control."""
- def test_global_off(self):
- """Mode 'none' should disable lazy imports entirely."""
- import test.test_lazy_import.data.global_off
- self.assertIn("test.test_lazy_import.data.basic2", sys.modules)
+ def tearDown(self):
+ for key in list(sys.modules.keys()):
+ if key.startswith('test.test_lazy_import.data'):
+ del sys.modules[key]
+
+ sys.set_lazy_imports_filter(None)
+ sys.set_lazy_imports("normal")
+
+ def test_global_off_rejected(self):
+ """Mode 'none' is not supported."""
+ with self.assertRaises(ValueError):
+ sys.set_lazy_imports("none")
def test_global_on(self):
"""Mode 'all' should make regular imports lazy."""
sys.set_lazy_imports("all")
self.assertEqual(sys.get_lazy_imports(), "all")
- sys.set_lazy_imports("none")
- self.assertEqual(sys.get_lazy_imports(), "none")
-
def test_get_lazy_imports_filter_default(self):
"""get_lazy_imports_filter should return None by default."""
sys.set_lazy_imports_filter(None)
self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
self.assertIn("LAZY", result.stdout)
- def test_cli_lazy_imports_none_forces_all_imports_eager(self):
- """-X lazy_imports=none should force all imports to be eager."""
- code = textwrap.dedent("""
- import sys
- # Even explicit lazy imports should be eager in 'none' mode
- lazy import json
- if 'json' in sys.modules:
- print("EAGER")
- else:
- print("LAZY")
- """)
+ def test_cli_lazy_imports_none_is_rejected(self):
+ """-X lazy_imports=none should be rejected."""
result = subprocess.run(
- [sys.executable, "-X", "lazy_imports=none", "-c", code],
+ [sys.executable, "-X", "lazy_imports=none", "-c", "pass"],
capture_output=True,
text=True
)
- self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
- self.assertIn("EAGER", result.stdout)
-
- @support.requires_resource("cpu")
- def test_cli_lazy_imports_modes_import_stdlib_modules(self):
- """-X lazy_imports modes should import available stdlib modules."""
- # Do not smoke-test modules with intentional import-time effects.
- import_side_effect_modules = {"antigravity", "this"}
- importable = []
-
- for module in sorted(sys.stdlib_module_names):
- if module in import_side_effect_modules:
- continue
-
- with self.subTest(module=module):
- code = f"import {module}; print({module})"
- baseline = subprocess.run(
- [sys.executable, "-I", "-c", code],
- capture_output=True,
- text=True,
- timeout=60,
- )
- if baseline.returncode:
- # sys.stdlib_module_names includes modules for other
- # platforms and optional extension modules not built here.
- continue
- importable.append(module)
-
- for mode in ("normal", "none"):
- with self.subTest(module=module, mode=mode):
- result = subprocess.run(
- [
- sys.executable,
- "-I",
- "-X",
- f"lazy_imports={mode}",
- "-c",
- code,
- ],
- capture_output=True,
- text=True,
- timeout=60,
- )
- self.assertEqual(result.returncode, 0, result.stderr)
-
- self.assertGreater(len(importable), 100)
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn("-X lazy_imports: invalid value", result.stderr)
+ self.assertIn("expected 'all' or 'normal'", result.stderr)
def test_cli_lazy_imports_normal_respects_lazy_keyword_only(self):
"""-X lazy_imports=normal should respect lazy keyword only."""
self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
self.assertIn("LAZY", result.stdout)
- def test_env_var_lazy_imports_none_disables_all_lazy(self):
- """PYTHON_LAZY_IMPORTS=none should disable all lazy imports."""
- code = textwrap.dedent("""
- import sys
- lazy import json
- if 'json' in sys.modules:
- print("EAGER")
- else:
- print("LAZY")
- """)
+ def test_env_var_lazy_imports_none_is_rejected(self):
+ """PYTHON_LAZY_IMPORTS=none should be rejected."""
import os
env = os.environ.copy()
env["PYTHON_LAZY_IMPORTS"] = "none"
result = subprocess.run(
- [sys.executable, "-c", code],
+ [sys.executable, "-c", "pass"],
capture_output=True,
text=True,
env=env
)
- self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
- self.assertIn("EAGER", result.stdout)
-
- def test_cli_lazy_imports_none_disables_dunder_lazy_modules(self):
- """-X lazy_imports=none should override __lazy_modules__."""
- code = textwrap.dedent("""
- import sys
- __lazy_modules__ = ["json"]
- import json
- if 'json' in sys.modules:
- print("EAGER")
- else:
- print("LAZY")
- """)
- result = subprocess.run(
- [sys.executable, "-X", "lazy_imports=none", "-c", code],
- capture_output=True,
- text=True,
- )
- self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
- self.assertIn("EAGER", result.stdout)
-
- def test_env_var_lazy_imports_none_disables_dunder_lazy_modules(self):
- """PYTHON_LAZY_IMPORTS=none should override __lazy_modules__."""
- code = textwrap.dedent("""
- import sys
- __lazy_modules__ = ["json"]
- import json
- if 'json' in sys.modules:
- print("EAGER")
- else:
- print("LAZY")
- """)
- import os
-
- env = os.environ.copy()
- env["PYTHON_LAZY_IMPORTS"] = "none"
- result = subprocess.run(
- [sys.executable, "-c", code],
- capture_output=True,
- text=True,
- env=env,
- )
- self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
- self.assertIn("EAGER", result.stdout)
+ self.assertNotEqual(result.returncode, 0)
+ self.assertIn("PYTHON_LAZY_IMPORTS: invalid value", result.stderr)
+ self.assertIn("expected 'all' or 'normal'", result.stderr)
def test_cli_overrides_env_var(self):
"""Command-line option should take precedence over environment variable."""
# PEP 810: -X lazy_imports takes precedence over PYTHON_LAZY_IMPORTS
code = textwrap.dedent("""
import sys
- lazy import json
+ import json
if 'json' in sys.modules:
print("EAGER")
else:
""")
import os
env = os.environ.copy()
- env["PYTHON_LAZY_IMPORTS"] = "all" # env says all
+ env["PYTHON_LAZY_IMPORTS"] = "all" # env says all imports are lazy
result = subprocess.run(
- [sys.executable, "-X", "lazy_imports=none", "-c", code], # CLI says none
+ [sys.executable, "-X", "lazy_imports=normal", "-c", code],
capture_output=True,
text=True,
env=env
)
self.assertEqual(result.returncode, 0, f"stderr: {result.stderr}")
- # CLI should win - imports should be eager
+ # CLI should win, so a regular import should stay eager.
self.assertIn("EAGER", result.stdout)
def test_sys_set_lazy_imports_overrides_cli(self):
"""sys.set_lazy_imports() should take precedence over CLI option."""
code = textwrap.dedent("""
import sys
- sys.set_lazy_imports("none") # Override CLI
- lazy import json
+ sys.set_lazy_imports("normal") # Override CLI
+ import json
if 'json' in sys.modules:
print("EAGER")
else:
class LazyCApiTests(LazyImportTestCase):
def test_set_matches_sys(self):
self.assertEqual(_testcapi.PyImport_GetLazyImportsMode(), sys.get_lazy_imports())
- for mode in ("normal", "all", "none"):
+ for mode in ("normal", "all"):
_testcapi.PyImport_SetLazyImportsMode(mode)
self.assertEqual(_testcapi.PyImport_GetLazyImportsMode(), sys.get_lazy_imports())
+ self.assertRaises(ValueError, _testcapi.PyImport_SetLazyImportsMode, "none")
def test_filter_matches_sys(self):
self.assertEqual(_testcapi.PyImport_GetLazyImportsFilter(), sys.get_lazy_imports_filter())
+++ /dev/null
-import sys
-
-sys.set_lazy_imports("none")
-
-lazy import test.test_lazy_import.data.basic2 as basic2
..
-.. date: 2026-03-24-13-06-52
-.. gh-issue: 146369
-.. nonce: 6wDI6S
-.. section: Core and Builtins
-
-Ensure ``-X lazy_imports=none`` and ``PYTHON_LAZY_IMPORTS=none`` override
-:attr:`~module.__lazy_modules__`. Patch by Hugo van Kemenade.
-
-..
-
.. date: 2026-03-22-19-30-00
.. gh-issue: 146308
.. nonce: AxnRVA
--- /dev/null
+Do not support ``none`` as a lazy imports mode.
PyImport_SetLazyImportsMode(PyImport_LAZY_NORMAL);
} else if (strcmp(PyUnicode_AsUTF8(mode), "all") == 0) {
PyImport_SetLazyImportsMode(PyImport_LAZY_ALL);
- } else if (strcmp(PyUnicode_AsUTF8(mode), "none") == 0) {
- PyImport_SetLazyImportsMode(PyImport_LAZY_NONE);
} else {
PyErr_SetString(PyExc_ValueError, "invalid mode");
return NULL;
return PyUnicode_FromString("normal");
case PyImport_LAZY_ALL:
return PyUnicode_FromString("all");
- case PyImport_LAZY_NONE:
- return PyUnicode_FromString("none");
default:
PyErr_SetString(PyExc_ValueError, "unknown mode");
return NULL;
PyObject *fromlist, PyObject *level, int lazy)
{
PyObject *res = NULL;
- PyImport_LazyImportsMode mode = PyImport_GetLazyImportsMode();
// Check if global policy overrides the local syntax
- switch (mode) {
- case PyImport_LAZY_NONE:
- lazy = 0;
- break;
+ switch (PyImport_GetLazyImportsMode()) {
case PyImport_LAZY_ALL:
if (!lazy) {
lazy = is_lazy_import_module_level();
break;
}
- if (!lazy && mode != PyImport_LAZY_NONE && is_lazy_import_module_level()) {
+ if (!lazy) {
// See if __lazy_modules__ forces this to be lazy.
- lazy = check_lazy_import_compatibility(tstate, globals, name, level);
- if (lazy < 0) {
- return NULL;
+ // __lazy_modules__ only applies at module level; exec() inside
+ // functions or classes should remain eager.
+ if (is_lazy_import_module_level()) {
+ lazy = check_lazy_import_compatibility(tstate, globals, name, level);
+ if (lazy < 0) {
+ return NULL;
+ }
}
}
"\n"
"The mode parameter must be one of the following strings:\n"
"- \"all\": All top-level imports become potentially lazy\n"
-"- \"none\": All lazy imports are suppressed (even explicitly marked ones)\n"
"- \"normal\": Only explicitly marked imports (with \'lazy\' keyword) are\n"
" lazy\n"
"\n"
"Gets the global lazy imports mode.\n"
"\n"
"Returns \"all\" if all top level imports are potentially lazy.\n"
-"Returns \"none\" if all explicitly marked lazy imports are suppressed.\n"
"Returns \"normal\" if only explicitly marked imports are lazy.");
#define SYS_GET_LAZY_IMPORTS_METHODDEF \
#ifndef SYS_GETANDROIDAPILEVEL_METHODDEF
#define SYS_GETANDROIDAPILEVEL_METHODDEF
#endif /* !defined(SYS_GETANDROIDAPILEVEL_METHODDEF) */
-/*[clinic end generated code: output=94838be2d96b4522 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=3ccdb73f733fc82c input=a9049054013a1b77]*/
" log imports of already-loaded modules; also #e{PYTHONPROFILEIMPORTTIME}\n"
"#s{-X} #L{int_max_str_digits}#b{=N}: limit the size of int<->str conversions;\n"
" 0 disables the limit; also #e{PYTHONINTMAXSTRDIGITS}\n"
-"#s{-X} #L{lazy_imports}#b{=[all|none|normal]}: control global lazy imports;\n"
+"#s{-X} #L{lazy_imports}#b{=[all|normal]}: control global lazy imports;\n"
" default is #B{normal}; also #e{PYTHON_LAZY_IMPORTS}\n"
"#s{-X} #L{no_debug_ranges}: don't include extra location information in code objects;\n"
" also #e{PYTHONNODEBUGRANGES}\n"
assert(config->int_max_str_digits >= 0);
// cpu_count can be -1 if the user doesn't override it.
assert(config->cpu_count != 0);
- // lazy_imports can be -1 (default), 0 (off), or 1 (on).
+ // lazy_imports can be -1 (default) or 1 (on). 0 is rejected later
+ // for embedders with an error message.
assert(config->lazy_imports >= -1 && config->lazy_imports <= 1);
// config->use_frozen_modules is initialized later
// by _PyConfig_InitImportConfig().
if (strcmp(env, "all") == 0) {
lazy_imports = 1;
}
- else if (strcmp(env, "none") == 0) {
- lazy_imports = 0;
- }
else if (strcmp(env, "normal") == 0) {
lazy_imports = -1;
}
else {
return _PyStatus_ERR("PYTHON_LAZY_IMPORTS: invalid value; "
- "expected 'all', 'none', or 'normal'");
+ "expected 'all' or 'normal'");
}
config->lazy_imports = lazy_imports;
}
if (wcscmp(x_value, L"all") == 0) {
lazy_imports = 1;
}
- else if (wcscmp(x_value, L"none") == 0) {
- lazy_imports = 0;
- }
else if (wcscmp(x_value, L"normal") == 0) {
lazy_imports = -1;
}
else {
return _PyStatus_ERR("-X lazy_imports: invalid value; "
- "expected 'all', 'none', or 'normal'");
+ "expected 'all' or 'normal'");
}
config->lazy_imports = lazy_imports;
}
// Initialize lazy imports based on configuration. Do this after site
// module is imported to avoid circular imports during startup.
- if (config->lazy_imports != -1) {
- PyImport_LazyImportsMode lazy_mode;
- if (config->lazy_imports == 1) {
- lazy_mode = PyImport_LAZY_ALL;
- }
- else {
- lazy_mode = PyImport_LAZY_NONE;
- }
- if (PyImport_SetLazyImportsMode(lazy_mode) < 0) {
+ if (config->lazy_imports == 0) {
+ return _PyStatus_ERR("PyConfig.lazy_imports=0 is not supported");
+ }
+ if (config->lazy_imports == 1) {
+ if (PyImport_SetLazyImportsMode(PyImport_LAZY_ALL) < 0) {
return _PyStatus_ERR("failed to set lazy imports mode");
}
}
The mode parameter must be one of the following strings:
- "all": All top-level imports become potentially lazy
-- "none": All lazy imports are suppressed (even explicitly marked ones)
- "normal": Only explicitly marked imports (with 'lazy' keyword) are
lazy
static PyObject *
sys_set_lazy_imports_impl(PyObject *module, PyObject *mode)
-/*[clinic end generated code: output=1ff34ba6c4feaf73 input=cb6df28a51844a31]*/
+/*[clinic end generated code: output=1ff34ba6c4feaf73 input=db3242f0ff6e5dcc]*/
{
PyImport_LazyImportsMode lazy_mode;
if (!PyUnicode_Check(mode)) {
PyErr_SetString(PyExc_TypeError,
- "mode must be a string: 'normal', 'all', or 'none'");
+ "mode must be a string: 'normal' or 'all'");
return NULL;
}
if (PyUnicode_CompareWithASCIIString(mode, "normal") == 0) {
else if (PyUnicode_CompareWithASCIIString(mode, "all") == 0) {
lazy_mode = PyImport_LAZY_ALL;
}
- else if (PyUnicode_CompareWithASCIIString(mode, "none") == 0) {
- lazy_mode = PyImport_LAZY_NONE;
- }
else {
PyErr_SetString(PyExc_ValueError,
- "mode must be 'normal', 'all', or 'none'");
+ "mode must be 'normal' or 'all'");
return NULL;
}
Gets the global lazy imports mode.
Returns "all" if all top level imports are potentially lazy.
-Returns "none" if all explicitly marked lazy imports are suppressed.
Returns "normal" if only explicitly marked imports are lazy.
[clinic start generated code]*/
static PyObject *
sys_get_lazy_imports_impl(PyObject *module)
-/*[clinic end generated code: output=4147dec48c51ae99 input=8cb574f1e4e3003c]*/
+/*[clinic end generated code: output=4147dec48c51ae99 input=6f8dd4f2c82893f2]*/
{
switch (PyImport_GetLazyImportsMode()) {
case PyImport_LAZY_NORMAL:
return PyUnicode_FromString("normal");
case PyImport_LAZY_ALL:
return PyUnicode_FromString("all");
- case PyImport_LAZY_NONE:
- return PyUnicode_FromString("none");
default:
PyErr_SetString(PyExc_RuntimeError, "unknown lazy imports mode");
return NULL;
projects / thirdparty / Python / cpython.git / commitdiff
