gh-156870: Add common Stable ABI notes for tables of definitions by encukou · Pull Request #156871 · python/cpython

encukou · 2026-09-03T07:21:15Z

Add two directives:

.. stable-abi-note:: adds a note with similar formatting as the auto-generated notes (not exact; that can be fixed in CSS which is in a different repo)
.. omit-stable-abi-notes:: a block in which autogenerated notes are omitted

Apply that to the tables of exceptions & iteration types.

(This PR has lots of indentation changes; hide them with ?w=1 in GitHub or -w on the Git command line.)

Issue: Replace some autogenerated Stable ABI notes with manual ones #156870

hopefully

read-the-docs-community · 2026-09-03T07:25:07Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #34430625 | 📁 Comparing b78b5ce against main (161054c)

🔍 Preview build

14 files changed · ± 14 modified

± Modified

StanFromIreland

This seems to be broken, we've lost all notes looking at the preview:

StanFromIreland · 2026-09-03T16:25:41Z

+            # in a 'c_annotations' attribute.
+            ancestor = node
+            while ancestor:
+                if 'omit-stable-abi-note' not in ancestor.get(


Skip the note if any ancestor has 'omit-stable-abi-note'

Is this not inverted, it's skipped if it's absent?

StanFromIreland · 2026-09-03T16:25:44Z

+                    [],
+                ):
+                    break
+                ancestor = node.parent


Shouldn't it be ancestor.parent?

StanFromIreland · 2026-09-03T16:27:00Z

+                # no skip; add the annotation
+                annotation = _stable_abi_annotation(record)
+                node.insert(0, annotation)
+                node.setdefault("classes", []).append('ADDED-HERE')


Leftover from debugging I presume?

encukou · 2026-09-04T12:24:37Z

Yes, thanks to the catch. That was not the code I meant to send.
Sorry for the noise!

StanFromIreland · 2026-09-04T19:51:35Z

+
+   These pointers are part of the :ref:`Stable ABI <stable>` since the
+   version in the *S.ABI* column (or since 3.2 when *S.ABI* is empty).
+   Exceptions marked N/A are *not* part of Stable ABI.


Suggested change

Exceptions marked N/A are *not* part of Stable ABI.

Exceptions marked N/A are *not* part of the Stable ABI.

StanFromIreland · 2026-09-04T19:51:44Z

+                ancestor = ancestor.parent
+            else:
+                # no skip; add the annotation
+                annotation = _stable_abi_annotation(record)


This approach seems a bit fragile and wasteful, we already have the Stable ABI data, but we're duplicating it with hand-written tables. Can we at least assert it matches stable_abi_data?

I haven't found a good way to do the assert.

I think this automation is a good tool -- it probably prevented a bunch of mistakes -- but where it has subpar results, we shouldn't be afraid to drop it and fall bask to writing things manually, like everywhere else in the docs.

If we start seeing many "S.ABI" columns, maybe we should automate that, but I don't think we're there yet.

I can't think of anything either I'm afraid.

StanFromIreland · 2026-09-04T19:51:51Z

+    has_content = True
+
+    def run(self) -> list[nodes.Node]:
+        node = nodes.Element()  # Anonymous container for parsing


Can we note use SphinxDirective.parse_content_to_nodes to simplify a little?

encukou · 2026-10-19T23:47:30Z

@StanFromIreland, do you want to take a look again?

StanFromIreland · 2026-10-21T19:51:19Z

   :c:data:`PyExc_BaseExceptionGroup`.


 OSError aliases


What about these, they are inconsistent now:

I'd like to handle these in a follow-up: #160111

miss-islington-app · 2026-10-23T22:54:07Z

Thanks @encukou for the PR 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

bedevere-app · 2026-10-23T22:54:24Z

GH-160539 is a backport of this pull request to the 3.15 branch.

…ns (GH-156871) (GH-160539) gh-156870: Add common Stable ABI notes for tables of definitions (GH-156871) (cherry picked from commit 99edd54) Co-authored-by: Petr Viktorin <encukou@gmail.com>

encukou added 4 commits September 2, 2026 18:31

Add extensions for manual stable ABI notes & omitting autogenerated ones

18f3740

Use stable-abi-note/omit-stable-abi-notes for the exceptions table

4b549d8

Use stable-abi-note/omit-stable-abi-notes for built-in iterators

932f03c

Docs for the doc tool

0e04200

encukou requested review from AA-Turner, StanFromIreland, ZeroIntensity and hugovk as code owners September 3, 2026 07:21

bedevere-app Bot mentioned this pull request Sep 3, 2026

Replace some autogenerated Stable ABI notes with manual ones #156870

Open

bedevere-app Bot added the awaiting core review label Sep 3, 2026

encukou added the skip news label Sep 3, 2026

Run the version of Ruff that CI needs today

f2a9bad

hopefully

picnixz changed the title ~~gh-156870: Ad common stable abi notes for tables of definitions~~ gh-156870: Add common stable abi notes for tables of definitions Sep 3, 2026

picnixz changed the title ~~gh-156870: Add common stable abi notes for tables of definitions~~ gh-156870: Add common Stable ABI notes for tables of definitions Sep 3, 2026

StanFromIreland reviewed Sep 3, 2026

View reviewed changes

encukou added 2 commits September 4, 2026 14:11

Resolve a branch mix-up

df60dcb

Remove forbidden blank line

4a1f50e

StanFromIreland reviewed Sep 4, 2026

View reviewed changes

encukou added 2 commits September 7, 2026 12:52

Use assert_has_content() and parse_content_to_nodes()

f91ddd0

Add the the

b78b5ce

StanFromIreland reviewed Oct 21, 2026

View reviewed changes

encukou mentioned this pull request Oct 21, 2026

Soft-deprecate C-API OSError aliases #160111

Merged

StanFromIreland approved these changes Oct 21, 2026

View reviewed changes

bedevere-app Bot added awaiting merge and removed awaiting core review labels Oct 21, 2026

encukou merged commit 99edd54 into python:main Oct 21, 2026
34 checks passed

bedevere-app Bot removed the awaiting merge label Oct 21, 2026

encukou deleted the manual-stable-abi-notes branch October 21, 2026 21:01

encukou added the needs backport to 3.15 bugs and security fixes label Oct 23, 2026

bedevere-app Bot removed the needs backport to 3.15 bugs and security fixes label Oct 23, 2026

	Exceptions marked N/A are not part of Stable ABI.
	Exceptions marked N/A are not part of the Stable ABI.

Conversation

encukou commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Sep 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

encukou commented Sep 4, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

encukou commented Oct 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-app Bot commented Oct 23, 2026

Uh oh!

bedevere-app Bot commented Oct 23, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

encukou commented Sep 3, 2026 •

edited

Loading

read-the-docs-community Bot commented Sep 3, 2026 •

edited

Loading