PEP 817: Final set of pre-split updates by mgorny · Pull Request #4867 · python/peps

mgorny · 2026-03-19T16:58:13Z

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)

This is a set of updates to PEP 817 that were prepared prior to the decision to split it into smaller PEPs. We do not intend to pursue PEP 817 in this updated form. However, we would like to get the changes committed to the repository so that the history of changes is not lost.

The changes include refocusing of the security details, some clarifications, tool behavior outlines and update for the images to respect dark theme.

We are not marking the PEP as withdrawn, as our current plan is to eventually replace the specification part with an index listing the split PEPs.

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

This is a set of updates to PEP 817 that were prepared prior to the decision to split it into smaller PEPs. We do not intend to pursue PEP 817 in this updated form. However, we would like to get the changes committed to the repository so that the history of changes is not lost. The changes include refocusing of the security details, some clarifications, tool behavior outlines and update for the images to respect dark theme. We are not marking the PEP as withdrawn, as our current plan is to eventually replace the specification part with an index listing the split PEPs. Signed-off-by: Michał Górny <mgorny@quansight.com>

rgommers

This was reviewed in detail by multiple co-authors before opening this PR. It contains important clarifications, as well as the diagram that multiple reviewers found really helpful.

PEP editors, can this please be merged?

hugovk · 2026-05-19T12:27:45Z

This looks okay in dark mode:

But the lines and a lot of text are invisible or hard to read in light:

@mgorny I thought we fixed the light/dark mode behavior?

Weird. It renders fine for me:

SVG portability ... sigh. On macOS, it renders fine on Safari, and badly on Firefox and Chrome.

For https://pypackaging-native.github.io/ I took the easy way out and just committed two .svg files, with the selected one depending on dark mode yes/no. Not sure if that's acceptable here. Can also just accept that it's imperfect in one of the modes and commit the white-background one, if that would be okay (there's already another image that's white-only because screenshot).

That's Firefox on Linux? It doesn't show for me on Chrome/Safari/Firefox/Opera on macOS, or Chrome on Android.

https://pep-previews--4867.org.readthedocs.build/pep-0817/#installing-a-package-from-an-index

If you want to use PNG, you can put :class: invert-in-dark-mode on it to invert via CSS (see other PEPs).

Two SVG files sound like a good workaround, but I don't know if we can implement switching between them via Sphinx.

Either way, I'm fine with any of the solutions, please decide for me :-).

If you want to use PNG, you can put :class: invert-in-dark-mode on it to invert via CSS (see other PEPs).

This sounds nice. PNG is much easier to work with, so if it's that easy, I'd prefer that - will not be the last time we'll need this.

Done. I've also added the class to PyTorch selector screenshot.

@hugovk, could you check if the same problem applies to the GROMACS bar graph? If yes, I can also replace it with a PNG.

Signed-off-by: Michał Górny <mgorny@quansight.com>

read-the-docs-community · 2026-05-22T16:19:03Z

Documentation build overview

📚 pep-previews | 🛠️ Build #32813447 | 📁 Comparing 8fe969a against latest (0d6797e)

🔍 Preview build

698 files changed · ± 698 modified

± Modified

willingc

Thanks. Let's try to land this since it adds useful diagrams which readers will benefit from viewing

willingc · 2026-03-19T17:48:02Z

+When asked to install a version of a package from an index, the proposed
+behavior would be to:
+
+1. Query the remote index for the package in question.


Suggested change

1. Query the remote index for the package in question.

1. Query the remote index for the desired package.

willingc · 2026-03-19T17:51:06Z

+2. Initially select a package version meeting the version constraints,
+   as usual (this does not need to take variant metadata into account).


Suggested change

2. Initially select a package version meeting the version constraints,

as usual (this does not need to take variant metadata into account).

2. Select an initial match for a package version meeting the version constraints,

as usual (this does not need to take variant metadata into account).

willingc · 2026-03-19T17:54:55Z

+   as usual (this does not need to take variant metadata into account).
+3. Filter available wheels based on Platform Compatibility Tags.
+4. Determine if any of the remaining wheels are variant wheels.
+   If not, proceed as with non-variant wheels.


proceed as with non-variant wheels

This would use the initial match. Correct?

willingc · 2026-03-19T17:57:26Z

 non-variant wheels as well.


+Suggested implementation logic per type of packaging tool


Can we simplify this language?

Suggested change

Suggested implementation logic per type of packaging tool

Suggested implementation logic for a packaging tool

willingc · 2026-03-19T17:57:59Z

+When asked to install a version of a package from an index, the proposed
+behavior would be to:


Suggested change

When asked to install a version of a package from an index, the proposed

behavior would be to:

When asked to install a version of a package from an index, the proposed

tool behavior would be to:

willingc · 2026-03-19T17:59:00Z

+2. Initially select a package version meeting the version constraints,
+   as usual (this does not need to take variant metadata into account).
+3. Filter available wheels based on Platform Compatibility Tags.
+4. Determine if any of the remaining wheels are variant wheels.


Suggested change

4. Determine if any of the remaining wheels are variant wheels.

4. Determine if any of the filtered wheels are variant wheels.

willingc · 2026-03-19T18:00:09Z

+When asked to install a local wheel file, the proposed behavior would be
+to:


Suggested change

When asked to install a local wheel file, the proposed behavior would be

to:

When asked to install a local wheel file, the tool's proposed behavior would be

to:

mgorny requested review from dstufft and warsaw as code owners March 19, 2026 16:58

rgommers approved these changes May 19, 2026

View reviewed changes

hugovk reviewed May 19, 2026

View reviewed changes

mgorny added 5 commits May 22, 2026 15:30

Unblockquote the diagram

295e3d7

Signed-off-by: Michał Górny <mgorny@quansight.com>

Add alt-text for the diagram

47fc562

Signed-off-by: Michał Górny <mgorny@quansight.com>

Replace the diagram with a PNG

ef387bb

Signed-off-by: Michał Górny <mgorny@quansight.com>

Invert the pytorch selector image too

7cd352e

Signed-off-by: Michał Górny <mgorny@quansight.com>

Merge branch 'main' into pep-817-update

8fe969a

willingc approved these changes May 22, 2026

View reviewed changes

	1. Query the remote index for the package in question.
	1. Query the remote index for the desired package.

		2. Initially select a package version meeting the version constraints,
		as usual (this does not need to take variant metadata into account).

		non-variant wheels as well.


		Suggested implementation logic per type of packaging tool

	Suggested implementation logic per type of packaging tool
	Suggested implementation logic for a packaging tool

		When asked to install a version of a package from an index, the proposed
		behavior would be to:

	4. Determine if any of the remaining wheels are variant wheels.
	4. Determine if any of the filtered wheels are variant wheels.

		When asked to install a local wheel file, the proposed behavior would be
		to:

Uh oh!

Conversation

mgorny commented Mar 19, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

read-the-docs-community Bot commented May 22, 2026

Documentation build overview

Uh oh!

willingc 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

mgorny commented Mar 19, 2026 •

edited by hugovk

Loading