Repository navigation
Documentation inconsistency with the stable ABI #91271
Description
| BPO | 47115 |
|---|---|
| Nosy | @vstinner, @encukou, @thatbirdguythatuknownot |
| PRs |
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 = []
Activity
thatbirdguythatuknownot commentedon Mar 25, 2022
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 commentedon Mar 28, 2022
Thanks for the report! You're right that this is misleading. I'll clarify the docs for this and other structs.
encukou commentedon Mar 30, 2022
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):
... 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):
The opaque structs continue to be:
encukou commentedon Apr 6, 2022
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
gh-91271: Document which parts of structs are in limited API/stable A…
Clarify API stability of PyTypeObject in relation to static types. (p…
Clarify API stability of PyTypeObject in relation to static types. (G…
Clarify API stability of PyTypeObject in relation to static types. (p…
Clarify API stability of PyTypeObject in relation to static types. (G…
Clarify API stability of PyTypeObject in relation to static types. (G…