PEP 825: Wheel Variants: Package Format

[mgorny]

Basic requirements (all PEP Types)

• Read and followed PEP 1 & PEP 12
• File created from the latest PEP template
• PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
• Title clearly, accurately and concisely describes the content in 79 characters or less
• Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
• Author, Status (Draft), Type and Created headers filled out correctly
• PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
• Required sections included
  • Abstract (first section)
  • Copyright (last section; exact wording from template required)
• Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
• PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
• Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

• PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
• Suggested sections included (unless not applicable)
  • Motivation
  • Rationale
  • Specification
  • Backwards Compatibility
  • Security Implications
  • How to Teach This
  • Reference Implementation
  • Rejected Ideas
  • Open Issues
  • Acknowledgements
  • Footnotes
  • Change History
• Python-Version set to valid (pre-beta) future Python version, if relevant
• Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
• Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

---

Following the suggestions given in the previous PEP 817 thread [1], we have decided to split PEP 817 into a series of smaller PEPs, with the hope that this will make it easier to comprehend the concept and discuss it.

This is the first split PEP, that specifically focuses on the low-level details necessary for variants wheels to work, that is:

• adding variant label to the filename
• storing variant properties in the file
• exposing variants on the index
• ordering/selecting variants
• introducing variant-conditional dependencies via environment markers
• exposing variant wheels in pylock.toml

The PEP keeps variant properties abstract, deferring their governance and determining their compatibility to a subsequent PEP, along with building wheels. We've also significantly cut motivation down (the original is kept in PEP 817 for reference). We've tried to make the "specification" part easier to comprehend, and removed the duplicate "rationale-overview", in favor of a more focused "rationale" section.

Compared to the previous iteration of PEP 817, we've also corrected the variant ordering algorithm to handle corner cases better.

[1] https://discuss.python.org/t/pep-817-wheel-variants-beyond-platform-tags/105860

---

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

[hugovk]

@warsaw or @dstufft Please can one of you confirm co-authorship?

@DEKHTIARJonathan Note: we assign PEP number after core team co-authorship/sponsorship is confirmed :)

@mgorny There's a checklist at https://github.com/python/peps/blob/main/.github/PULL_REQUEST_TEMPLATE/Add%20a%20new%20PEP.md you might find useful to paste into the top message and check off as relevant.

[DEKHTIARJonathan]

@hugovk thanks Hugo with the help :)

@dstufft just told me to grab the next number available: link

PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header

[dstufft]

Yes. Sent from my iPhoneOn Feb 17, 2026, at 14:18, Jonathan DEKHTIAR ***@***.***> wrote:DEKHTIARJonathan left a comment (python/peps#4819) @hugovk @dstufft just told me to grab the next number available. —Reply to this email directly, view it on GitHub, or unsubscribe.You are receiving this because you were mentioned.Message ID: ***@***.***>

[hugovk]

Thanks, please go ahead with 825! Remember the CODEOWNERS file.

[DEKHTIARJonathan]

Done. Thanks Hugo

[mgorny]

@mgorny There's a checklist at https://github.com/python/peps/blob/main/.github/PULL_REQUEST_TEMPLATE/Add%20a%20new%20PEP.md you might find useful to paste into the top message and check off as relevant.

Ah, sorry, I wonder why GH didn't include it in the box.

[hugovk]

General suggestion for all this PEP splitting work, there are some optional headers that might be useful for cross linking:

Requires: *[NNN]
Replaces: *[NNN]
Superseded-By: *[NNN]

https://peps.python.org/pep-0012/#how-to-use-this-template

[DEKHTIARJonathan]

These headers do not apply to this specific PEP. We will probably update very soon 817 to include Requires: [817, and_others_not_yet_published]

If that works for you, we can close this one

[mgorny]

Yeah, basically I'm not sure yet how this all pans out, so let's wait before deciding how to link different PEPs together (i.e. if we're going to withdraw 817 or make it an "index" for other PEPs).

[hugovk]

Ah, sorry, I wonder why GH didn't include it in the box.

Not your fault, GitHub has only partially implemented the feature: the option to use a template only shows up when you click to open the PR via the website UI, and not for example via the link you get when pushing from the CLI (which is my usual route of opening a PR). 🤷

[warsaw]

@warsaw or @dstufft Please can one of you confirm co-authorship?

Confirmed

[h-vetinari]

the lack of separators here is a bit jarring. The numpy example for the introduction of variant labels has x86_64_v3; is there any reason this couldn't be:

Suggested change

	// matching the variant label ("x8664v3_openblas") and the value
	// matching the variant label ("x86_64_v3_openblas") and the value

This occurs in the same way in several example further down, so I must assume it's intentional, but I don't understand why that cramped style was chosen. Plus it's not consistent with also using x86_64_v3 in other places.

[mgorny]

Label can be up to 16 characters long, and anyway it's just an example.

[h-vetinari]

If the PEP itself already runs into this limitation (without a contrived example)

>>> len("x8664v3_openblas")
16

it sounds like 16 is too short? The Variant Label section does not provide a rationale for that length either. What constraint (aside from avoiding superlong wheel names) was this limit chosen for?

(PS. Happy to move this to discourse; I initially had thought this was just on the level of a typo fix, but it might need wider discussion)

[mgorny]

The "superlong wheel names" was precisely the problem. PyPI maintainers were concerned about the length, and 16 characters was basically a compromise (we originally had 8).

[merwok]

There was a suggestion of reserving a series of PEP numbers for this work.
Is there a mecanism for this?

[DEKHTIARJonathan]

There was a suggestion of reserving a series of PEP numbers for this work.

Is there a mecanism for this?

One of the issues is that we are not sure how many PEPs we will end up "cutting into". It would be nice to have but realistically it's not the end of the world if we don't also.

@hugovk if we were to "reserve and block" 825-830 right now. How would we do that ? What's the criteria to make it happen ?

[warsaw]

Given that 817 and 825 are already somewhat disjoint, it's not the end of the world if you don't get a series. But OTOH, it's also not difficult, since it's Just Numbers 😄. I think if you had a clearer sense of wanting X PEPs you could reserve a block of those X numbers. It also wouldn't be terrible if you end up using X-N because those extras could be "released" for other proposals. Harder is if you need X+N because those will already be assigned and renumbering isn't going to work.

[mgorny]

Thanks, @MegaIng and @merwok, and sorry for missing these updates. I admit the typing is still iffy, but I'm not sure if I should aim to put complete types all over the place, as that's probably going to hinder readability.

[MegaIng]

I admit the typing is still iffy, but I'm not sure if I should aim to put complete types all over the place, as that's probably going to hinder readability.

I don't think complete type gints are needed, no. But I do think all type hints that are there should be correct, otherwise it's confusing to read.

(FWIW, annotating self: Self is pointless noise, especially if Self isn't used anywhere else in the signature)

[mgorny]

(FWIW, annotating self: Self is pointless noise, especially if Self isn't used anywhere else in the signature)

TBH, I've done it for consistency with other: Self in the __lt__, and then for consistency with self: Self in other methods. Do you think I should remove all instances of self: Self, and just leave other: Self?