bpo-45431: Rename CFrame to _PyCFrame in the C API

[vstinner]

Rename also struct _cframe to struct _PyCFrame.

Add a comment suggesting using public functions rather than using
directly the private _PyCFrame structure.

https://bugs.python.org/issue45431

[markshannon]

Why?

[markshannon]

CFrame is an internal implementation detail. It is not part of the C API.

[vstinner]

See https://devguide.python.org/c-api/ for the organization of the C API. The name is not prefixed by _Py or _PY, so it's a public name. Even if it's not a symbol in the ABI, it is a public name in the C API.

[vstinner]

CFrame is an internal implementation detail. It is not part of the C API.

Currently, it's a public name in the public C API. Today, it's used by PyThreadState.cframe and PyThreadState.root_cframe, and PyThreadState is public. We cannot define PyThreadState if the compiler doesn't know CFrame structure (root_cframe is an instance of the struct, not a pointer). I'm open to make PyThreadState opaque, but nobody finished the work to make that possible: see https://bugs.python.org/issue39947

[markshannon]

At least put an underscore on the front of the name: _PyCFrame.
And a big "Do not use this" warning, just to be sure.

[vstinner]

At least put an underscore on the front of the name: _PyCFrame. And a big "Do not use this" warning, just to be sure.

Sure, done. I added a comment suggesting using public functions rather than using directly the private _PyCFrame structure.

Well, I would prefer to be able to move the whole PyThreadState structure right now to the internal C API, as I just did for PyFrameObject, but I would prefer to have a smoother migration. I plan to spend more time on preparing projects using PyThreadState, maybe add a few more getter functions.

[vstinner]

@markshannon: Would you mind reviewing this change?

[markshannon]

That looks fine, thanks.

[vstinner]

Thanks for the feedback. I now agree that _PyCFrame (private name) is better ;-)