gh-156133: Add `PyUnstable_InterpreterFrame_GetLocal` by guilhermeleobas · Pull Request #156134 · python/cpython

guilhermeleobas · 2026-08-20T18:58:24Z

Add an unstable C API that reads a frame's local variables into a caller-provided array indexed by localsplus index, with cell and free variables unboxed to their contents. Free variables are resolved from the function closure, so the API also works on a frame that has not started executing (before COPY_FREE_VARS runs), which is the case that motivated it.

Includes the three PEP 689 deliverables:

reference documentation in Doc/c-api/frame.rst
a What's New entry for 3.16
and tests (a C wrapper in Modules/_testinternalcapi.c driven by Lib/test/test_capi/test_frame_getlocals.py covering plain locals, a cell variable, and a free variable).

Authored with the assistance of an AI coding agent (Claude Opus)

Issue: Add PyUnstable_InterpreterFrame_GetLocal to read a local var from an interp. frame #156133

python-cla-bot · 2026-08-20T18:58:28Z

All commit authors signed the Contributor License Agreement.

read-the-docs-community · 2026-08-20T19:21:56Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34951257 | 📁 Comparing a271e36 against main (83531fd)

🔍 Preview build

400 files changed · + 9 added · ± 391 modified

+ Added

± Modified

Add an unstable C API that returns a strong reference to a single local variable of an internal interpreter frame, addressed by its localsplus index, with cell and free variables unboxed to their contents. Free variables are resolved from the function closure, so the API also works on a frame that has not started executing (before COPY_FREE_VARS runs) -- the case that motivated it -- and it does not modify the frame. Includes the PEP 689 deliverables: reference documentation in Doc/c-api/frame.rst, a What's New entry for 3.16, a Misc/NEWS.d blurb, and tests in Lib/test/test_capi/test_misc.py (TestInternalFrameApi) covering plain locals, a cell variable, and a free variable. Authored with the assistance of an AI coding agent (Claude Opus)

guilhermeleobas · 2026-08-24T13:57:59Z

Thanks @aisk. I've addressed your comments.

aisk · 2026-08-24T14:32:05Z

Hi, thank you for the contribution, but please avoid using force push in the future, see: https://devguide.python.org/getting-started/pull-request-lifecycle/#don-t-force-push

guilhermeleobas · 2026-08-24T15:24:27Z

https://devguide.python.org/getting-started/pull-request-lifecycle/#don-t-force-push

Sorry, it won't happen again. I did because the e-mail used in the commit was wrong and the cla-bot was failing.

guilhermeleobas · 2026-09-16T18:52:37Z

@aisk could you take a look at this PR again once you have some cycles to spare?

ZeroIntensity · 2026-09-16T20:57:03Z

   .. versionadded:: 3.12
+
+
+.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetLocal(struct _PyInterpreterFrame *frame, Py_ssize_t index)


Ideally we should add an unstable API for the _PyInterpreterFrame struct too, right?

From the discuss topic, Petr said this can be done in a follow-up PR. I can add it here if you think it is necessary.

I'll defer to him :)

@encukou could you take a look at this PR once you have a chance?

I will, after the 3.15.0 release.

…me-getlocals

…emRef` convention

…me-getlocals

…t_of_range`) and unset variable (`get_get_local_unset`)

encukou

Thank you! I have a bunch of small nitpicks, hopehully the last batch.

encukou · 2026-10-07T13:19:44Z

+
+        with self.assertRaises(TypeError):
+            _testinternalcapi.code_get_localsplus_names(None)


This only exercises the test helper.

Suggested change

with self.assertRaises(TypeError):

_testinternalcapi.code_get_localsplus_names(None)

encukou · 2026-10-07T13:20:14Z

+    if (!PyCode_Check(arg)) {
+        PyErr_SetString(PyExc_TypeError, "argument must be a code object");
+        return NULL;
+    }


Suggested change

