gh-86682: Adds sys._getframemodulename as a lightweight alternative to _getframe

Doc/library/sys.rst

@@ -787,6 +787,21 @@ always available.
    .. versionadded:: 3.2
 
 
+.. function:: _getcaller([depth])
+
+   Return a function object from the call stack.  If optional integer *depth* is
+   given, return the frame object that many calls below the top of the stack.  If
+   that is deeper than the call stack, :exc:`ValueError` is raised.  The default
+   for *depth* is zero, returning the function at the top of the call stack.
+
+   .. audit-event:: sys._getcaller depth sys._getcaller
+
+   .. impl-detail::
+
+      This function should be used for internal and specialized purposes only.
+      It is not guaranteed to exist in all implementations of Python.
+
+
 .. function:: _getframe([depth])
 
    Return a frame object from the call stack.  If optional integer *depth* is

Lib/collections/__init__.py

@@ -507,9 +507,12 @@ def __getnewargs__(self):
     # specified a particular module.
     if module is None:
         try:
-            module = _sys._getframe(1).f_globals.get('__name__', '__main__')
-        except (AttributeError, ValueError):
-            pass
+            module = getattr(_sys._getcaller(1), '__module__', '__main__')
+        except AttributeError:
+            try:
+                module = _sys._getframe(1).f_globals.get('__name__', '__main__')
+            except (AttributeError, ValueError):
+                pass
     if module is not None:
         result.__module__ = module
 

Lib/doctest.py

@@ -207,7 +207,12 @@ def _normalize_module(module, depth=2):
     elif isinstance(module, str):
         return __import__(module, globals(), locals(), ["*"])
     elif module is None:
-        return sys.modules[sys._getframe(depth).f_globals['__name__']]
+        try:
+            caller = sys._getcaller(depth)
+        except AttributeError:
+            return sys.modules[sys._getframe(depth).f_globals['__name__']]
+        else:
+            return sys.modules[caller.__module__]
     else:
         raise TypeError("Expected a module, string, or None")
 

Lib/enum.py

@@ -860,13 +860,15 @@ def _create_(cls, class_name, names, *, module=None, qualname=None, type=None, s
                 member_name, member_value = item
             classdict[member_name] = member_value
 
-        # TODO: replace the frame hack if a blessed way to know the calling
-        # module is ever developed
         if module is None:
             try:
-                module = sys._getframe(2).f_globals['__name__']
-            except (AttributeError, ValueError, KeyError):
-                pass
+                module = getattr(sys._getcaller(2), '__module__', None)
+            except AttributeError:
+                # Fall back on _getframe if _getcaller is missing
+                try:
+                    module = sys._getframe(2).f_globals['__name__']
+                except (AttributeError, ValueError, KeyError):
+                    pass
         if module is None:
             _make_class_unpicklable(classdict)
         else:

Lib/test/audit-tests.py

@@ -419,6 +419,17 @@ def hook(event, args):
     sys._getframe()
 
 
+def test_sys_getcaller():
+    import sys
+
+    def hook(event, args):
+        if event.startswith("sys."):
+            print(event, *args)
+
+    sys.addaudithook(hook)
+    sys._getcaller()
+
+
 def test_wmi_exec_query():
     import _wmi
 

Lib/test/test_audit.py

@@ -186,6 +186,18 @@ def test_sys_getframe(self):
 
         self.assertEqual(actual, expected)
 
+    def test_sys_getcaller(self):
+        returncode, events, stderr = self.run_python("test_sys_getcaller")
+        if returncode:
+            self.fail(stderr)
+
+        if support.verbose:
+            print(*events, sep='\n')
+        actual = [(ev[0], ev[2]) for ev in events]
+        expected = [("sys._getcaller", "0")]
+
+        self.assertEqual(actual, expected)
+
     def test_wmi_exec_query(self):
         import_helper.import_module("_wmi")
         returncode, events, stderr = self.run_python("test_wmi_exec_query")

Lib/test/test_sys.py

@@ -399,6 +399,24 @@ def test_getframe(self):
             is sys._getframe().f_code
         )
 
