Add `PyUnstable_InterpreterFrame_GetLocals()`: read a frame’s locals from the interpreter-frame C API

[encukou (Petr Viktorin)]

@guilhermeleobas

PyFrame_GetLocals can be a bit slow:\

If that’s the only issue we could add a PyFrame_GetVarByIndex (after 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: “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.