if (!PyCode_Check(arg)) {

PyErr_SetString(PyExc_TypeError, "argument must be a code object");

return NULL;

}

assert(PyCode_Check(arg));

encukou · 2026-10-07T13:35:16Z

+        self.assertEqual(d['a'], 3)
+        self.assertEqual(d['b'], 4)
+        self.assertEqual(d['c'], 7)
+        self.assertIs(d['self'], self)


We can test the whole dict at once.

Suggested change

self.assertEqual(d['a'], 3)

self.assertEqual(d['b'], 4)

self.assertEqual(d['c'], 7)

self.assertIs(d['self'], self)

self.assertEqual(d, {'a': 3, 'b': 4, 'c': 7, 'self': self})

encukou · 2026-10-07T13:39:19Z

+        # f has no cell or free variables, so co_nlocalsplus == co_nlocals.
+        code = f.__code__
+        self.assertFalse(code.co_cellvars or code.co_freevars)
+        nlocalsplus = code.co_nlocals
+        for index in (-1, nlocalsplus, nlocalsplus + 1):


This can be simpler now.

Suggested change

# f has no cell or free variables, so co_nlocalsplus == co_nlocals.

code = f.__code__

self.assertFalse(code.co_cellvars or code.co_freevars)

nlocalsplus = code.co_nlocals

for index in (-1, nlocalsplus, nlocalsplus + 1):

n = len(_testinternalcapi.code_get_localsplus_names(f.__code__))

for index in (-1, n, n + 1):

encukou · 2026-10-07T13:41:34Z

+        def f():
+            if False:
+                unset = 1
+            names = f.__code__.co_varnames


I'd prefer using the matching API

Suggested change

names = f.__code__.co_varnames

names = _testinternalcapi.code_get_localsplus_names(f.__code__)

encukou · 2026-10-07T13:48:51Z

+    if (frame == NULL) {
+        PyErr_SetString(PyExc_RuntimeError, "no caller frame");
+        return NULL;
+    }


Test functions can assert when they're used wrong.

Suggested change

if (frame == NULL) {

PyErr_SetString(PyExc_RuntimeError, "no caller frame");

return NULL;

}

assert(frame != NULL); // there must be a caller frame

encukou · 2026-10-07T13:50:18Z

