PEP 9999: building (draft; do not merge) by mgorny · Pull Request #44 · wheelnext/peps

mgorny · 2026-03-02T17:18:31Z

Here's an early draft, mostly as context to #40.

📚 Documentation preview 📚: https://wheelnext-peps--44.org.readthedocs.build/

read-the-docs-community · 2026-03-02T17:22:13Z

Documentation build overview

📚 wheelnext-peps | 🛠️ Build #35419432 | 📁 Comparing 067a5a5 against latest (344e589)

🔍 Preview build

166 files changed · + 11 added · ± 154 modified · - 1 deleted

+ Added

± Modified

- Deleted

pep-0817/appendix-variant-metadata-json-schema/index.html

rgommers

This looks pretty good to me, thanks @mgorny! I only have a handful of comments at the moment.

rgommers · 2026-03-12T12:43:06Z

+For consistency, it is RECOMMENDED that build backends implement the
+following interface for building variant wheels:
+
+- variant metadata seed is stored in ``pyproject.toml`` file, as


The word "seed" here and in the next section isn't too helpful. It seems to imply that changes may occur, it's only a starting point (a la "random seed"). That isn't the case - the metadata in pyproject.toml and in variants.json should actually be 100% consistent. And as for PEP 621, if both exist, I'd expect the pyproject.toml version to be authoritative.

I'm not opposed to replacing or removing "seed", but there are some differences:

variants will only include the selected variant.

providers.{namespace}.static-properties may be filled from a plugin.

default-priorities.feature.{namespace} may be filled from a plugin.

@mgorny I still don't like "seed" at all. I suggest "variant configuration" instead.

rgommers · 2026-07-10T18:19:40Z

I just remembered that I had made a diagram early on in wheelnext/pep_817_wheel_variants#9. Here's the latest version:

Needs some tweaks to align with the final version of this PEP, but we may want to consider including it - a lot easier to grasp than lots of text and numbered lists of steps.

EDIT: or better, include into the reworked PEP 817 as an Informational PEP, since it looks like we're going that way.

rgommers

This probably is still in flux at the moment, but I had a look. Overall looks good, and all of the main decisions still make sense to me. The main comment I have right now is that default-priorities.feature is still used in some places.

rgommers · 2026-10-26T11:41:36Z

@mgorny the diff is quite large, how about rebasing or merging in the main branch of python/peps so we get all the latest changes to 817, 825 and 850 as a baseline?. Also, this PR should probably be retargeted to a new integration branch for just the Building PEP.

mgorny · 2026-10-26T12:10:57Z

Oh, sorry, I thought I've rebased it already.

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

mgorny · 2026-10-26T12:16:02Z

Oh, I needed to change base here.

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

rgommers

Here is a first set of comments - I'm about halfway through, more coming later today or tomorrow.

rgommers · 2026-10-26T12:06:30Z

+  list of variant feature names and their values that are valid
+  according to the provider plugin. The ordering of the lists is
+  insignificant. A particular plugin version MUST always return the same
+  lists (modulo ordering), irrespective of any runtime conditions.


It would be good to state in the Rationale that the ordering of get_all_configs is insignificant because the interface is meant only for validating that properties/features are valid. And that it's useful to leave the list unordered because (reason: I think so that only features that are actually used need to be specified in feature-order).

rgommers · 2026-10-26T12:22:51Z

+
+The ``build-requires`` key is only valid in the ``pyproject.toml`` file.
+In a variant wheel built from that file, the ``build-requires`` and
+``plugin-api`` keys MUST be removed, and ``static-properties`` MUST be


static-properties MUST be added -> that seems to imply that it must always be added, even when building a null variant.

It's a little hard to work this out in my head, but this juggling between required/optional and what metadata must be retained in the built wheel feels like it has room for corner cases.

That's actually a good question. I suppose it must be added, because otherwise you'd end up with a provider entry that has none of the required keys.

Now I wonder if we should make it explicit in PEP 850 that it may be empty.

