From 536b174c99b403b833f3aa5df8f41c2c385c9ac8 Mon Sep 17 00:00:00 2001 From: Xuanteng Huang Date: Sat, 6 Jun 2026 16:50:27 +0800 Subject: [PATCH 1/3] make `__name__` and `__file__` as a proxy for `_LazyModule.__spec__` --- Doc/library/importlib.rst | 17 +++++++ Lib/importlib/util.py | 25 +++++++++-- Lib/test/test_importlib/test_lazy.py | 45 ++++++++++++++++++- ...-06-06-12-00-00.gh-issue-139669.La9Zk1.rst | 7 +++ 4 files changed, 89 insertions(+), 5 deletions(-) create mode 100644 Misc/NEWS.d/next/Library/2026-06-06-12-00-00.gh-issue-139669.La9Zk1.rst diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index acccc9da416827f..a47d3b5177017f7 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1375,6 +1375,18 @@ an :term:`importer`. compatibility warning for :class:`importlib.machinery.BuiltinImporter` and :class:`importlib.machinery.ExtensionFileLoader`. + .. versionchanged:: 3.16 + Reading a lazily-loaded module's :attr:`~module.__name__` and + :attr:`~module.__file__` attributes no longer triggers the load. Until + the module is loaded they act as aliases for the + :attr:`~importlib.machinery.ModuleSpec.name` and + :attr:`~importlib.machinery.ModuleSpec.origin` of its + :attr:`~module.__spec__`, and assigning to them updates the spec + instead. This keeps introspection tools such as + :func:`inspect.getmodule` -- used indirectly by, for example, + :func:`inspect.getframeinfo` -- from forcing every lazily-loaded module + in :data:`sys.modules` to be imported (:gh:`139669`). + .. classmethod:: factory(loader) A class method which returns a callable that creates a lazy loader. This @@ -1486,6 +1498,11 @@ The example below shows how to implement lazy imports:: >>> lazy_typing.TYPE_CHECKING False +Reading the module's :attr:`~module.__name__` or :attr:`~module.__file__` +does not trigger the load; until then they mirror the module's +:attr:`~module.__spec__`. Accessing any other attribute (such as +``TYPE_CHECKING`` above) loads the module. + Setting up an importer '''''''''''''''''''''' diff --git a/Lib/importlib/util.py b/Lib/importlib/util.py index dbce696dc8d169a..5f9c65843d88730 100644 --- a/Lib/importlib/util.py +++ b/Lib/importlib/util.py @@ -175,6 +175,13 @@ class _LazyModule(types.ModuleType): def __getattribute__(self, attr): """Trigger the load of the module and return the attribute.""" __spec__ = object.__getattribute__(self, '__spec__') + + # gh-139669: avoid triggering lazy loading from these 2 attrs + if attr == "__name__": + return __spec__.name + if attr == "__file__": + return __spec__.origin + loader_state = __spec__.loader_state with loader_state['lock']: # Only the first thread to get the lock should trigger the load @@ -227,11 +234,23 @@ def __getattribute__(self, attr): return getattr(self, attr) + def __setattr__(self, attr, value): + """Keep __name__/__file__ in sync with __spec__ without loading.""" + __spec__ = object.__getattribute__(self, '__spec__') + if attr == "__name__": + __spec__.name = value + elif attr == "__file__": + __spec__.origin = value + else: + object.__setattr__(self, attr, value) + def __delattr__(self, attr): """Trigger the load and then perform the deletion.""" - # To trigger the load and raise an exception if the attribute - # doesn't exist. - self.__getattribute__(attr) + # Reading __name__/__file__ aliases the spec and no longer triggers + # the load, so access __spec__ to force it. This also resets + # __class__ to the real module type, avoiding infinite recursion in + # the delattr() below. + self.__getattribute__('__spec__') delattr(self, attr) diff --git a/Lib/test/test_importlib/test_lazy.py b/Lib/test/test_importlib/test_lazy.py index e48fad8898f0ef3..99e37e53d4668c2 100644 --- a/Lib/test/test_importlib/test_lazy.py +++ b/Lib/test/test_importlib/test_lazy.py @@ -1,6 +1,7 @@ import importlib from importlib import abc from importlib import util +import inspect import sys import time import threading @@ -99,6 +100,9 @@ def test_attr_unchanged(self): # An attribute only mutated as a side-effect of import should not be # changed needlessly. module = self.new_module() + # __name__ itself doesn't trigger the lazy loading, + # trigger via another attr + module.__package__ self.assertEqual(TestingImporter.mutated_name, module.__name__) def test_new_attr(self): @@ -138,14 +142,14 @@ def test_module_substitution_error(self): sys.modules[TestingImporter.module_name] = fresh_module module = self.new_module() with self.assertRaisesRegex(ValueError, "substituted"): - module.__name__ + module.__package__ def test_module_already_in_sys(self): with test_util.uncache(TestingImporter.module_name): module = self.new_module() sys.modules[TestingImporter.module_name] = module # Force the load; just care that no exception is raised. - module.__name__ + module.__package__ @threading_helper.requires_working_threading() def test_module_load_race(self): @@ -224,6 +228,43 @@ def __delattr__(self, name): with self.assertRaises(AttributeError): del module.CONSTANT + def test_name_file_alias_spec(self): + # gh-139669: __name__/__file__ are aliases for __spec__.name and + # __spec__.origin. Reading them returns the spec values and does not + # trigger the load; writing them flows through to the spec. + loader = TestingImporter() + module = self.new_module(loader=loader) + spec = object.__getattribute__(module, '__spec__') + spec.origin = '/some/where.py' + self.assertEqual(module.__name__, spec.name) + self.assertEqual(module.__file__, '/some/where.py') + # Neither read triggered the load. + self.assertIsNone(loader.loaded) + self.assertEqual(0, loader.load_count) + # Writes flow through to the spec, still without loading. + module.__name__ = 'renamed' + module.__file__ = '/other.py' + self.assertEqual(spec.name, 'renamed') + self.assertEqual(spec.origin, '/other.py') + self.assertEqual(module.__name__, 'renamed') + self.assertEqual(module.__file__, '/other.py') + self.assertIsNone(loader.loaded) + self.assertIsInstance(module, util._LazyModule) + + def test_inspect_does_not_trigger_lazy_load(self): + # gh-139669: introspecting an unrelated frame iterates over + # sys.modules and must not force lazy modules to be loaded. + loader = TestingImporter() + module = self.new_module(loader=loader) + with test_util.uncache(TestingImporter.module_name): + sys.modules[TestingImporter.module_name] = module + self.assertIsInstance(module, util._LazyModule) + + inspect.getframeinfo(inspect.currentframe()) + self.assertIsNone(loader.loaded) + self.assertEqual(0, loader.load_count) + self.assertIsInstance(module, util._LazyModule) + if __name__ == '__main__': unittest.main() diff --git a/Misc/NEWS.d/next/Library/2026-06-06-12-00-00.gh-issue-139669.La9Zk1.rst b/Misc/NEWS.d/next/Library/2026-06-06-12-00-00.gh-issue-139669.La9Zk1.rst new file mode 100644 index 000000000000000..a13647ddd5fcb2c --- /dev/null +++ b/Misc/NEWS.d/next/Library/2026-06-06-12-00-00.gh-issue-139669.La9Zk1.rst @@ -0,0 +1,7 @@ +Reading the :attr:`~module.__name__` and :attr:`~module.__file__` attributes +of a module created by :class:`importlib.util.LazyLoader` no longer triggers +the load. While the module remains unloaded these attributes are aliases for +its :attr:`~module.__spec__`, and assigning to them updates the spec. This +prevents introspection tools such as :func:`inspect.getframeinfo`, via +:func:`inspect.getmodule`, from forcing every lazily-loaded module in +:data:`sys.modules` to be imported. From 1b8a8d4f1bda3c763b3394383ff2b928d79f3b00 Mon Sep 17 00:00:00 2001 From: Xuanteng Huang Date: Sat, 6 Jun 2026 16:59:51 +0800 Subject: [PATCH 2/3] rephrase --- Doc/library/importlib.rst | 8 +++----- Lib/importlib/util.py | 5 +---- Lib/test/test_importlib/test_lazy.py | 23 ----------------------- 3 files changed, 4 insertions(+), 32 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index a47d3b5177017f7..f5b817009ad6851 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1377,15 +1377,13 @@ an :term:`importer`. .. versionchanged:: 3.16 Reading a lazily-loaded module's :attr:`~module.__name__` and - :attr:`~module.__file__` attributes no longer triggers the load. Until + :attr:`~module.__file__` attributes no longer triggers the load. Until the module is loaded they act as aliases for the :attr:`~importlib.machinery.ModuleSpec.name` and :attr:`~importlib.machinery.ModuleSpec.origin` of its :attr:`~module.__spec__`, and assigning to them updates the spec - instead. This keeps introspection tools such as - :func:`inspect.getmodule` -- used indirectly by, for example, - :func:`inspect.getframeinfo` -- from forcing every lazily-loaded module - in :data:`sys.modules` to be imported (:gh:`139669`). + instead. This avoids the unintentional loading caused by + introspection tools like :func:`inspect.getframeinfo` (:gh:`139669`). .. classmethod:: factory(loader) diff --git a/Lib/importlib/util.py b/Lib/importlib/util.py index 5f9c65843d88730..4e99fa513905dac 100644 --- a/Lib/importlib/util.py +++ b/Lib/importlib/util.py @@ -246,11 +246,8 @@ def __setattr__(self, attr, value): def __delattr__(self, attr): """Trigger the load and then perform the deletion.""" - # Reading __name__/__file__ aliases the spec and no longer triggers - # the load, so access __spec__ to force it. This also resets - # __class__ to the real module type, avoiding infinite recursion in - # the delattr() below. self.__getattribute__('__spec__') + # Goes into ModuleType.__delattr__ delattr(self, attr) diff --git a/Lib/test/test_importlib/test_lazy.py b/Lib/test/test_importlib/test_lazy.py index 99e37e53d4668c2..452f42c6aa046bc 100644 --- a/Lib/test/test_importlib/test_lazy.py +++ b/Lib/test/test_importlib/test_lazy.py @@ -228,29 +228,6 @@ def __delattr__(self, name): with self.assertRaises(AttributeError): del module.CONSTANT - def test_name_file_alias_spec(self): - # gh-139669: __name__/__file__ are aliases for __spec__.name and - # __spec__.origin. Reading them returns the spec values and does not - # trigger the load; writing them flows through to the spec. - loader = TestingImporter() - module = self.new_module(loader=loader) - spec = object.__getattribute__(module, '__spec__') - spec.origin = '/some/where.py' - self.assertEqual(module.__name__, spec.name) - self.assertEqual(module.__file__, '/some/where.py') - # Neither read triggered the load. - self.assertIsNone(loader.loaded) - self.assertEqual(0, loader.load_count) - # Writes flow through to the spec, still without loading. - module.__name__ = 'renamed' - module.__file__ = '/other.py' - self.assertEqual(spec.name, 'renamed') - self.assertEqual(spec.origin, '/other.py') - self.assertEqual(module.__name__, 'renamed') - self.assertEqual(module.__file__, '/other.py') - self.assertIsNone(loader.loaded) - self.assertIsInstance(module, util._LazyModule) - def test_inspect_does_not_trigger_lazy_load(self): # gh-139669: introspecting an unrelated frame iterates over # sys.modules and must not force lazy modules to be loaded. From 6f9f53908c067cb1939c56670e9607eff698983a Mon Sep 17 00:00:00 2001 From: Xuanteng Huang Date: Sun, 15 Nov 2026 23:16:35 +0800 Subject: [PATCH 3/3] reserve attr --- Doc/library/importlib.rst | 5 +++-- Lib/importlib/util.py | 4 ++-- Lib/test/test_importlib/test_lazy.py | 16 +++++++++++++++- 3 files changed, 20 insertions(+), 5 deletions(-) diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst index f5b817009ad6851..981aa7227fc00da 100644 --- a/Doc/library/importlib.rst +++ b/Doc/library/importlib.rst @@ -1381,8 +1381,9 @@ an :term:`importer`. the module is loaded they act as aliases for the :attr:`~importlib.machinery.ModuleSpec.name` and :attr:`~importlib.machinery.ModuleSpec.origin` of its - :attr:`~module.__spec__`, and assigning to them updates the spec - instead. This avoids the unintentional loading caused by + :attr:`~module.__spec__`, and assigning to them also updates the spec. + These assignments are preserved when the module is loaded. + This avoids the unintentional loading caused by introspection tools like :func:`inspect.getframeinfo` (:gh:`139669`). .. classmethod:: factory(loader) diff --git a/Lib/importlib/util.py b/Lib/importlib/util.py index 4e99fa513905dac..dccc6aaa6e3997c 100644 --- a/Lib/importlib/util.py +++ b/Lib/importlib/util.py @@ -241,8 +241,8 @@ def __setattr__(self, attr, value): __spec__.name = value elif attr == "__file__": __spec__.origin = value - else: - object.__setattr__(self, attr, value) + # Record the assignment so it can be restored after loading. + object.__setattr__(self, attr, value) def __delattr__(self, attr): """Trigger the load and then perform the deletion.""" diff --git a/Lib/test/test_importlib/test_lazy.py b/Lib/test/test_importlib/test_lazy.py index 452f42c6aa046bc..326ac5ca4faa7db 100644 --- a/Lib/test/test_importlib/test_lazy.py +++ b/Lib/test/test_importlib/test_lazy.py @@ -114,9 +114,23 @@ def test_new_attr(self): def test_mutated_preexisting_attr(self): # Changing an attribute that already existed on the module -- # e.g. __name__ -- should persist. - module = self.new_module() + loader = TestingImporter() + module = self.new_module(loader=loader) module.__name__ = 'bogus' self.assertEqual('bogus', module.__name__) + self.assertIsNone(loader.loaded) + self.assertEqual(module.attr, 42) + self.assertEqual('bogus', module.__name__) + + def test_mutated_file_survives_loading(self): + loader = TestingImporter() + module = self.new_module( + source_code="attr = 42; __file__ = 'changed.py'", loader=loader) + module.__file__ = 'bogus.py' + self.assertEqual('bogus.py', module.__file__) + self.assertIsNone(loader.loaded) + self.assertEqual(module.attr, 42) + self.assertEqual('bogus.py', module.__file__) def test_mutated_attr(self): # Changing an attribute that comes into existence after an import