[issue47115] Documentation inconsistency with the stable ABI
New submission from Jeremiah Gabriel Pascual <nohackingofkrowten@gmail.com>: 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? ---------- assignee: docs@python components: Documentation messages: 415989 nosy: Crowthebird, docs@python priority: normal severity: normal status: open title: Documentation inconsistency with the stable ABI _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
Change by Ned Deily <nad@python.org>: ---------- nosy: +petr.viktorin _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
Petr Viktorin <encukou@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
Petr Viktorin <encukou@gmail.com> added the comment: 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 ---------- nosy: +vstinner _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
Change by Petr Viktorin <encukou@gmail.com>: ---------- keywords: +patch pull_requests: +30272 stage: -> patch review pull_request: https://github.com/python/cpython/pull/32196 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
Petr Viktorin <encukou@gmail.com> added the comment: 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/d79f118d044e9b4244b5dfda35448d39202... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue47115> _______________________________________
participants (3)
-
Jeremiah Gabriel Pascual -
Ned Deily
-
Petr Viktorin