gh-92041: Address frame lookup review and document cache precedence

Author: mdeck

Doc/library/inspect.rst

@@ -771,6 +771,16 @@ Retrieving source code
    Try to guess which module an object was defined in. Return ``None``
    if the module cannot be determined.
 
+   .. versionchanged:: 3.16
+      On a filename-cache miss, frames and tracebacks may be resolved from
+      a registered module whose global namespace and canonical filename match
+      the frame. Existing filename-cache entries retain precedence. If multiple
+      modules share a filename, the result may differ from earlier Python
+      versions and can depend on previous lookups: the frame's globals owner
+      is not guaranteed to take precedence. Code objects continue to use
+      filename-based lookup and can also be affected by earlier frame or
+      traceback lookups.
+
 
 .. function:: getsourcefile(object)
 

Lib/inspect.py

@@ -936,16 +936,17 @@ def _getframemodule(frame, filename):
     if type(name) is not str:
         return None
     module = sys.modules.get(name)
-    # Leave dynamic module metadata to the existing filename fallback.
-    if (type(module) is not types.ModuleType or
-            module.__dict__ is not namespace or '__getattr__' in namespace or
-            type(namespace.get('__file__')) is not str):
+    # Leave module subclasses and dynamically supplied filenames to the fallback.
+    if (type(module) is not types.ModuleType
+        or module.__dict__ is not namespace
+        or type(namespace.get('__file__')) is not str):
         return None
     try:
         if filename == getabsfile(module):
             return module
-    except (TypeError, FileNotFoundError):
+    except FileNotFoundError, TypeError:
         pass
+    return None
 
 
 def getmodule(object, _filename=None):
@@ -965,8 +966,12 @@ def getmodule(object, _filename=None):
         return None
     if file in modulesbyfile:
         return sys.modules.get(modulesbyfile[file])
-    frame = object if isframe(object) else (
-        object.tb_frame if istraceback(object) else None)
+    if isframe(object):
+        frame = object
+    elif istraceback(object):
+        frame = object.tb_frame
+    else:
+        frame = None
     if frame is not None and (
             _filename is None or _filename == frame.f_code.co_filename):
         module = _getframemodule(frame, file)

Lib/test/test_inspect/test_inspect.py

@@ -1090,6 +1090,76 @@ def test_filename_collision_uses_globals_owner(self):
             for object in (frame, traceback):
                 self.assertIs(inspect.getmodule(object), self.module)
 
+            # An unrelated miss scans the registry and can replace that entry.
+            self.assertIsNone(inspect.getmodule(
+                compile('pass', '<inspect-unrelated-miss>', 'exec')))
+            for object in (frame, traceback):
+                self.assertIs(inspect.getmodule(object), other)
+
+            # Bare code uses the filename map, including entries populated
+            # by an earlier frame lookup.
+            inspect.modulesbyfile.clear()
+            inspect._filesbymodname.clear()
+            self.assertIs(inspect.getmodule(frame.f_code), other)
+            inspect.modulesbyfile.clear()
+            inspect._filesbymodname.clear()
+            self.assertIs(inspect.getmodule(frame), self.module)
+            self.assertIs(inspect.getmodule(frame.f_code), self.module)
+
+    def test_static_filename_with_module_getattr_avoids_scan(self):
+        def module_getattr(name):
+            self.fail(f'unexpected module attribute lookup: {name}')
+
+        self.module.__getattr__ = module_getattr
+        frame, traceback = self.capture()
+
+        class NoScanDict(dict):
+            def copy(self):
+                raise AssertionError('registered frame scanned sys.modules')
+
+        with unittest.mock.patch.object(sys, 'modules', NoScanDict(sys.modules)):
+            for object in (frame, traceback):
+                inspect.modulesbyfile.clear()
+                inspect._filesbymodname.clear()
+                self.assertIs(inspect.getmodule(object), self.module)
+
+    def test_filename_supplied_by_module_getattr_falls_back(self):
+        del self.module.__file__
+
+        def module_getattr(name):
+            if name == '__file__':
+                return self.module.source
+            raise AttributeError(name)
+
+        self.module.__getattr__ = module_getattr
+        for suffix in ('.dynamic', '.changed'):
+            self.module.source = self.filename + suffix
+            frame, traceback = self.capture(filename=self.module.source)
+            for object in (frame, traceback):
+                inspect.modulesbyfile.clear()
+                inspect._filesbymodname.clear()
+                self.assertIs(inspect.getmodule(object), self.module)
+
+    def test_loader_supplied_by_module_getattr(self):
+        self.module.__file__ = self.filename + 'c'
+        del self.module.__loader__
+        loader = object()
+        requested = []
+
+        def module_getattr(name):
+            requested.append(name)
+            if name == '__loader__':
+                return loader
+            raise AttributeError(name)
+
+        self.module.__getattr__ = module_getattr
+        frame, traceback = self.capture()
+        for obj in (frame, traceback):
+            inspect.modulesbyfile.clear()
+            inspect._filesbymodname.clear()
+            self.assertIs(inspect.getmodule(obj), self.module)
+        self.assertIn('__loader__', requested)
+
     def test_unregistered_namespace_uses_filename_fallback(self):
         namespace = {'__name__': self.module.__name__}
         frame, traceback = self.capture(namespace)

Misc/NEWS.d/next/Library/2026-10-22-00-00-00.gh-issue-92041.frame.rst

@@ -1,3 +1,4 @@
-Speed up :func:`inspect.getmodule` for frames and tracebacks whose globals
-belong to a registered module with a matching filename. The globals owner
-takes precedence over unrelated modules sharing the same filename.
+Avoid scanning :data:`sys.modules` in :func:`inspect.getmodule` for an uncached
+frame or traceback whose globals identify a registered module with a matching
+canonical filename. Existing filename-cache entries retain precedence. When
+modules share a filename, results can depend on earlier lookups.