bpo-46836: Add Doc/c-api/frame.rst

[vstinner]

Reorganize the documentation of the PyFrameObject C API.

https://bugs.python.org/issue46836

[vstinner]

My previous attempt to document PyFrameObject, in 2013: https://bugs.python.org/issue19431

[gvanrossum]

@markshannon ^^

[markshannon]

Thanks, it makes sense to more all the Frame API docs to one place.

I'd really like discourage extension code from accessing the internals of the frame, as the integrity of the VM relies on it in subtle ways.

[markshannon]

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.

[vstinner]

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.

[markshannon]

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.

[markshannon]

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)

[markshannon]

@vstinner
I'd like to get at least a minimal version of this merged, so I have somewhere to put the docs for new PyFrame C-API functions.

[markshannon]

Thanks.

[vstinner]

@kumaraditya303: Can you please propose a PR for your changes?

Mark needed this PR for his PR #32055 and so I merged my PR.

I removed the whole section about "public members" since they are confusing. I will propose a second PR to find a way to document them.

[kumaraditya303]

@kumaraditya303: Can you please propose a PR for your changes?

Sure, seems like github removed my comments as I was still adding suggestions and the PR got merged.