Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Documentation inconsistency with the stable ABI #91271

Closed
thatbirdguythatuknownot mannequin opened this issue Mar 25, 2022 · 4 comments
Closed

Documentation inconsistency with the stable ABI #91271

thatbirdguythatuknownot mannequin opened this issue Mar 25, 2022 · 4 comments
Labels
docs Documentation in the Doc dir

Comments

@thatbirdguythatuknownot
Copy link
Mannequin

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
    Copy link
    Mannequin Author

    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?

    @thatbirdguythatuknownot thatbirdguythatuknownot mannequin added the docs Documentation in the Doc dir label Mar 25, 2022
    @thatbirdguythatuknownot thatbirdguythatuknownot mannequin added the docs Documentation in the Doc dir label Mar 25, 2022
    @encukou
    Copy link
    Member

    encukou commented Mar 28, 2022

    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
    Copy link
    Member

    encukou commented 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):

    • 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
    Copy link
    Member

    encukou commented 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

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    @encukou encukou closed this as completed Apr 21, 2022
    @bedevere-bot bedevere-bot mentioned this issue Aug 5, 2022
    Merged
    encukou added a commit that referenced this issue Aug 5, 2022
    @encukou
    gh-91271: Document which parts of structs are in limited API/stable A…
    b66b6e1 
    …BI (GH-32196) (GH-95711)

Co-authored-by: Erlend Egeberg Aasland <erlend.aasland@innova.no>
    @ov2k ov2k mentioned this issue Aug 23, 2022
    Merged
    This was referenced Aug 25, 2022
    Merged
    Merged
    miss-islington pushed a commit to miss-islington/cpython that referenced this issue Aug 25, 2022
    @ov2k @miss-islington
    Clarify API stability of PyTypeObject in relation to static types. (p…
    73bf205 
    …ythonGH-96217)

Fixes:
python#95300

Related:
python#91271
(cherry picked from commit caa2a97)

Co-authored-by: ov2k <ov2k.github@gmail.com>
    encukou pushed a commit that referenced this issue Aug 25, 2022
    @ov2k
    Clarify API stability of PyTypeObject in relation to static types. (G…
    caa2a97 
    …H-96217)

Fixes:
#95300

Related:
#91271
    miss-islington pushed a commit to miss-islington/cpython that referenced this issue Aug 25, 2022
    @ov2k @miss-islington
    Clarify API stability of PyTypeObject in relation to static types. (p…
    af51ecd 
    …ythonGH-96217)

Fixes:
python#95300

Related:
python#91271
(cherry picked from commit caa2a97)

Co-authored-by: ov2k <ov2k.github@gmail.com>
    miss-islington added a commit that referenced this issue Aug 25, 2022
    @miss-islington @ov2k
    Clarify API stability of PyTypeObject in relation to static types. (G…
    3d14b4f 
    …H-96217)

Fixes:
#95300

Related:
#91271
(cherry picked from commit caa2a97)

Co-authored-by: ov2k <ov2k.github@gmail.com>
    miss-islington added a commit that referenced this issue Aug 25, 2022
    @miss-islington @ov2k
    Clarify API stability of PyTypeObject in relation to static types. (G…
    2f88289 
    …H-96217)

Fixes:
#95300

Related:
#91271
(cherry picked from commit caa2a97)

Co-authored-by: ov2k <ov2k.github@gmail.com>
    @vstinner vstinner mentioned this issue Jun 21, 2023
    Closed
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    docs Documentation in the Doc dir
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    1 participant
    @encukou