GeezerVison

It would be much safer to just say "don't access fields directly".

For example, f_lineno is not valid most of the time, we use it as an internal cache when tracing. f_back can be NULL even if the Python attribute is not None. Setting f_trace_lines or f_trace_opcodes may not do anything, as the change won't visible to the VM.

I updated the PR to clarify that these members are part of the Python API. My idea is just to explain that the Python API can be accessed in C as well.

Setting f_trace_lines or f_trace_opcodes may not do anything, as the change won't visible to the VM.

Well, it's technically possible to do that in pure Python. If there is a bug, it should be either documented or fixed. For example, disallow setting f_trace_lines and f_trace_opcodes.

Currently, f_trace_lines and f_trace_opcodes are not documented. IMO it's better to document them. If there are limits, we can document them.

The struct fields cannot be safely accessed by C code. The limit is that you can't do it.
The Python attributes can be safely modified by PyObject_GetAttr etc.

Given that this is the C API docs, any reference to Python attributes is likely to be misread as referring to C struct fields, so it is best not to list the Python attributes here.

Could you list the C API functions, PyFrame_GetLineNumber, etc, first?
I'll add docs to the new accessors here, as I add them.

Then add a comment that Python-level attributes can be accessed by PyObject_GetAttr[String] and PyObject_SetAttr[String] with an example:

E.g. PyObject_GetAttrString(frame, "f_lineno") is equivalent to PyFrame_GetLineNumber(frame)