Update PEP 3149 to explicitly include the stable ABI

[stefanor]

It was suggested on discourse that we update PEP-3149 to explicitly include the stable ABI, with examples.

PEP-384 was defined before PEP-3149 but in practice was only implemented a couple of years after 3149. PEP-3149 anticipated PEP-384, but didn't provide examples of it. And PEP-3149's implementation didn't cover the stable ABI, because it wasn't something in use yet.

PEP-1 describes PEPs as stable documents that shouldn't seek revision, but can we expand PEP-3149 here to provide more explicit clarity on how things should work?

Some resolution on this has been blocking python/cpython#122931 (implementation: python/cpython#122917) for a couple of years now. Debian has been carrying a patch to resolve this since Python 3.13.

[stefanor]

I should add: A timely decision here would allow a very last minute change to 3.15 to avoid needing to support non-multiarch-tagged abi3t.so files for the long-term future.

The main argument that has been given to block the MR has been the perceived performance cost of supporting both names.

[stefanor]

For some extra context on the performance concerns, they were raised here: python/cpython#122917 (comment)

I did some absolute worst case analysis here: python/cpython#122917 (comment) and I couldn't find any measurable difference.

We know the cost will be one extra syscall per extra import attempt. (2 now that abi3t exists too, unless we move fast)

At PyCon US 2026 @ericsnowcurrently looked into adding a caching layer in cPython but concluded that Linux's dentry cache is good enough, there is no value in adding another layer of caching on top of it.

[warsaw]

From the SC:

PEP 1 says:

In general, PEPs are no longer substantially modified after they have reached the Accepted, Final, Rejected or Superseded state. Once resolution is reached, a PEP is considered a historical document rather than a living specification. Formal documentation of the expected behavior should be maintained elsewhere, such as the Language Reference for core features, the Library Reference for standard library modules or the PyPA Specifications for packaging.

So in that regard, PEP 3149 should not be updated. If needed, we can add a canonical-doc reference to point from the PEP to the relevant documentation and make it more obvious that the PEP itself is historical. If we need to flesh out the living documentation, then we should do that too.

We think that this shouldn't block progress on issue and PR.

[warsaw]

Closing, but please do reopen if you need the SC to consider things further.

[eli-schwartz]

I think that this isn't strictly about PEP 3149 since PEP 3149 didn't actually define platform triplet based filenames. It did say that one is allowed to add additional bits to the filename "in an implementation defined behavior however you feel you need it for ABI purposes" but that is unrelated to the behavior which it required, which is "version tagging".

Really this is more about python/cpython#67169, which greatly expanded on what PEP 3149 mandated. Since the parts we care about today (abi3t adding platform triplets) were wholly lacking from the PEP even for regular extensions, I think it's quite fair to say the lack of a PEP specifically saying to do it for abi3t is not a barrier to doing it.

If people feel that the lack of a PEP is a major blocker, they are evidently wrong (it wasn't a blocker in the past) but it is indeed an unrelated shame that there doesn't seem to be anywhere other than a PEP to write design docs?

We think that this shouldn't block progress on issue and PR.

I think this maybe is the key takeaway to be had, here.