PEP 739: specify how to handle conflicting installs

[FFY00]

• Change is either:
  • To a Draft PEP
  • To an Accepted or Final PEP, with Steering Council approval
  • To fix an editorial issue (markup, typo, link, header, etc)
• PR title prefixed with PEP number (e.g. PEP 123: Summary of changes)

---

📚 Documentation preview 📚: https://pep-previews--4889.org.readthedocs.build/

[hugovk]

(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?

[FFY00]

@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.

[pfmoore]

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?

[merwok]

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)

[pfmoore]

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.

[stefanor]

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.