gh-92041: Preserve getmodule filename fallback

Restore filename-based module resolution when direct frame-globals lookup cannot prove ownership. Avoid repeated full sys.modules scans while its module names are unchanged.

Author: mdeck

Lib/inspect.py

@@ -925,6 +925,34 @@ def getabsfile(object, _filename=None):
 
 modulesbyfile = {}
 _filesbymodname = {}
+_modulesbyfile_snapshot = None
+
+
+def _getframemodule(frame, _filename=None):
+    """Return a module owned by a frame's globals, or None if not found."""
+    frame_globals = frame.f_globals
+    module_name = frame_globals.get('__name__')
+    if not isinstance(module_name, str):
+        return None
+    module = sys.modules.get(module_name)
+    if not (ismodule(module) and module.__dict__ is frame_globals):
+        return None
+    module_file = getattr(module, '__file__', None)
+    if module_file is None:
+        return None
+    try:
+        file = getabsfile(frame, _filename)
+    except (TypeError, FileNotFoundError):
+        return None
+    if frame.f_code.co_filename == module_file:
+        return module
+    try:
+        module_file = getabsfile(module)
+    except (TypeError, FileNotFoundError):
+        return None
+    if file == module_file or file == os.path.realpath(module_file):
+        return module
+
 
 def getmodule(object, _filename=None):
     """Return the module an object was defined in, or None if not found."""
@@ -938,29 +966,9 @@ def getmodule(object, _filename=None):
         # Frame globals identify the execution namespace directly. Preserve
         # the private filename override when it names a different file.
         if _filename is None or _filename == object.f_code.co_filename:
-            object_globals = object.f_globals
-            module_name = object_globals.get('__name__')
-            if not isinstance(module_name, str):
-                return None
-            module = sys.modules.get(module_name)
-            if not (ismodule(module) and module.__dict__ is object_globals):
-                return None
-            module_file = getattr(module, '__file__', None)
-            if module_file is None:
-                return None
-            try:
-                file = getabsfile(object, _filename)
-            except (TypeError, FileNotFoundError):
-                return None
-            if object.f_code.co_filename == module_file:
-                return module
-            try:
-                module_file = getabsfile(module)
-            except (TypeError, FileNotFoundError):
-                return None
-            if file == module_file or file == os.path.realpath(module_file):
+            module = _getframemodule(object, _filename)
+            if module is not None:
                 return module
-            return None
 
     # Try the filename to modulename cache
     if _filename is not None and _filename in modulesbyfile:
@@ -972,19 +980,33 @@ def getmodule(object, _filename=None):
         return None
     if file in modulesbyfile:
         return sys.modules.get(modulesbyfile[file])
-    # Update the filename to module name cache and check yet again
-    # Copy sys.modules in order to cope with changes while iterating
-    for modname, module in sys.modules.copy().items():
-        if ismodule(module) and hasattr(module, '__file__'):
-            f = module.__file__
-            if f == _filesbymodname.get(modname, None):
-                # Have already mapped this module, so skip it
-                continue
-            _filesbymodname[modname] = f
-            f = getabsfile(module)
-            # Always map to the name the module knows itself by
-            modulesbyfile[f] = modulesbyfile[
-                os.path.realpath(f)] = module.__name__
+    # Update the filename to module name cache only when sys.modules is
+    # replaced or its module names have changed since the previous scan.
+    # Retaining module values in the snapshot would keep removed modules alive.
+    global _modulesbyfile_snapshot
+    modules = sys.modules
+    modules_id = id(modules)
+    try:
+        snapshot = (modules_id, tuple(modules))
+    except RuntimeError:
+        # The mapping changed while its keys were being copied.
+        snapshot = None
+    if snapshot is None or snapshot != _modulesbyfile_snapshot:
+        # Copy sys.modules in order to cope with changes while iterating.
+        modules = modules.copy()
+        snapshot = (modules_id, tuple(modules))
+        for modname, module in modules.items():
+            if ismodule(module) and hasattr(module, '__file__'):
+                f = module.__file__
+                if f == _filesbymodname.get(modname, None):
+                    # Have already mapped this module, so skip it
+                    continue
+                _filesbymodname[modname] = f
+                f = getabsfile(module)
+                # Always map to the name the module knows itself by
+                modulesbyfile[f] = modulesbyfile[
+                    os.path.realpath(f)] = module.__name__
+        _modulesbyfile_snapshot = snapshot
     if file in modulesbyfile:
         return sys.modules.get(modulesbyfile[file])
     # Check the main module

Lib/test/libregrtest/utils.py

@@ -296,6 +296,7 @@ def clear_caches():
         inspect._shadowed_dict_from_weakref_mro_tuple.cache_clear()
         inspect._filesbymodname.clear()
         inspect.modulesbyfile.clear()
+        inspect._modulesbyfile_snapshot = None
 
     try:
         importlib_metadata = sys.modules['importlib.metadata']

Lib/test/test_inspect/test_inspect.py