Wait a minute, I've gotten confused here. These are the lists of all supported properties, so they should always be filled, as we expect them to be the same across all variants. I suppose a tool may remove a provider if the variant doesn't use it, but it definitely mustn't output build-requires or incorrect static-properties.

Hmm, but no, that will break PEP 850 schema. We can't remove the provider information without removing it from namespace order, and if we removed it there, we couldn't guarantee consistency.

rgommers · 2026-10-26T12:24:12Z

+.. code:: toml
+
+    [variant]
+    "$schema" = "https://variants-schema.wheelnext.dev/peps/850/v0.2.0.json"


This schema must be bumped right? PEP 850 has v0.2.0, and we're adding to it here?

No, the JSON schema is not being changed. We've decided against having a separate TOML schema, so the extensions here don't affect the schema. This is probably something that should be mentioned in the rationale.

Ah, okay - then yes, let's add that prominently in Rationale.

Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>

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

rgommers

Some more comments on the text, nothing too dramatic.

rgommers · 2026-10-26T22:31:27Z

+Type: Standards Track
+Topic: Packaging
+Requires: 825, 850
+Created: 02-Mar-2026


Suggested change

Created: 02-Mar-2026

Created: 26-Oct-2026

rgommers · 2026-10-26T22:35:25Z

+backends. All of this is given as a recommendation to make documentation
+universal, build backends interchangeable and therefore improve user
+experience. At the same, build backends are permitted to follow a
+different implementation path as necessary to fit their specific use
+cases.


I'm not so sure about this part, it feels like an unnecessary disclaimer. This can be said of many PEPs "feel free to ignore and use tool.xxx to do your own thing".

I'll need to think about this some more, but I'm currently inclined to suggest leaving out these sentences.

rgommers · 2026-10-26T22:35:42Z

+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+document are to be interpreted as described in :rfc:`2119`.


Can we remove this? It's just boilerplate.

rgommers · 2026-10-26T22:42:58Z

+For consistency, it is RECOMMENDED that build backends implement the
+following interface for building variant wheels:
+
+- variant metadata seed is stored in ``pyproject.toml`` file, as


@mgorny I still don't like "seed" at all. I suggest "variant configuration" instead.

rgommers · 2026-10-26T22:47:22Z

+.. code:: toml
+
+    [variant]
+    "$schema" = "https://variants-schema.wheelnext.dev/peps/850/v0.2.0.json"


This doesn't look right to me. It'd be very unusual to point at an actual JSON schema here. I think all we want is the version number. There will only ever be one authoritative place for a schema; we don't want to indicate that one can make up their own.

rgommers · 2026-10-26T22:51:58Z

+
+When using build backends, using ``get_requires*()`` hooks for exposing
+provider plugin dependencies as regular build dependencies is
+recommended. This permits reusing the existing frontend logic for


Why "recommended"? I don't think that build backends should be making their own choices here, this should be mandatory.

rgommers · 2026-10-26T22:54:10Z

