Skip to content

Documentation inconsistency with the stable ABI #91271

Closed
Closed
Documentation inconsistency with the stable ABI#91271
Labels
docsDocumentation in the Doc dir

Description

@thatbirdguythatuknownot
thatbirdguythatuknownot
mannequin
opened on Mar 25, 2022
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 = []

    Activity

    1. thatbirdguythatuknownot commented on Mar 25, 2022

      @thatbirdguythatuknownot
      thatbirdguythatuknownotmannequin
      on Mar 25, 2022
      MannequinAuthor

      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 dir
      on Mar 25, 2022
    4. thatbirdguythatuknownot
      assigned
      docspython
      on Mar 25, 2022
    5. thatbirdguythatuknownot
      added
      docsDocumentation in the Doc dir
      on Mar 25, 2022

    6. encukou commented on Mar 28, 2022

      @encukou
      encukou
      on Mar 28, 2022
      Member

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

      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
      encukou
      on Apr 6, 2022
      Member

      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
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

    Metadata

    Metadata

    Assignees

    No one assigned

      Labels

      docsDocumentation in the Doc dir

      Projects

      No projects

        Milestone

        No milestone

        Relationships

        None yet

        Development

        No branches or pull requests

        Issue actions