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

Proposal:

Add an unstable C API to read a single local variable of an internal interpreter frame by its localsplus index:

PyObject *
PyUnstable_InterpreterFrame_GetLocal(struct _PyInterpreterFrame *frame,
                                     Py_ssize_t index);

Returns a new strong reference, with cell and free variables unboxed to their contents. Free variables are resolved from the function closure, so it also works on a frame that has not started executing (before COPY_FREE_VARS). index outside [0, co_nlocalsplus) returns NULL with an IndexError set; an unset or hidden slot returns NULL with no exception set. The frame is not modified.

Motivation

TorchDynamo (PyTorch JIT compiler) relies on the eval frame API (PEP 523), and one of the things it needs to do when it intercepts a frame is to read the frame's local variables.

CPython has 3 public APIs for reading frame locals, but none of them are suitable to be used in Dynamo:

• PyFrame_GetLocals(PyFrameObject*)
• PyFrame_GetVar(PyFrameObject*, PyObject*)
• PyEval_GetFrameLocals(void)

The first two take a PyFrameObject* as first argument and there's no public way to get one from a _PyInterpreterFrame*. The last one (PyEval_GetFrameLocals) reads the current frame, and the frame might not be ready when Dynamo gets it.

So today PyTorch implements its own version of *_GetLocals, which relies on an interface that is fragile and hard to maintain.

Has this already been discussed elsewhere?

I have already discussed this feature proposal on Discourse

Links to previous discussion of this feature:

https://discuss.python.org/t/add-pyunstable-interpreterframe-getlocals-read-a-frame-s-locals-from-the-interpreter-frame-c-api/108520

Linked PRs

• gh-156134

首先查看链接的 PR gh-156134 和 Discourse 讨论，然后将提议的 PyUnstable_InterpreterFrame_GetLocal 行为与 PyTorch 的 framelocals_mapping.cpp 实现进行比较。当不稳定 C API 按照规范处理 localsplus 索引、cell 和 free 变量、未设置的槽位以及执行前的帧，并且具有适当的测试时，即视为完成。