+integration`_) follows from :pep:`518` specifying that such tables are
+"reserved for future use by other PEPs". Therefore, introducing the
+``[variant]`` table is backwards compatible.
+


I'd state explicitly here that hence there are no additional backwards compatibility implications beyond those listed in PEP 825.

rgommers · 2026-10-26T22:54:40Z

+There are no new security implications beyond what is already noted in
+:pep:`850`. In particular, the use of provider plugins during build time
+is not seen as an additional risk, given that the dependencies are
+provided by the user directly (for example, in ``pyproject.toml``) and


Suggested change

provided by the user directly (for example, in ``pyproject.toml``) and

specified by the package author directly (in ``pyproject.toml``) and

mgorny mentioned this pull request Mar 2, 2026

PEP 9999: providers (for review) #40

Closed

mgorny force-pushed the pep-building branch 3 times, most recently from 2fed7a0 to 96c81fc Compare March 9, 2026 13:16

rgommers reviewed Mar 12, 2026

View reviewed changes

mgorny force-pushed the pep-building branch 2 times, most recently from f80e6e8 to b7ad00c Compare March 12, 2026 15:05

mgorny force-pushed the pep-providers branch from da14f55 to a2dafb4 Compare March 12, 2026 15:05

mgorny force-pushed the pep-providers branch from a2dafb4 to 7b369ae Compare April 1, 2026 18:37

mgorny force-pushed the pep-building branch from b7ad00c to d7e1603 Compare April 1, 2026 18:37

rgommers mentioned this pull request May 19, 2026

feat: add experimental PEP 817 variant support scikit-build/scikit-build-core#1284

Merged

mgorny force-pushed the pep-providers branch 3 times, most recently from 93b34f5 to 8a445ad Compare August 17, 2026 14:26

mgorny force-pushed the pep-providers branch from e15a67e to 6c99577 Compare September 1, 2026 13:00

mgorny force-pushed the pep-building branch from d7e1603 to af07c66 Compare September 1, 2026 13:01

mgorny force-pushed the pep-building branch 2 times, most recently from 0ff098b to 405bcb6 Compare September 9, 2026 17:33

mgorny force-pushed the pep-providers branch from a8b327a to 017ce84 Compare September 9, 2026 17:33

mgorny force-pushed the pep-building branch from 405bcb6 to c225d2f Compare September 16, 2026 11:39

mgorny force-pushed the pep-providers branch from 97b5ea0 to e029b64 Compare September 17, 2026 12:52

mgorny force-pushed the pep-building branch from c225d2f to 1f819e6 Compare September 17, 2026 12:52

mgorny force-pushed the pep-providers branch 2 times, most recently from e4f3057 to 1e4b442 Compare September 21, 2026 17:00

rgommers reviewed Sep 22, 2026

View reviewed changes

Comment thread peps/pep-9998.rst Outdated

Comment thread peps/pep-9998.rst Outdated

mgorny force-pushed the pep-building branch 2 times, most recently from eda6717 to df2b8e4 Compare September 28, 2026 16:14

mgorny force-pushed the pep-providers branch from afbca1d to eef86e7 Compare October 13, 2026 11:12

mgorny force-pushed the pep-building branch 2 times, most recently from 6255877 to b9060ff Compare October 13, 2026 16:01

mgorny force-pushed the pep-providers branch 3 times, most recently from c0c345d to 24ec08c Compare October 19, 2026 12:20

mgorny force-pushed the pep-building branch from b84add1 to d40b62e Compare October 20, 2026 14:08

mgorny changed the title ~~PEP 9998: building (draft; do not merge)~~ PEP 9999: building (draft; do not merge) Oct 20, 2026

mgorny added 6 commits October 26, 2026 13:14

[WIP] Building PEP

6764a75

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

Remove old appendix

07d788c

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

Grammar and other enhancements

514552f

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

Add an abstract

f492350

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

Providers are now PEP 850

2549e72

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

9998 → 9999

678326e

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

mgorny force-pushed the pep-building branch from d40b62e to 678326e Compare October 26, 2026 12:14

mgorny changed the base branch from pep-providers to main October 26, 2026 12:15

Move Rationale before Specification

4b1e01d

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

rgommers reviewed Oct 26, 2026

View reviewed changes

mgorny and others added 4 commits October 26, 2026 16:53

Apply batched suggestions from code review

e063f5b

Co-authored-by: Ralf Gommers <ralf.gommers@gmail.com>

Apply one more suggestion

4b5ce22

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

Address more feedback

1b674a8

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

Add a note that static-properties are needed for consistency

067a5a5

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

rgommers reviewed Oct 26, 2026

View reviewed changes

	provided by the user directly (for example, in ``pyproject.toml``) and
	specified by the package author directly (in ``pyproject.toml``) and

Conversation

mgorny commented Mar 2, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rgommers commented Jul 10, 2026 • edited 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!

rgommers commented Oct 26, 2026

Uh oh!

mgorny commented Oct 26, 2026

Uh oh!

mgorny commented Oct 26, 2026

Uh oh!

rgommers left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

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!

Uh oh!

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

mgorny commented Mar 2, 2026 •

edited by github-actions Bot

Loading

read-the-docs-community Bot commented Mar 2, 2026 •

edited

Loading

rgommers commented Jul 10, 2026 •

edited

Loading