This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Documentation inconsistency with the stable ABI
Type: Stage: patch review
Components: Documentation Versions:
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Crowthebird, docs@python, petr.viktorin, vstinner
Priority: normal Keywords: patch

Created on 2022-03-25 08:05 by Crowthebird, last changed 2022-04-11 14:59 by admin.

Pull Requests
URL Status Linked Edit
PR 32196 merged petr.viktorin, 2022-03-30 15:19
Messages (4)
msg415989 - (view) Author: Jeremiah Gabriel Pascual (Crowthebird) * Date: 2022-03-25 08:05
In https://docs.python.org/3/c-api/typeobj.html#static-types, it says that PyTypeObject isn't part of the stable ABI. Yet, in https://docs.python.org/3/c-api/type.html#c.PyTypeObject, it says that PyTypeObject IS part of the stable ABI. Which is true?
msg416157 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2022-03-28 11:22
Thanks for the report! You're right that this is misleading. I'll clarify the docs for this and other structs.

- struct PyTypeObject is part if the limited API.
- its fields and size are not part of the API or stable ABI.
msg416370 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2022-03-30 14:57
So. According to PEP 384 (which added all structs in the stable ABI, except Py_buffer), some structs are opaque and others have a few members exposed:
https://peps.python.org/pep-0384/#structures

I will split the latter into 1) structs that have a few fields exposed mainly for backwards compatibility (which, of course, is very important here). Best practice is to treat them as opaque (use getters/setters):

- PyObject (ob_refcnt, ob_type)
- PyVarObject (ob_base, ob_size)

... and 2) structs for which all fields are part of the ABI (and the struct's size as well: for most of these as users are expected to provide arrays):

- PyMethodDef
- PyMemberDef
- PyGetSetDef
- PyModuleDefBase
- PyModuleDef
- PyStructSequence_Field
- PyStructSequence_Desc
- PyType_Slot
- PyType_Spec
- Py_buffer (new in 3.11)

The opaque structs continue to be:

- PyThreadState
- PyInterpreterState
- PyFrameObject
- symtable
- PyWeakReference
- PyLongObject
- PyTypeObject
msg416874 - (view) Author: Petr Viktorin (petr.viktorin) * (Python committer) Date: 2022-04-06 14:50
New changeset d79f118d044e9b4244b5dfda35448d39202d7f56 by Petr Viktorin in branch 'main':
bpo-47115: Document which parts of structs are in limited API/stable ABI (GH-32196)
https://github.com/python/cpython/commit/d79f118d044e9b4244b5dfda35448d39202d7f56
History
Date User Action Args
2022-04-11 14:59:57adminsetgithub: 91271
2022-04-06 14:50:59petr.viktorinsetmessages: + msg416874
2022-03-30 15:19:39petr.viktorinsetkeywords: + patch
stage: patch review
pull_requests: + pull_request30272
2022-03-30 14:57:29petr.viktorinsetnosy: + vstinner
messages: + msg416370
2022-03-28 11:22:25petr.viktorinsetmessages: + msg416157
2022-03-25 21:10:25ned.deilysetnosy: + petr.viktorin
2022-03-25 08:05:03Crowthebirdcreate