+            return NULL;
+        }
+        if (rc == 0) {
+            continue;  // unset or hidden slot


Suggested change

continue; // unset or hidden slot

assert(value == NULL);

continue; // unset or hidden slot

encukou · 2026-10-07T13:51:19Z

+        if (rc < 0) {
+            Py_DECREF(names);
+            Py_DECREF(dict);
+            return NULL;


Suggested change

return NULL;

assert(value == NULL);

return NULL;

encukou · 2026-10-07T14:06:54Z

+   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`.


Suggested change

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`.

Return a :term:`strong reference` to a tuple of names of the local,

cell and free variables of a code object.

The names are in the same order as the values returned by

:c:func:`PyUnstable_InterpreterFrame_GetLocal`.

encukou · 2026-10-07T14:08:36Z

+   Retrieve the local variable at *index* in the frame's localsplus array, with
+   cell and free variables unboxed to their contents.  Free variables are
+   resolved from the function closure, so this also works on a frame that has
+   not started executing.


Suggested change

Retrieve the local variable at *index* in the frame's localsplus array, with

cell and free variables unboxed to their contents. Free variables are

resolved from the function closure, so this also works on a frame that has

not started executing.

Retrieve the local variable at *index*.

To determine the index of a particular variable, use

:c:func:`PyUnstable_InterpreterFrame_GetCode` and

:c:func:`PyUnstable_Code_GetLocalPlusNames`.

Cell and free variables are unboxed to their contents. Free variables are

resolved from the function closure, so this also works on a frame that has

not started executing.

guilhermeleobas requested review from AA-Turner, ZeroIntensity and markshannon as code owners August 20, 2026 18:58

bedevere-app Bot mentioned this pull request Aug 20, 2026

Add PyUnstable_InterpreterFrame_GetLocal to read a local var from an interp. frame #156133

Open

bedevere-app Bot added the awaiting review label Aug 20, 2026

guilhermeleobas force-pushed the guilhermeleobas/frame-getlocals branch 3 times, most recently from 049e1b3 to 9145c2f Compare August 20, 2026 19:16

aisk reviewed Aug 21, 2026

View reviewed changes

Comment thread Objects/frameobject.c Outdated

aisk reviewed Aug 21, 2026

View reviewed changes

Comment thread Modules/_testinternalcapi.c Outdated

aisk changed the title ~~gh-156133: Add PyUnstable_InterpreterFrame_GetLocals~~ gh-156133: Add PyUnstable_InterpreterFrame_GetLocal Aug 21, 2026

aisk reviewed Aug 21, 2026

View reviewed changes

Comment thread Objects/frameobject.c Outdated

guilhermeleobas added 2 commits August 24, 2026 13:50

Address reviewer comments

d29acd6

guilhermeleobas force-pushed the guilhermeleobas/frame-getlocals branch from cbb346a to d29acd6 Compare August 24, 2026 13:52

guilhermeleobas requested a review from aisk September 7, 2026 20:13

ZeroIntensity reviewed Sep 16, 2026

View reviewed changes

aisk reviewed Sep 17, 2026

View reviewed changes

Comment thread Doc/c-api/frame.rst Outdated

aisk reviewed Sep 17, 2026

View reviewed changes

Comment thread Doc/c-api/frame.rst Outdated

guilhermeleobas and others added 4 commits September 17, 2026 22:05

Merge remote-tracking branch 'upstream/main' into guilhermeleobas/fra…

892795b

…me-getlocals

use "next" in versionadded

f7f33ad

Update PyUnstable_InterpreterFrame_GetLocal to follow `PyDict_GetIt…

5075201

…emRef` convention

Merge remote-tracking branch 'upstream/main' into guilhermeleobas/fra…

442d8cd

…me-getlocals

bedevere-app Bot added the type-feature A feature request or enhancement label Oct 1, 2026

encukou reviewed Oct 2, 2026

View reviewed changes

Comment thread Doc/c-api/frame.rst

Comment thread Lib/test/test_capi/test_misc.py

guilhermeleobas added 2 commits October 5, 2026 15:03

Add and document PyUnstable_Code_GetLocalPlusNames

cd8b975

Add tests for -1, co_nlocalsplus indice (`test_get_local_index_ou…

a271e36

…t_of_range`) and unset variable (`get_get_local_unset`)

encukou reviewed Oct 7, 2026

View reviewed changes

		.. versionadded:: 3.12


		.. c:function:: PyObject* PyUnstable_InterpreterFrame_GetLocal(struct _PyInterpreterFrame *frame, Py_ssize_t index)


		with self.assertRaises(TypeError):
		_testinternalcapi.code_get_localsplus_names(None)

	names = f.__code__.co_varnames
	names = _testinternalcapi.code_get_localsplus_names(f.__code__)

	continue; // unset or hidden slot
	assert(value == NULL);
	continue; // unset or hidden slot

Conversation

guilhermeleobas commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

python-cla-bot Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

guilhermeleobas commented Aug 24, 2026

Uh oh!

aisk commented Aug 24, 2026

Uh oh!

guilhermeleobas commented Aug 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

guilhermeleobas commented Sep 16, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

guilhermeleobas Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

guilhermeleobas commented Aug 20, 2026 •

edited

Loading

python-cla-bot Bot commented Aug 20, 2026 •

edited

Loading

read-the-docs-community Bot commented Aug 20, 2026 •

edited

Loading

guilhermeleobas commented Aug 24, 2026 •

edited

Loading

guilhermeleobas Sep 17, 2026 •

edited

Loading