@@ -844,32 +844,142 @@ def test_getmodule(self):
                           sys.modules[__name__])
 
     def test_getmodule_unregistered_exec_frame(self):
-        def exec_namespace(namespace):
+        def exec_namespace(namespace, filename, expected):
             exec(compile(textwrap.dedent("""
                 frame = inspect.currentframe()
                 try:
                     1 / 0
                 except ZeroDivisionError as error:
                     traceback = error.__traceback__
-            """), modfile, "exec"), namespace)
-            self.assertIsNone(inspect.getmodule(namespace["frame"]))
-            self.assertIsNone(inspect.getmodule(namespace["traceback"]))
-
-        # Missing and invalid module names identify no registered namespace.
-        exec_namespace({"inspect": inspect})
-        exec_namespace({"inspect": inspect, "__name__": []})
-
-        module_name = f"{__name__}.not_registered"
-        for module in (None, object(), types.ModuleType(module_name)):
-            with self.subTest(module=module):
-                sys.modules[module_name] = module
-                try:
-                    exec_namespace({
-                        "inspect": inspect,
-                        "__name__": module_name,
-                    })
-                finally:
-                    del sys.modules[module_name]
+            """), filename, "exec"), namespace)
+            self.assertIs(inspect.getmodule(namespace["frame"]), expected)
+            self.assertIs(
+                inspect.getmodule(namespace["frame"].f_code), expected)
+            self.assertIs(inspect.getmodule(namespace["traceback"]), expected)
+
+        with (unittest.mock.patch.object(inspect, "modulesbyfile", {}),
+              unittest.mock.patch.object(inspect, "_filesbymodname", {}),
+              unittest.mock.patch.object(
+                  inspect, "_modulesbyfile_snapshot", None)):
+            # Preserve filename-based resolution when the execution namespace
+            # does not identify the module that supplied the source.
+            exec_namespace({"inspect": inspect}, modfile, mod)
+            exec_namespace({"inspect": inspect, "__name__": []},
+                           modfile, mod)
+
+            module_name = f"{__name__}.not_registered"
+            for module in (None, object(), types.ModuleType(module_name)):
+                with self.subTest(module=module):
+                    sys.modules[module_name] = module
+                    try:
+                        exec_namespace({
+                            "inspect": inspect,
+                            "__name__": module_name,
+                        }, modfile, mod)
+                    finally:
+                        del sys.modules[module_name]
+
+            # A namespace and filename with no registered module still
+            # resolves to None after the filename fallback.
+            with temp_cwd() as cwd:
+                filename = os.path.join(cwd, "not_registered.py")
+                exec_namespace({"inspect": inspect}, filename, None)
+
+    def test_getmodule_skips_unchanged_module_rescan(self):
+        with temp_cwd() as cwd:
+            filename = os.path.join(cwd, "not_registered.py")
+            namespace = {"inspect": inspect}
+            exec(compile("frame = inspect.currentframe()", filename, "exec"),
+                 namespace)
+            frame = namespace["frame"]
+            modules = sys.modules.copy()
+            module_name = f"{__name__}.late_registered"
+            marker_name = f"{__name__}.scan_marker"
+            marker = types.ModuleType(marker_name)
+            marker.__file__ = os.path.join(cwd, "scan_marker.py")
+            with open(marker.__file__, "w"):
+                pass
+            modules[marker_name] = marker
+
+            original_ismodule = inspect.ismodule
+            scan_count = 0
+
+            def ismodule(object):
+                nonlocal scan_count
+                if object is marker:
+                    scan_count += 1
+                return original_ismodule(object)
+
+            with (unittest.mock.patch.object(sys, "modules", modules),
+                  unittest.mock.patch.object(inspect, "modulesbyfile", {}),
+                  unittest.mock.patch.object(inspect, "_filesbymodname", {}),
+                  unittest.mock.patch.object(inspect, "ismodule", ismodule),
+                  unittest.mock.patch.object(
+                      inspect, "_modulesbyfile_snapshot", None)):
+                self.assertIsNone(inspect.getmodule(frame, filename))
+                first_scan_count = scan_count
+                self.assertGreater(first_scan_count, 0)
+                self.assertIsNone(inspect.getmodule(frame, filename))
+                self.assertEqual(scan_count, first_scan_count)
+
+                module = types.ModuleType(module_name)
+                module.__file__ = filename
+                modules[module_name] = module
+                self.assertIs(inspect.getmodule(frame.f_code), module)
+                self.assertGreater(scan_count, first_scan_count)
+                second_scan_count = scan_count
+
+                # A replacement sys.modules object must invalidate the
+                # snapshot even when it contains the same entries.
+                replacement = modules.copy()
+                unknown = os.path.join(cwd, "unknown.py")
+                with unittest.mock.patch.object(sys, "modules", replacement):
+                    self.assertIsNone(inspect.getmodule(None, unknown))
+                    self.assertGreater(scan_count, second_scan_count)
+
+    def test_getmodule_sys_modules_changes_during_key_snapshot(self):
+        class MutatingModules(dict):
+            mutate = True
+
+            def __iter__(self):
+                iterator = super().__iter__()
+                yield next(iterator)
+                if self.mutate:
+                    self.mutate = False
+                    self[f"{__name__}.added_during_iteration"] = None
+                yield from iterator
+
+        modules = MutatingModules(sys.modules)
+        with (temp_cwd() as cwd,
+              unittest.mock.patch.object(sys, "modules", modules),
+              unittest.mock.patch.object(inspect, "modulesbyfile", {}),
+              unittest.mock.patch.object(inspect, "_filesbymodname", {}),
+              unittest.mock.patch.object(
+                  inspect, "_modulesbyfile_snapshot", None)):
+            filename = os.path.join(cwd, "not_registered.py")
+            self.assertIsNone(inspect.getmodule(None, filename))
+
+    def test_getmodule_snapshot_does_not_retain_modules(self):
+        with temp_cwd() as cwd:
+            module_name = f"{__name__}.snapshot_module"
+            module = types.ModuleType(module_name)
+            module.__file__ = os.path.join(cwd, "snapshot_module.py")
+            with open(module.__file__, "w"):
+                pass
+            module_ref = weakref.ref(module)
+            modules = sys.modules.copy()
+            modules[module_name] = module
+
+            with (unittest.mock.patch.object(sys, "modules", modules),
+                  unittest.mock.patch.object(inspect, "modulesbyfile", {}),
+                  unittest.mock.patch.object(inspect, "_filesbymodname", {}),
+                  unittest.mock.patch.object(
+                      inspect, "_modulesbyfile_snapshot", None)):
+                self.assertIs(inspect.getmodule(None, module.__file__), module)
+                del modules[module_name]
+                del module
+                support.gc_collect()
+                self.assertIsNone(module_ref())
 
     def test_getmodule_registered_exec_frame(self):
         def exec_module(module, filename):
@@ -902,8 +1012,24 @@ def exec_module(module, filename):
                 self.assertIsNone(inspect.getmodule(module.frame))
                 self.assertIsNone(inspect.getmodule(module.traceback))
 
-                # Preserve the existing result for fileless modules while
-                # avoiding a scan of sys.modules.
+                # If another module supplied the source, fall back to the
+                # filename-based lookup instead of trusting frame globals.
+                source_name = f"{module_name}.source"
+                source_module = types.ModuleType(source_name)
+                source_module.__file__ = filename + ".source"
+                with open(source_module.__file__, "w"):
+                    pass
+                sys.modules[source_name] = source_module
+                try:
+                    exec_module(module, source_module.__file__)
+                    self.assertIs(inspect.getmodule(module.frame),
+                                  source_module)
+                    self.assertIs(inspect.getmodule(module.traceback),
+                                  source_module)
+                finally:
+                    del sys.modules[source_name]
+
+                # Preserve the existing result for fileless modules.
                 del module.__file__
                 exec_module(module, "<fileless>")
                 self.assertIsNone(inspect.getmodule(module.frame))

Lib/test/test_zipimport_support.py

@@ -10,6 +10,7 @@
 import zipfile
 import zipimport
 import doctest
+import importlib
 import inspect
 import linecache
 import unittest
@@ -96,6 +97,36 @@ def test_inspect_getsource_issue4223(self):
             finally:
                 del sys.modules["zip_pkg"]
 
+    def test_inspect_fresh_namespace_uses_module_loader(self):
+        test_src = textwrap.dedent("""\
+            import inspect
+
+            def capture():
+                return inspect.currentframe()
+
+            frame = capture()
+        """)
+        expected_source = textwrap.dedent("""\
+            def capture():
+                return inspect.currentframe()
+        """)
+        module_name = "test_zipped_inspect"
+        with os_helper.temp_dir() as d:
+            script_name = make_script(d, module_name, test_src)
+            zip_name, _ = make_zip_script(d, "test_zip", script_name)
+            os.remove(script_name)
+            sys.path.insert(0, zip_name)
+            module = importlib.import_module(module_name)
+            try:
+                namespace = {}
+                exec(compile(test_src, module.__file__, "exec"), namespace)
+                frame = namespace["frame"]
+
+                self.assertIs(inspect.getmodule(frame), module)
+                self.assertEqual(inspect.getsource(frame), expected_source)
+            finally:
+                del sys.modules[module_name]
+
     def test_doctest_issue4197(self):
         # To avoid having to keep two copies of the doctest module's
         # unit tests in sync, this test works by taking the source of

Misc/NEWS.d/next/Library/2026-08-14-16-30-00.gh-issue-92041.kD7pQm.rst

@@ -1 +1 @@
-Improve :func:`inspect.getmodule` performance for frame and traceback objects by resolving registered modules directly from frame globals. Frames executing in unregistered globals now return ``None`` instead of being associated with a module solely by filename.
+Improve :func:`inspect.getmodule` performance for frame and traceback objects by resolving registered modules directly from frame globals and avoiding repeated full scans when the names in :data:`sys.modules` are unchanged.