+    def test_getcaller(self):
+        # Default depth gets ourselves
+        func = type(self).test_getcaller
+        self.assertIs(func, sys._getcaller())
+
+        def get_1(d):
+            return sys._getcaller(d)
+
+        def get_2(d):
+            return get_1(d)
+
+        self.assertIs(get_1, get_1(0))
+        self.assertIs(func, get_1(1))
+
+        self.assertIs(get_1, get_2(0))
+        self.assertIs(get_2, get_2(1))
+        self.assertIs(func, get_2(2))
+
     # sys._current_frames() is a CPython-only gimmick.
     @threading_helper.reap_threads
     @threading_helper.requires_working_threading()

Lib/typing.py

@@ -1942,11 +1942,15 @@ def _no_init_or_replace_init(self, *args, **kwargs):
 
 
 def _caller(depth=1, default='__main__'):
+    try:
+        return getattr(sys._getcaller(depth + 1), '__module__', default)
+    except AttributeError:  # For platforms without _getcaller()
+        pass
     try:
         return sys._getframe(depth + 1).f_globals.get('__name__', default)
     except (AttributeError, ValueError):  # For platforms without _getframe()
-        return None
-
+        pass
+    return None
 
 def _allow_reckless_class_checks(depth=3):
     """Allow instance and class checks for special stdlib modules.

Misc/NEWS.d/next/Library/2022-11-15-23-30-39.gh-issue-86682.gK9i1N.rst

@@ -0,0 +1,2 @@
+Changes internal function used to ensure runtime-created collections have
+the correct module name from :func:`sys._getframe` to :func:`sys._getcaller`.

Python/sysmodule.c

@@ -2180,6 +2180,42 @@ sys_is_stack_trampoline_active_impl(PyObject *module)
 }
 
 
+/*[clinic input]
+sys._getcaller
+
+    depth: int = 0
+
+Return the calling function object.
+
+The default depth returns the function containing the call to this API.
+A more typical use in a library will pass a depth of 1 to get the user's
+function rather than the library module.
+[clinic start generated code]*/
+
+static PyObject *
+sys__getcaller_impl(PyObject *module, int depth)
+/*[clinic end generated code: output=250f47adb2372e4a input=1993a1558597f1ed]*/
+{
+    if (PySys_Audit("sys._getcaller", "i", depth) < 0) {
+        return NULL;
+    }
+    _PyInterpreterFrame *f = _PyThreadState_GET()->cframe->current_frame;
+    while (f && (f->owner == FRAME_OWNED_BY_CSTACK || depth-- > 0)) {
+        f = f->previous;
+    }
+    if (f == NULL) {
+        Py_RETURN_NONE;
+    }
+    return Py_NewRef(f->f_funcobj);
+    PyObject *r = PyDict_GetItemWithError(f->f_globals, &_Py_ID(__name__));
+    if (!r) {
+        PyErr_Clear();
+        r = Py_None;
+    }
+    return Py_NewRef(r);
+}
+
+
 static PyMethodDef sys_methods[] = {
     /* Might as well keep this in alphabetic order */
     SYS_ADDAUDITHOOK_METHODDEF
@@ -2207,6 +2243,7 @@ static PyMethodDef sys_methods[] = {
     SYS_GETRECURSIONLIMIT_METHODDEF
     {"getsizeof", _PyCFunction_CAST(sys_getsizeof),
      METH_VARARGS | METH_KEYWORDS, getsizeof_doc},
+    SYS__GETCALLER_METHODDEF
     SYS__GETFRAME_METHODDEF
     SYS_GETWINDOWSVERSION_METHODDEF
     SYS__ENABLELEGACYWINDOWSFSENCODING_METHODDEF