(I've added the checklist to the PR description.)

This is an accepted PEP, so needs SC approval:

If changes based on implementation experience and user feedback are made to Standards track PEPs while in the Provisional or (with SC approval) Accepted state, they should be noted in the PEP, such that the PEP accurately describes the implementation at the point where it is marked Final.

https://peps.python.org/pep-0001/#pep-maintenance

Please can you ask the SC about this change?

@pfmoore, per python/steering-council#341 and python/steering-council#343, could you make a decision on this? Since the 3.15 feature freeze is just around the corner, I really don't want to have to wait for the Packaging Council to be up to speed.

There's one edge case that I'd like to clarify before accepting.

Suppose that a distribution has two Python builds that both get installed into the same prefix, but only one is actually installed by the user. From a strict reading, that one installation would need to be named build-details.json, and only if/when a second build got installed, would the new text apply. This would be problematic, because it would require renaming of the original build-details.json.

It's arguable that the "UNLESS unfeasible due to technical limitations" exclusion applies here, and the potential to install two builds is considered enough of a technical limitation. But if it's too easy to justify using a different name, that dilutes the benefit of having an easily discoverable standard name for common cases, so allowing that could be a bad idea.

Could you update the wording to clarify the intent in this case, please?

but only one is actually installed by the user.

Could you explain the meaning here? Does this mean: installed manually with tools such as make install from a CPython checkout, as opposed to installed by the user using system-level package manager?

(In this case, for operating systems like Debian, the case in question is not possible: the package manager owns /usr, and the user can use /usr/local or /opt for manual local installs)

What I mean is, suppose Debian has python314 and python314-ft builds. Both use the same sys.prefix (presumably /usr? Sorry, I don't know how Linux distros do their filesystem layouts). The user does apt install python314, so they only have one Python installed.

A strict reading of the PEP implies that the file should be called build-details.json. Which presumably means that's what the file is called in the .deb archive. But the exact same logic applies to python314-ft, and you can't have two packages both "owning" the same file (I assume).

The likely answer is that "technical reasons" apply here, so the files should be something like build-details-314.json and build-details-314ft.json. But if we do that, then we lose a lot of the discoverability that having a standard name gives - and as a result, I think that this scenario should be explicitly discussed.

The free-threading case is one case (and still in Debian's future), but practically right now the there are two other clashes: debug builds and multiarch. Fundamentally the issue is that Debian installs multiple different builds of the same Python version, to the same tree. They can share .py files. C extensions are differentiated through ABI flags.

For multiarch:
You can have libpython3.14-stdlib:amd64 and libpython3.14-stdlib:i386 (for example) installed concurrently on the same system. Both need to contain build-details.json, per the PEP. But the contents needs to be different, because the files include some architecture-specific data.

But the exact same logic applies to python314-ft, and you can't have two packages both "owning" the same file (I assume).

Fundamentally, you can't have two files with the same name with different contents. If each build needs its own file (and they do, because the file documents details of the Python interpreter like architecture and ABI flags), then they have to be named differently.

We are currently working around this by calling our build-details files /usr/lib/python3.14/build-details_$(MULTIARCH).json. Based on the current state of this PR (and running the problem with debug builds), I'll rename them to /usr/lib/python3.14/build-details.$(ABIFLAGS).$(MULTIARCH).json. A little ugly to have .. in the default name, but it keeps the patch simple.

It's arguable that the "UNLESS unfeasible due to technical limitations" exclusion applies here, and the potential to install two builds is considered enough of a technical limitation.

That should and will pretty clearly apply to packages for any distro. Moving files from one package around based on the user installing another package is a big no-no (file listings are static and used in UIs, similar to RECORD files in wheels), and not how anyone is going to consider implementing this. Simple proposed textual fix to address the comment: change "share" to "may share" in _"When multiple Python installations share the same prefix".

@FFY00 any reason not to make that small tweak to address @pfmoore's edge case concern?

But if it's too easy to justify using a different name

I think any packager will only deviate from the SHOULD when necessary, as in Debian's case.

We are currently working around this by calling our build-details files /usr/lib/python3.14/build-details_$(MULTIARCH).json. Based on the current state of this PR (and running the problem with debug builds), I'll rename them to /usr/lib/python3.14/build-details.$(ABIFLAGS).$(MULTIARCH).json. A little ugly to have .. in the default name, but it keeps the patch simple.

Dots vs. underscores is a minor stylistic choice I'd think, but either way it'd be nice to recommend something (the examples kinda are a recommendation). You're assuming a scheme here that's build-details[.{abiflags}.{multiarch}].json rather than build-details[.{abiflags}][.{multiarch}].json (note the ][ in the middle, you're getting .. because of always filling in abiflags). Also, your name will then end up as build-details.t.x86_64-linux-gnu.json for free-threading; using a plain .t is quite hard to read and imho quite a bit worse than using .free-threading is in the example in this PR. This matter much more here than for _sysconfigdata, because this build-details file is much more user-facing.

In the end Debian is going to be the main user of this exception, so it'd be great to align the examples added to the PEP so they align with Debian's actual implementation and are readable.

@stefanor would something like build-details[.{multiarch}][-free-threading][-debug].json work perhaps?

@stefanor would something like build-details[.{multiarch}][-free-threading][-debug].json work perhaps?

Absolutely. That would be nice and readable. I think that naming scheme should be defined in the spec, and (ideally) created by the generation script, itself.

I don't want to have to invent my own scheme of mapping abi flags to readable strings, downstream. I'd much rather we define it here.

I think that naming scheme should be defined in the spec, and (ideally) created by the generation script, itself.

Ah, nice idea, I like it. Since it's opt-in anyway, I can't think of a downside of having some kind of toggle (env var perhaps, since plumbing this in through ./configure sounds like a pain?) inside the code that generates this json file. Doesn't feel like that should hold up merging this PR, but it's an opportunity for some Debian-CPython synergy - I believe we can use a bit of that:)

What I mean is, suppose Debian has python314 and python314-ft builds. Both use the same sys.prefix (presumably /usr? Sorry, I don't know how Linux distros do their filesystem layouts). The user does apt install python314, so they only have one Python installed.

Sorry for the delay getting back to you!

As Ralf mentioned, in most distribution systems, packages are static, so we can't move files based on whether another package is installed or not. As such, if the user only has one os the Python distribution packages installed, it would have a single build-details.XXX.json file.

I think that's fine, and it works with the PEP semantics — build-details.XXX.json map to Python installations, not the other way round.

Do think the PEP text needs more clarification regarding this?

Absolutely. That would be nice and readable. I think that naming scheme should be defined in the spec, and (ideally) created by the generation script, itself.

I don't want to have to invent my own scheme of mapping abi flags to readable strings, downstream. I'd much rather we define it here.

We can define something, but I would prefer not to for the following reasons:

• We can't specify a readable string format that covers all possible scenarios (I'd like to avoid having an edge-case in an edge-case)
• The readable string is just that, a string for humans to differentiate multiple installations, it has no semantic meaning, and should not be parsed by tooling

Ah, nice idea, I like it. Since it's opt-in anyway, I can't think of a downside of having some kind of toggle (env var perhaps, since plumbing this in through ./configure sounds like a pain?) inside the code that generates this json file. Doesn't feel like that should hold up merging this PR, but it's an opportunity for some Debian-CPython synergy - I believe we can use a bit of that:)

Yeah, I was planning to add a ./configure option to specify the build-details.XXX.json identifier string. I agree, it shouldn't block this PR.

Yeah, I was planning to add a ./configure option to specify the build-details.XXX.json identifier string. I agree, it shouldn't block this PR.

I'm busy implementing something like that right now. I'll file it and tag you for review.

Simple proposed textual fix to address the comment: change "share" to "may share" in _"When multiple Python installations share the same prefix".

Applied this suggestion. Thanks Ralf!

Documentation build overview

📚 pep-previews | 🛠️ Build #32763155 | 📁 Comparing b97169e against latest (7dd79b1)

  🔍 Preview build  

± Modified

• 404.html
• index.html
• api/index.html
• contents/index.html
• docs/index.html
• numerical/index.html
• pep-0000/index.html
• pep-0001/index.html
• pep-0002/index.html
• pep-0003/index.html
• and 734 more...

- Deleted

• pep-0786/index.html
• pep-0830/index.html
• pep-0831/index.html
• pep-0832/index.html
• pep-0833/index.html