# Add \`PyUnstable\_InterpreterFrame\_GetLocals()\`: read a frame’s locals from the interpreter-frame C API

**URL:** <https://discuss.python.org/t/add-pyunstable-interpreterframe-getlocals-read-a-frame-s-locals-from-the-interpreter-frame-c-api/108520>\
**Category:** C API\
**Created:** [August 12, 2026, 3:21am UTC](https://discuss.python.org/t/add-pyunstable-interpreterframe-getlocals-read-a-frame-s-locals-from-the-interpreter-frame-c-api/108520 "2026-08-12T03:21:13Z")\
**Posts on this page:** 1\
**Showing post:** 7

<div class="post-metadata">

**Author:** ![encukou](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/encukou/32/2461_2.png) [@encukou](https://discuss.python.org/u/encukou)\
**Post date:** [August 19, 2026, 8:07am UTC](https://discuss.python.org/t/add-pyunstable-interpreterframe-getlocals-read-a-frame-s-locals-from-the-interpreter-frame-c-api/108520/7 "2026-08-19T08:07:54Z")

</div>

> [@guilhermeleobas](#):
>
> `PyFrame_GetLocals` can be a bit slow:\

If that’s the only issue we could add a `PyFrame_GetVarByIndex` (after [`PyFrame_GetVar`](https://docs.python.org/3/c-api/frame.html#c.PyFrame_GetVar).)

> [@guilhermeleobas](#):
>
> [getting one local at a time] works for us. Dynamo do materialize all the locals today, but that’s mostly a consequence of how the code is written than a hard requirement. I’ll switch the proposal to `PyUnstable_InterpreterFrame_GetLocal(frame, idx)`.

Sounds good.

> [@guilhermeleobas](#):
>
> One other question, should I introduce the opaque `InterpreterFrame` typedef?

Nah, that can go in a different PR.

* * *

> [@steve.dower](#):
>
> Pretty sure [keeping `_PyInterpreterFrame` underscored] is just the result of not doing a broad rename of everything that existed prior to inventing `PyUnstable`. For the sake of not breaking existing code, I wouldn’t bother.

Guess this is related to your [post from an unrelated thread](https://discuss.python.org/t/pep-842-postmortem-how-do-we-protect-the-standard-library/108575/39): _“The unavoidable premise is that the docs are the definitive source of truth on what’s “public” (aka. intended to be used), because that’s how it’s always been done.”_

Except… that’s not unavoidable, and I think that in the C API, we _can_ get to a state where the leading underscore means “don’t touch”. Adding `PyUnstable` versions for documented-but-underscored API has been argued, and even approved in PEP 689. Also, PEP 387 very explicitly excludes underscored names from public API.

For the sake of not breaking existing code, we can soft-deprecate the old name instead of using `Py_DEPRECATED`.

---

_[View the full topic](https://discuss.python.org/t/add-pyunstable-interpreterframe-getlocals-read-a-frame-s-locals-from-the-interpreter-frame-c-api/108520)._