gh-141518: Add PyUnstable_InterpreterFrame_GetFrameObject() function

[vstinner]

Add also PyUnstable_InterpreterFrame type.

• Issue: [C API] Promote PEP 523 functions to public functions: add PyUnstable_InterpreterState_SetEvalFrameFunc() #141518

---

📚 Documentation preview 📚: https://cpython-previews--141950.org.readthedocs.build/

[vstinner]

See #141665 (review) for the rationale on adding this function.

[markshannon]

I don't think we should add PyUnstable_InterpreterFrame_GetFrameObject().

If someone wants a frame object, they can get it directly with sys._getframe() or the C API equivalent.
The whole point of using _PyInterpreterFrame is to avoid the overhead of creating a frame object.
Also, PyUnstable_InterpreterFrame_GetFrameObject() is not a simpler getter, but will often have to create the frame object.

[vstinner]

Well, @encukou requested such API for PyUnstable_InterpreterState_SetEvalFrameFunc(): #141665 (review)

[encukou]

sys._getframe() won't work in a frame evaluation function -- until the new frame is set up, it returns the previous one.

Should it be PyUnstable_InterpreterFrame_AsFrameObject?

[markshannon]

In a frame evaluation function, you don't want the frame object. It is just a bulkier, slower version of the frame you already have. The frame object contains no additional information, just a pointer back to the internal frame.

[vstinner]

In a frame evaluation function, you don't want the frame object

Yeah, you should use the internal C API to access the interpreter frame: pycore_interpframe.h provides many functions, such as:

• _PyFrame_GetCode()
• _PyFrame_GetBytecode()
• _PyFrame_GetFunction()
• _PyFrame_IsIncomplete()
• etc.

I know that it's kind of unusual to have a public function to set a frame evalution function, but need the internal C API to implement it.

[vstinner]

The C API Working Group decided to not add a public function for this feature, but keep the _Py name instead: capi-workgroup/decisions#89.