GeezerVison

The World Wide Web, restored to 800 pixels of glory.

GeezerVison is showing github.com — bpo-47115: Document which parts of structs are in limited API/stable ABI by encukou · Pull Request #32196 · python/cpython

bpo-47115: Document which parts of structs are in limited API/stable ABI #32196

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

Merged

encukou merged 7 commits into python:main from encukou:abi3-struct-docs

Apr 6, 2022

Uh oh!

There was an error while loading. Please reload this page.

Merged

bpo-47115: Document which parts of structs are in limited API/stable ABI #32196

Show file tree

Hide file tree

Changes from 1 commit

Commits

Show all changes

7 commits

Select commit Hold shift + click to select a range

655bfe5

stable_abi.txt: Fix several function types that were listed as structs

encukou Mar 30, 2022

9f4c764

Document which parts of structs are in limited API/stable ABI

Apply suggestions from code review

encukou Apr 1, 2022

89826aa

Use “members” as the term for struct fields

encukou Apr 1, 2022

4b188ae

Adjust wording of the PyFrameObject docs

encukou Apr 1, 2022

c1ef70a

Reword the "Only some members" message and adjust comment

encukou Apr 6, 2022

File filter

Filter by extension .dat (1) .py (2) .rst (1) .txt (1) All 4 file types selected

Viewed files

Clear filters

Conversations

Failed to load comments.

Uh oh!

There was an error while loading. Please reload this page.

Jump to

Jump to file

Failed to load files.

Uh oh!

There was an error while loading. Please reload this page.

Diff view

Unified

Split

Hide whitespace

Diff view

Unified

Split

Hide whitespace

Previous commit

Next commit

Use “members” as the term for struct fields

Loading branch information

Uh oh!

There was an error while loading. Please reload this page.

encukou committed Apr 1, 2022

commit 89826aae2abcff0ce531f7691628c24974908d2a

There are no files selected for viewing

4 changes: 2 additions & 2 deletions 4 Doc/data/stable_abi.dat

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -470,7 +470,7 @@ function,PyOS_string_to_double,3.2,,
		function,PyOS_strtol,3.2,,
		function,PyOS_strtoul,3.2,,
		function,PyOS_vsnprintf,3.2,,
		type,PyObject,3.2,,fields
		type,PyObject,3.2,,members
		member,PyObject.ob_refcnt,3.2,,
		member,PyObject.ob_type,3.2,,
		function,PyObject_ASCII,3.2,,
Expand Down Expand Up		@@ -779,7 +779,7 @@ function,PyUnicode_Tailmatch,3.2,,
		function,PyUnicode_Translate,3.2,,
		var,PyUnicode_Type,3.2,,
		function,PyUnicode_WriteChar,3.7,,
		type,PyVarObject,3.2,,fields
		type,PyVarObject,3.2,,members
		member,PyVarObject.ob_base,3.2,,
		member,PyVarObject.ob_size,3.2,,
		type,PyWeakReference,3.2,,opaque
Expand Down

2 changes: 1 addition & 1 deletion 2 Doc/tools/extensions/c_annotations.py

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -124,7 +124,7 @@ def add_annotations(self, app, doctree):
		emph_node += nodes.Text(' (as an opaque struct)')
		elif struct_abi_kind == 'full-abi':
		emph_node += nodes.Text(' (including all members)')
		elif struct_abi_kind == 'fields':
		elif struct_abi_kind == 'members':
		emph_node += nodes.Text(
		' (but only some members are part of the stable ABI)')
		if record['ifdef_note']:
Expand Down

2 changes: 1 addition & 1 deletion 2 Misc/NEWS.d/next/Documentation/2022-03-30-17-08-12.bpo-47115.R3wt3i.rst

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
		@@ -1,2 +1,2 @@
		The documentation now lists which fields of C structs are part of the
		The documentation now lists which members of C structs are part of the
		:ref:`Limited API/Stable ABI <stable>`.

