PEP 817: Wheel Variants: Beyond Platform Tags #4740

DEKHTIARJonathan · 2025-12-10T21:54:21Z

Basic requirements (all PEP Types)

Standards Track requirements

CC: @mgorny @konstin @rgommers @atalman @charliermarsh @msarahan @seemethere @warsaw @dstufft @aterrel

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

python-cla-bot · 2025-12-10T21:54:25Z

All commit authors signed the Contributor License Agreement.

hugovk · 2025-12-10T22:05:03Z

Let's renumber this to 9999 for now, we also have #4739 clashing.

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

DEKHTIARJonathan · 2025-12-10T22:12:24Z

Oh thanks @hugovk I totally didn't see that one being published within 20min :D

Let me know which number you want me to pick and I'll do the update ;)

warsaw · 2025-12-10T22:57:39Z

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

Confirmed.

hugovk · 2025-12-10T23:18:11Z

Thanks!

@DEKHTIARJonathan You may continue with 817.

.github/CODEOWNERS

AA-Turner

very brief review, I haven't yet read beyond the end of Motivation.

A

peps/pep-0817/avx512_gromacs_benchmark.png

peps/pep-0817/pytorch_variant_selector.png

peps/pep-0817/appendix-variant-metadata-json-schema.rst

peps/pep-0817/variant_schema.json

peps/pep-0817.rst

jezdez · 2025-12-11T09:45:09Z

Just a brief bystander comment: I'm so stoked to see this PEP draft published!

Co-authored-by: Adam Turner <[email protected]>

DEKHTIARJonathan · 2025-12-11T13:44:09Z

Just a brief bystander comment: I'm so stoked to see this PEP draft published!

Thanks Jannis! Took some significant amount of work but we eventually got there

Signed-off-by: Michał Górny <[email protected]>

Co-authored-by: Adam Turner <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

Reflow the text to restore correct text width after all the inline changes and applied suggestions. Signed-off-by: Michał Górny <[email protected]>

Signed-off-by: Michał Górny <[email protected]>

@konstin

Remove accidental double spaces that vim's `gq` introduced while I was reflowing the text. Thanks to @konstin for noticing. Signed-off-by: Michał Górny <[email protected]>

seemethere · 2025-12-16T00:30:14Z

peps/pep-0817.rst

+enabling the optional provider or selecting the variant explicitly.
+
+
+Package ABI matching


Super excited about this one by the way :D

DEKHTIARJonathan · 2025-12-16T22:35:20Z

@hugovk @AA-Turner what needs to be done in order for the PEP to be merged ?

AA-Turner · 2025-12-16T22:37:39Z

Sorry for my delay here. I will review the remainder of the PEP this evening (UK time).

A

DEKHTIARJonathan · 2025-12-16T22:38:13Z

Fantastic, thanks Adam ;)

hugovk · 2025-12-16T23:21:00Z

Note this will be the longest PEP..! Thanks Adam for reviewing.

DEKHTIARJonathan · 2025-12-16T23:24:16Z

Note this will be the longest PEP..! Thanks Adam for reviewing.

I can pay with cookies for any emotional trauma induced by this work :D

Take your time, it took us close to one year to formalize everything, build prototypes and write the PEP.
So clearly I don't think any of us expect anyone to be able to read this and understand it in a few hours ;)

AA-Turner · 2025-12-17T01:19:16Z

I've completed my first detailed read-through (on printed paper!), but it's now firmly in the wee hours, so I'm going to continue in the morning. Writing up the review comments should go much quicker though!

A

AA-Turner

Sorry again for the further delay, this review has taken much longer than expected. I was half hoping someone else would beat me to it!

I've added several inline comments, albeit I ran out of steam a little (it is long past my bedtime!), so I might revisit the end of the PEP again.

General points:

I think the specification especially needs to be tightened up, to make it clear what exactly is being required of installers, builders, indexes, etc in as concicse wording as possible. The prose text in Specification should be moved elsewhere.
Significant chunks of text could be deleted/moved to an appendix. I've highlighted some obvious ones
I have found myself getting a bit confused by the jargon in the PEP, especially e.g. AoT, which might usefully be called 'static' plugins? The glossary was quite useful though.
Parts of the PEP appear to be saying conflicting things. This might be in my reading, but it'd be useful to clarify regardless.

So long, and thanks for all the ~~fish~~ cookies,
Adam

AA-Turner · 2025-12-18T04:39:11Z

peps/pep-0817.rst

+The goal is for a familiar ``[uv] pip install <package>`` to provide
+the best user experience.


Suggested change

The goal is for a familiar ``[uv] pip install <package>`` to provide

the best user experience.

The goal is for the obvious installation commands (``{tool} install <package>``)

