Documentation inconsistency with the stable ABI

[thatbirdguythatuknownot]

BPO	47115
Nosy	@vstinner, @encukou, @thatbirdguythatuknownot
PRs	bpo-47115: Document which parts of structs are in limited API/stable ABI #32196

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2022-03-25.08:05:03.316>
labels = ['docs']
title = 'Documentation inconsistency with the stable ABI'
updated_at = <Date 2022-04-06.14:50:59.105>
user = 'https://github.com/thatbirdguythatuknownot'

bugs.python.org fields:

activity = <Date 2022-04-06.14:50:59.105>
actor = 'petr.viktorin'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2022-03-25.08:05:03.316>
creator = 'Crowthebird'
dependencies = []
files = []
hgrepos = []
issue_num = 47115
keywords = ['patch']
message_count = 4.0
messages = ['415989', '416157', '416370', '416874']
nosy_count = 4.0
nosy_names = ['vstinner', 'petr.viktorin', 'docs@python', 'Crowthebird']
pr_nums = ['32196']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue47115'
versions = []

[thatbirdguythatuknownot]

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?

[encukou]

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.

[encukou]

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

[encukou]

New changeset d79f118 by Petr Viktorin in branch 'main':
bpo-47115: Document which parts of structs are in limited API/stable ABI (GH-32196)
d79f118