[issue19431] Document PyFrame_FastToLocals() and PyFrame_FastToLocalsWithError()

[Serhiy Storchaka]

Serhiy Storchaka <storchaka+cpython at gmail.com> added the comment:

frameobject.h is not included in any header file. Some effort was spent for avoiding including it in ceval.h, genobject.h, pystate.h and traceback.h. The whole content of frameobject.h is not available in the limited API. I'm not sure about the status of this API. This is not a very hight level API, but rather a very low level API. If document it, it should be documented on a separate page or on a page together with other low-level API.

> Serhiy: how are you supposed to modify local variables of a frame when these variables are stored in "fast locals"?

Currently you should call PyFrame_FastToLocalsWithError(), modify directly f_locals, and call PyFrame_LocalsToFast(). This is very low-level manipulation. It exposes implementation details (at least you need to access PyFrameObject attributes directly). It should be documented that the most of PyFrame_* API is low-level and implementation specific. PyFrame_GetLineNumber() is an exception.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue19431>
_______________________________________