Add and document PyUnstable_Code_GetLocalPlusNames

Author: guilhermeleobas

Doc/c-api/code.rst

@@ -44,6 +44,15 @@ bound into a function.
       The old name is deprecated, but will remain available until the
       signature changes again.
 
+.. c:function:: PyObject* PyUnstable_Code_GetLocalPlusNames(PyCodeObject *co)
+
+   Return a new :term:`strong reference` to the tuple of names of the local,
+   cell and free variables of a code object.  The tuple is indexed like the
+   *localsplus* array of a frame, so it can be used together with
+   :c:func:`PyUnstable_InterpreterFrame_GetLocal`.
+
+   .. versionadded:: next
+
 .. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, PyObject *qualname, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
 
    Return a new code object.  If you need a dummy code object to create a frame,

Doc/whatsnew/3.16.rst

@@ -1178,7 +1178,9 @@ New features
   (Contributed by Victor Stinner in :gh:`148233`.)
 
 * Add :c:func:`PyUnstable_InterpreterFrame_GetLocal` to read a local variable
-  of an internal interpreter frame by its localsplus index.
+  of an internal interpreter frame by its localsplus index, and
+  :c:func:`PyUnstable_Code_GetLocalPlusNames` to get the matching variable
+  names.
   (Contributed by Guilherme Leobas in :gh:`156133`.)
 
 Porting to Python 3.16

Include/cpython/code.h

@@ -177,6 +177,11 @@ static inline int PyUnstable_Code_GetFirstFree(PyCodeObject *op) {
     return op->co_nlocalsplus - op->co_nfreevars;
 }
 
+static inline PyObject *PyUnstable_Code_GetLocalPlusNames(PyCodeObject *op) {
+    assert(PyCode_Check(op));
+    return Py_NewRef(op->co_localsplusnames);
+}
+
 Py_DEPRECATED(3.13) static inline int PyCode_GetFirstFree(PyCodeObject *op) {
     return PyUnstable_Code_GetFirstFree(op);
 }

Lib/test/test_capi/test_misc.py

@@ -2837,6 +2837,30 @@ def inner():
         self.assertEqual(d['z'], 7)
 
 
+    def test_code_get_localsplus_names(self):
+        def outer(a, b):
+            c = a
+            def inner():
+                return a, d
+            d = b
+            return inner
+
+        names = _testinternalcapi.code_get_localsplus_names(outer.__code__)
+        self.assertIsInstance(names, tuple)
+        # Arguments and locals come first, followed by cells that are not
+        # arguments; here a and d are cells.
+        self.assertEqual(sorted(names), sorted(['a', 'b', 'c', 'd', 'inner']))
+        self.assertEqual(names[:2], ('a', 'b'))
+
+        inner = outer(1, 2)
+        names = _testinternalcapi.code_get_localsplus_names(inner.__code__)
+        self.assertEqual(names, ('a', 'd'))
+        self.assertEqual(names[inner.__code__.co_nlocals:], ('a', 'd'))
+
+        with self.assertRaises(TypeError):
+            _testinternalcapi.code_get_localsplus_names(None)
+
+
 SUFFICIENT_TO_DEOPT_AND_SPECIALIZE = 100
 
 class Test_Pep523API(unittest.TestCase):

Misc/NEWS.d/next/C_API/2026-08-20-12-00-00.gh-issue-156133.GetLoc.rst

@@ -1,2 +1,3 @@
 Add :c:func:`PyUnstable_InterpreterFrame_GetLocal` to read a local variable of
-an internal interpreter frame by its localsplus index.
+an internal interpreter frame by its localsplus index, and
+:c:func:`PyUnstable_Code_GetLocalPlusNames` to get the matching variable names.

Modules/_testinternalcapi.c

@@ -1553,24 +1553,28 @@ get_frame_locals(PyObject *self, PyObject *Py_UNUSED(ignored))
     if (dict == NULL) {
         return NULL;
     }
+    PyObject *names = PyUnstable_Code_GetLocalPlusNames(co);
     for (Py_ssize_t i = 0; i < n; i++) {
         PyObject *value;
         int rc = PyUnstable_InterpreterFrame_GetLocal(frame, i, &value);
         if (rc < 0) {
+            Py_DECREF(names);
             Py_DECREF(dict);
             return NULL;
         }
         if (rc == 0) {
             continue;  // unset or hidden slot
         }
-        PyObject *name = PyTuple_GET_ITEM(co->co_localsplusnames, i);
+        PyObject *name = PyTuple_GET_ITEM(names, i);
         int err = PyDict_SetItem(dict, name, value);
         Py_DECREF(value);
         if (err < 0) {
+            Py_DECREF(names);
             Py_DECREF(dict);
             return NULL;
         }
     }
+    Py_DECREF(names);
     return dict;
 }