14 changes: 7 additions & 7 deletions 14 Misc/stable_abi.txt

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -43,12 +43,12 @@
		# were public in the past)

		# For structs, one of the following must be set:
		# - opaque: The struct name is available in the Limited API, but its fields
		# - opaque: The struct name is available in the Limited API, but its members
		# are not. Users must manipulate it via pointers.
		# - fields: Space-separated list of fields which are part of the Limited API
		# and Stable ABI.
		# Fields that sren't listed are not accessible to applications.
		# - full-abi: The entire struct -- all its fields and its size -- is part of
		# - members: Space-separated list of members which are part of the
		# Limited API and Stable ABI.
		# Members that aren't listed are not accessible to applications.
		# - full-abi: The entire struct -- all its members and its size -- is part of
		# the Stable ABI, and must not change.

		# Removing items from this file is generally not allowed, and additions should
Expand All		@@ -63,10 +63,10 @@

		struct PyObject
		added 3.2
		fields ob_refcnt ob_type
		members ob_refcnt ob_type
		struct PyVarObject
		added 3.2
		fields ob_base ob_size
		members ob_base ob_size
		struct PyMethodDef
		added 3.2
		full-abi
Expand Down

12 changes: 6 additions & 6 deletions 12 Tools/scripts/stable_abi.py

Show comments

View file

Open in desktop

Original file line number	Diff line number	Diff line change
Expand Up		@@ -119,7 +119,7 @@ class ABIItem:
		abi_only: bool = False
		ifdef: str = None
		struct_abi_kind: str = None
		fields: list = None
		members: list = None

		KINDS = frozenset({
		'struct', 'function', 'macro', 'data', 'const', 'typedef',
Expand Down Expand Up		@@ -174,15 +174,15 @@ def raise_error(msg):
		if parent.kind not in {'function', 'data'}:
		raise_error(f'{kind} cannot go in {parent.kind}')
		parent.abi_only = True
		elif kind in {'fields', 'full-abi', 'opaque'}:
		elif kind in {'members', 'full-abi', 'opaque'}:
		if parent.kind not in {'struct'}:
		raise_error(f'{kind} cannot go in {parent.kind}')
		if prev := getattr(parent, 'struct_abi_kind', None):
		raise_error(
		f'{parent.name} already has {prev}, cannot add {kind}')
		parent.struct_abi_kind = kind
		if kind == 'fields':
		parent.fields = content.split()
		if kind == 'members':
		parent.members = content.split()
		else:
		raise_error(f"unknown kind {kind!r}")
		# When adding more, update the comment in stable_abi.txt.
Expand Down Expand Up		@@ -272,10 +272,10 @@ def gen_doc_annotations(manifest, args, outfile):
		'added': item.added,
		'ifdef_note': ifdef_note,
		'struct_abi_kind': item.struct_abi_kind})
		for field_name in item.fields or ():
		for member_name in item.members or ():
		writer.writerow({
		'role': 'member',
		'name': f'{item.name}.{field_name}',
		'name': f'{item.name}.{member_name}',
		'added': item.added})

		@generator("ctypes_test", 'Lib/test/test_stable_abi_ctypes.py')
Expand Down

Add this suggestion to a batch that can be applied as a single commit. This suggestion is invalid because no changes were made to the code. Suggestions cannot be applied while the pull request is closed. Suggestions cannot be applied while viewing a subset of changes. Only one suggestion per line can be applied in a batch. Add this suggestion to a batch that can be applied as a single commit. Applying suggestions on deleted lines is not supported. You must change the existing code in this line in order to create a valid suggestion. Outdated suggestions cannot be applied. This suggestion has been applied or marked resolved. Suggestions cannot be applied from pending reviews. Suggestions cannot be applied on multi-line comments. Suggestions cannot be applied while the pull request is queued to merge. Suggestion cannot be applied right now. Please check back later.

You are visitor 01402520 — GeezerVison does not store the pages you look up.
Best viewed with Netscape Navigator 4.7 or Internet Explorer 6 at 800×600. No cookies required.