to select the most appropriate wheel, and provide the best user experience.

AA-Turner · 2025-12-18T04:40:17Z

peps/pep-0817.rst

+The Python packaging ecosystem has evolved to support increasingly
+diverse computing environments. The current software ecosystem often


"software ecosystem" here is software in general rather than just Python? Would be useful to disambiguate from "packaging ecosystem" in the previous sentence.

AA-Turner · 2025-12-18T04:42:18Z

peps/pep-0817.rst

+format cannot adequately express the diversity of features present
+in modern hardware.
+
+For example, packages such as `PyTorch <https://pytorch.org/>`_ need to


The current style is fine, but using the same PyTorch link reference with different link targets/URIs technically creates ambiguous references in the RST spec. Prefer double-trailing-underscore to fix this.

AA-Turner · 2025-12-18T04:47:44Z

peps/pep-0817.rst

+According to the `2024 Python Developers Survey
+<https://lp.jetbrains.com/python-developers-survey-2024/#purposes-for-using-python>`__,
+a significant portion of respondents over the last years have been
+successively using Python for scientific computing purposes, covering
+such areas as Data analysis (steadily over 40% respondents), Machine
+learning (grown to 40% in 2024) and Data engineering (around 30%).
+Many of these use cases are directly impacted by suboptimal
+packaging.


I'd make this para the start of Motivation, it provides a useful contextualisation

Suggested change

According to the `2024 Python Developers Survey

<https://lp.jetbrains.com/python-developers-survey-2024/#purposes-for-using-python>`__,

a significant portion of respondents over the last years have been

successively using Python for scientific computing purposes, covering

such areas as Data analysis (steadily over 40% respondents), Machine

learning (grown to 40% in 2024) and Data engineering (around 30%).

Many of these use cases are directly impacted by suboptimal

packaging.

The `2024 Python Developers Survey`__ shows that a significant proportion of

Python's users have scientific computing use-cases. This includes data analysis

(40% of respondents), machine learning (30%), and data engineering (30%).

Many of these use-cases are directly impacted by suboptimal Python packaging.

__ https://lp.jetbrains.com/python-developers-survey-2024/#purposes-for-using-python

AA-Turner · 2025-12-18T04:48:14Z

peps/pep-0817.rst

+(``mypackage-gpu``, ``mypackage-cpu``, etc.). Each of these approaches
+has significant drawbacks.


Suggested change

(``mypackage-gpu``, ``mypackage-cpu``, etc.). Each of these approaches

has significant drawbacks.

(``mypackage-gpu``, ``mypackage-cpu``, etc.). Each of these approaches

has significant drawbacks and potential security implications.

AA-Turner · 2025-12-18T05:47:28Z

peps/pep-0817.rst

+containing file. Its individual keys are sub-dictionaries that are
+described in the subsequent sections, along with the requirements for
+their presence. The tools must ignore unknown keys in the dictionaries
+to permit future backwards compatible updates to the PEP. However, users


Suggested change

to permit future backwards compatible updates to the PEP. However, users

for forwards compatibility of updates to the PEP. However, users

AA-Turner · 2025-12-18T05:48:08Z

peps/pep-0817.rst

+described in the subsequent sections, along with the requirements for
+their presence. The tools must ignore unknown keys in the dictionaries
+to permit future backwards compatible updates to the PEP. However, users
+should not introduce custom keys to avoid potential future conflicts.


Suggested change

should not introduce custom keys to avoid potential future conflicts.

MUST NOT use unsupported keys to avoid potential future conflicts.

AA-Turner · 2025-12-18T05:48:45Z

peps/pep-0817.rst

+  it, effectively rendering the variants using its properties
+  incompatible. If it is ``false``, the provider is considered


I didn't understand this

AA-Turner · 2025-12-18T05:49:19Z

peps/pep-0817.rst

+- a ``$schema`` key whose value is the URL corresponding to the schema
+  file supplied in the appendix of this PEP. The URL contains the
+  version of the format, and a new version must be added to the appendix
+  whenever the format changes in the future,


why this over a simple version key?

AA-Turner · 2025-12-18T05:50:45Z

peps/pep-0817.rst

+Plugins are implemented as Python packages. They need to expose two
+kinds of Python objects at a specified API endpoint:


Is this a hard requirement? The PEP also notes/suggests that installers reimplement (popular) provider packages, and e.g. uv is written in Rust, not Python. Does it cease to be a plugin when reimplemented?

PEP 817: Wheel Variants: Beyond Platform Tags

f81a825

DEKHTIARJonathan requested a review from a team as a code owner December 10, 2025 21:54

hugovk changed the title ~~PEP 817: Wheel Variants: Beyond Platform Tags~~ PEP 9999: Wheel Variants: Beyond Platform Tags Dec 10, 2025

