gh-139686: Make reloading a lazy module no-op (GH-139857)

Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Brett Cannon <brett@python.org>

diff --git a/Doc/library/importlib.rst b/Doc/library/importlib.rst
index c5ea78c1683761ff2522283815becf48f9cd163f..b04403cd15a58c3e1c8c12998a83aa01436e6900 100644 (file)
--- a/Doc/library/importlib.rst
+++ b/Doc/library/importlib.rst
@@ -210,6 +210,12 @@ Functions
        :exc:`ModuleNotFoundError` is raised when the module being reloaded lacks
        a :class:`~importlib.machinery.ModuleSpec`.
 
+   .. versionchanged:: 3.14
+       If *module* is a lazy module that has not yet been materialized (i.e.,
+       loaded via :class:`importlib.util.LazyLoader` and not yet accessed),
+       calling :func:`reload` is a no-op and returns the module unchanged.
+       This prevents the reload from unintentionally triggering the lazy load.
+
    .. warning::
       This function is not thread-safe. Calling it from multiple threads can result
       in unexpected behavior. It's recommended to use the :class:`threading.Lock`

diff --git a/Lib/importlib/__init__.py b/Lib/importlib/__init__.py
index a7d57561ead046c481d4d78bf33a6726185e399d..694fea806f7944085f80ea4a899a8c36423367bf 100644 (file)
--- a/Lib/importlib/__init__.py
+++ b/Lib/importlib/__init__.py
@@ -97,6 +97,11 @@ def reload(module):
     The module must have been successfully imported before.
 
     """
+    # If a LazyModule has not yet been materialized, reload is a no-op.
+    if importlib_util := sys.modules.get('importlib.util'):
+        if lazy_module_type := getattr(importlib_util, '_LazyModule', None):
+            if isinstance(module, lazy_module_type):
+                return module
     try:
         name = module.__spec__.name
     except AttributeError:

diff --git a/Lib/test/test_importlib/test_lazy.py b/Lib/test/test_importlib/test_lazy.py
index e48fad8898f0ef3eff32be1b0dc91fd86bf2ee08..c6b26ad75b97f9222e0c73975c36c19519d2504b 100644 (file)
--- a/Lib/test/test_importlib/test_lazy.py
+++ b/Lib/test/test_importlib/test_lazy.py
@@ -10,6 +10,9 @@ import unittest
 from test.support import threading_helper
 from test.test_importlib import util as test_util
 
+# Make sure sys.modules[util] is in sync with the import.
+# That is needed as other tests may reload util.
+sys.modules['importlib.util'] = util
 
 class CollectInit:
 
@@ -192,7 +195,7 @@ class LazyLoaderTests(unittest.TestCase):
             sys.modules['json'] = module
             loader.exec_module(module)
 
-            # Trigger load with attribute lookup, ensure expected behavior
+            # Trigger load with attribute lookup, ensure expected behavior.
             test_load = module.loads('{}')
             self.assertEqual(test_load, {})
 
@@ -224,6 +227,26 @@ sys.modules[__name__].__class__ = ImmutableModule
         with self.assertRaises(AttributeError):
             del module.CONSTANT
 
+    def test_reload(self):
+        # Reloading a lazy module that hasn't been materialized is a no-op.
+        module = self.new_module()
+        sys.modules[TestingImporter.module_name] = module
+
+        # Change the source code to add a new attribute.
+        TestingImporter.source_code = 'attr = 42\nnew_attr = 123\n__name__ = {!r}'.format(TestingImporter.mutated_name)
+        self.assertIsInstance(module, util._LazyModule)
+
+        # Reload the module (should be a no-op since not materialized).
+        reloaded = importlib.reload(module)
+        self.assertIs(reloaded, module)
+        self.assertIsInstance(module, util._LazyModule)
+
+        # Access the new attribute (should trigger materialization, and new_attr should exist).
+        self.assertEqual(module.attr, 42)
+        self.assertNotIsInstance(module, util._LazyModule)
+        self.assertTrue(hasattr(module, 'new_attr'))
+        self.assertEqual(module.new_attr, 123)
+
 
 if __name__ == '__main__':
     unittest.main()

diff --git a/Misc/NEWS.d/next/Library/2025-10-09-15-46-18.gh-issue-139686.XwIZB2.rst b/Misc/NEWS.d/next/Library/2025-10-09-15-46-18.gh-issue-139686.XwIZB2.rst
new file mode 100644 (file)
index 0000000..00dd344
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2025-10-09-15-46-18.gh-issue-139686.XwIZB2.rst
@@ -0,0 +1 @@
+Make importlib.reload no-op for lazy modules.