Description

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'

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

1. thatbirdguythatuknownot commented on Mar 25, 2022

   

   thatbirdguythatuknownotmannequin

   on Mar 25, 2022

   MannequinAuthor

   More actions

   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?
2. thatbirdguythatuknownot

   assigned

   docspython

   on Mar 25, 2022
3. thatbirdguythatuknownot

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Mar 25, 2022
4. thatbirdguythatuknownot

   assigned

   docspython

   on Mar 25, 2022
5. thatbirdguythatuknownot

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Mar 25, 2022
6. encukou commented on Mar 28, 2022

   

   encukou

   on Mar 28, 2022

   Member

   More actions

   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.
7. encukou commented on Mar 30, 2022

   

   encukou

   on Mar 30, 2022

   Member

   More actions

   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
8. encukou commented on Apr 6, 2022

   

   encukou

   on Apr 6, 2022

   Member

   More actions

   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
9. ezio-melotti

   transferred this issue fromon Apr 10, 2022
10. encukou

    closed this as completedon Apr 21, 2022
11. encukou

    added a commit that references this issue on Aug 5, 2022

    gh-91271: Document which parts of structs are in limited API/stable A…

    b66b6e1
12. miss-islington

    added a commit that references this issue on Aug 25, 2022

    Clarify API stability of PyTypeObject in relation to static types. (p…

    73bf205
13. encukou

    added a commit that references this issue on Aug 25, 2022

    Clarify API stability of PyTypeObject in relation to static types. (G…

    caa2a97
14. miss-islington

    added 3 commits that reference this issue on Aug 25, 2022

    Clarify API stability of PyTypeObject in relation to static types. (p…

    af51ecd

    Clarify API stability of PyTypeObject in relation to static types. (G…

    3d14b4f

    Clarify API stability of PyTypeObject in relation to static types. (G…

    2f88289

Issue actions