hugovk mentioned this pull request Dec 10, 2025

PEP 818: Upstreaming the Pyodide js ffi #4739

Open

27 tasks

hugovk changed the title ~~PEP 9999: Wheel Variants: Beyond Platform Tags~~ PEP 817: Wheel Variants: Beyond Platform Tags Dec 10, 2025

hugovk reviewed Dec 10, 2025

View reviewed changes

.github/CODEOWNERS Outdated Show resolved Hide resolved

Code-Owners editing

5c3b867

AA-Turner added the new-pep A new draft PEP submitted for initial review label Dec 11, 2025

AA-Turner reviewed Dec 11, 2025

View reviewed changes

hugovk mentioned this pull request Dec 11, 2025

PEP 12: SVG is allowed after PEP 676 #4741

Merged

Apply suggestions from code review

8e3d5ea

Co-authored-by: Adam Turner <[email protected]>

mgorny and others added 5 commits December 11, 2025 17:26

Switch to plain quotation marks

f0d43f6

Signed-off-by: Michał Górny <[email protected]>

Move "definitions" to "specification" section

e16bf03

Signed-off-by: Michał Górny <[email protected]>

Reflow the cupy package list

fede5ff

Signed-off-by: Michał Górny <[email protected]>

Update peps/pep-0817/appendix-variant-metadata-json-schema.rst

c68242d

Co-authored-by: Adam Turner <[email protected]>

[PEP Review] JSON Schema Indent switched to 2

64f32ed

DEKHTIARJonathan force-pushed the pep-817-wheel-variants branch from e34e8fa to 64f32ed Compare December 12, 2025 03:14

mgorny added 5 commits December 12, 2025 15:20

Replace the benchmark chart with SVG

78ff40b

Signed-off-by: Michał Górny <[email protected]>

Compact the SVG

a31b68b

Signed-off-by: Michał Górny <[email protected]>

Reflow text

73753b9

Reflow the text to restore correct text width after all the inline changes and applied suggestions. Signed-off-by: Michał Górny <[email protected]>

Replace typographic apostrophes

162ec7b

Signed-off-by: Michał Górny <[email protected]>

Remove double spaces introduced while reflowing

0064073

Remove accidental double spaces that vim's `gq` introduced while I was reflowing the text. Thanks to @konstin for noticing. Signed-off-by: Michał Górny <[email protected]>

seemethere reviewed Dec 16, 2025

View reviewed changes

AA-Turner reviewed Dec 18, 2025

View reviewed changes

		enabling the optional provider or selecting the variant explicitly.


		Package ABI matching

		The goal is for a familiar ``[uv] pip install <package>`` to provide
		the best user experience.

		The Python packaging ecosystem has evolved to support increasingly
		diverse computing environments. The current software ecosystem often

		(``mypackage-gpu``, ``mypackage-cpu``, etc.). Each of these approaches
		has significant drawbacks.

	to permit future backwards compatible updates to the PEP. However, users
	for forwards compatibility of updates to the PEP. However, users

	should not introduce custom keys to avoid potential future conflicts.
	MUST NOT use unsupported keys to avoid potential future conflicts.

		it, effectively rendering the variants using its properties
		incompatible. If it is ``false``, the provider is considered

		Plugins are implemented as Python packages. They need to expose two
		kinds of Python objects at a specified API endpoint:

Uh oh!

PEP 817: Wheel Variants: Beyond Platform Tags #4740

Are you sure you want to change the base?

PEP 817: Wheel Variants: Beyond Platform Tags #4740

Conversation

DEKHTIARJonathan commented Dec 10, 2025 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

python-cla-bot bot commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Dec 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

DEKHTIARJonathan commented Dec 10, 2025

Uh oh!

warsaw commented Dec 10, 2025

Uh oh!

hugovk commented Dec 10, 2025

Uh oh!

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jezdez commented Dec 11, 2025

Uh oh!

DEKHTIARJonathan commented Dec 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DEKHTIARJonathan commented Dec 16, 2025

Uh oh!

AA-Turner commented Dec 16, 2025

Uh oh!

DEKHTIARJonathan commented Dec 16, 2025

Uh oh!

hugovk commented Dec 16, 2025

Uh oh!

DEKHTIARJonathan commented Dec 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AA-Turner commented Dec 17, 2025

Uh oh!

AA-Turner 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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

DEKHTIARJonathan commented Dec 10, 2025 •

edited by hugovk

Loading

python-cla-bot bot commented Dec 10, 2025 •

edited

Loading

hugovk commented Dec 10, 2025 •

edited

Loading

DEKHTIARJonathan commented Dec 16, 2025 •

edited

Loading