PEP 825: Various clarifications#4969
Conversation
Reword the ordering algorithm to avoid introducing new terms. Rather than talking of abstract "variants", operate in the terms of grouping variant wheels by their labels, and creating an additional group for non-variant wheels. Then, sorting by platform compatibility tags becomes a matter of in-group ordering. Hopefully this also avoids discussing the existing ordering algorithm. Signed-off-by: Michał Górny <mgorny@quansight.com> Co-authored-by: konsti <konstin@mailbox.org>
Signed-off-by: Michał Górny <mgorny@quansight.com>
Signed-off-by: Michał Górny <mgorny@quansight.com>
Open issues -> Out of scope
Update Change History (11-May-2026)
Documentation build overview
703 files changed ·
|
| ``requires-python`` or ``yanked``) are not meaningful for that file. | ||
| Indexes MAY publish or skip these attributes, as long as the values do | ||
| not prevent correct operation. Tools MAY either use or ignore these | ||
| values. |
There was a problem hiding this comment.
If you're putting variant.json files in the files section of the JSON response, then you need to follow the existing rules, which say that for each files entry, filename, url, hashes and size are mandatory, and all other keys are optional. There's nothing in the existing spec that suggests that tools can ignore attributes if they are present, and I don't think we should be special-casing variant.json files.
I actually don't understand why you're allowing these fields to be present at all. What's wrong with simply saying that variant.json files must not include any of the optional fields defined in the index spec (with the exception of the upload-time field, which may be present)1?
Honestly, this feels like a problem caused by trying to put variant.json files into a field that's intended to hold details of distribution files. I'd argue that a cleaner design would be to have a separate variant-data field in the project details response2.
Footnotes
-
I'm only making an exception for upload time because I can see cases where it might be useful, in analysing index data. ↩
-
The HTML version of the index would still need to have all the links together, but that should be viewed as secondary, as per PEP 833 (which is not yet approved, but is likely to be). ↩
There was a problem hiding this comment.
Yes, "optional fields" is what we meant. We'll correct this.
For the rest, see rationale. The goal is to support indexes during the transitional period with minimal modifications necessary. Should the tools be rejecting projects if the index gives unnecessary-yet-harmless fields?
| The default ordering MUST be performed equivalent to the following | ||
| MUST obtain a list of compatible features, and for every feature, a list | ||
| of compatible values. The method of obtaining these lists will be | ||
| defined in a subsequent PEP. The items in these lists will be provided |
There was a problem hiding this comment.
"The method of obtaining these lists is not defined (and hence is tool-specific)."
We should avoid making this PEP explicitly dependent on "future PEPs", as if we do so it's impossible to approve this PEP on its own merits.
There was a problem hiding this comment.
I don't really see that contradiction, I think we have to live with some of that tension if we want to avoid having one massive PEP 817. There's other PEPs too which specifically leave gaps for future specifications, and I don't see that as fundamentally different. If we say it's tool-specific, that would be rather misleading, as we don't want to open up the namespace to everyone beyond experimentation, we have the expectation that in the end we'll have a compatibility standard where everyone speak the same language.
There was a problem hiding this comment.
I think we have to live with some of that tension if we want to avoid having one massive PEP 817.
Agreed (although we have to accept that if the tension is too great, a single PEP 817 may be a better approach). The key here is that we have a way to implement PEP 825 in the absence of those other PEPs. If we can't start implementation work once PEP 825 is (provisionally) accepted, there's no point in accepting it independently. So regardless of what you might prefer, anything not specified in PEP 825 will be tool-defined. When the follow-up PEP XXX comes along, people who correctly guessed what it would say will be ready, and everyone else will have to change their implementation, but we can't know what the answer will be in advance. I'd rather we made it clear that's the situation, rather than having people think they can't start implementation work because parts of the behaviour need a further PEP to specify them.
There's other PEPs too which specifically leave gaps for future specifications
Maybe I'm getting too concerned about this. Can you give me some examples and I'll check how they handle the situation?
|
|
||
| 1. Construct the ordered list of namespaces by copying the value of the | ||
| ``default-priorities.namespace`` key from `index-level metadata`_. | ||
| This is ``namespace_order`` in the example. |
There was a problem hiding this comment.
This ordered list is not well defined if multiple indexes are involved.
There was a problem hiding this comment.
See my comment about multiple indexes at the bottom.
| precedence) and therefore they always need to be ordered by the package | ||
| maintainer. | ||
| While a future PEP will define how variant properties are provided, a | ||
| baseline assumption is made that the compatible properties will be |
There was a problem hiding this comment.
This shouldn't be an assumption, it should be explicitly required in this PEP. Then this sentence can be reworded something along these lines:
This PEP simply requires that compatible properties are provided in a specific order corresponding to their preference. We do not state how tools will provide this ordered list, but a future PEP is planned which will standardise the mechanism.
There was a problem hiding this comment.
Shouldn't the rationale section be describing why were the specific decisions made in the specification part, rather than stating what is required (I.e. effectively repeating specification)? I dare say the "context" is the whole point of having a rationale in the first place.
There was a problem hiding this comment.
Sure, if you want to move this "baseline assumption" into the specification section as a requirement, that works for me.
| properties as data without having to change the algorithm. | ||
|
|
||
| A future PEP will define how the ordering for features and values is | ||
| provided. However, namespaces are governed independently and considered |
There was a problem hiding this comment.
Same here. You need to say what this PEP requires, so that tools can (in principle) implement their own mechanism for providing an ordering. The fact that we'll standardise that mechanism in a future PEP isn't important here, except as context.
| A future PEP will define how the ordering for features and values is | ||
| provided. However, namespaces are governed independently and considered | ||
| on equal footing, and therefore there will be no standard ordering for | ||
| them. Instead, the package maintainer will decide which namespaces have |
There was a problem hiding this comment.
Conversely, here you're saying "the package maintainer will decide", but you haven't specified how they record those decisions in the variant metadata. Is this information recorded by manually editing the package.json files, or is it held somewhere else?
There was a problem hiding this comment.
For the wheel file, it's "Variant metadata → Default priorities". For how the data ends up in that file, subsequent PEP concerning building packages (which should literally mirror the data in pyproject.toml, but saying that right now will only extend the PEP beyond its scope).
There was a problem hiding this comment.
OK, let's reword this as
on equal footing, and therefore there will be no standard ordering for
them. Instead, the ordering of namespaces will be explicitly stated in
thevariants.jsonfile (which is provided by the package maintainer as
part of the build process).
That clarifies that the "decision" is simply a matter of supplying the correct data in the appropriate file, and not some yet-to-be-defined process. You could reword the next sentence similarly, as overriding the ordering is actually just amending that file.
Basically, by being a bit more explicit, you can avoid some uncertainty. That's all, really.
| - determining which variant properties are compatible with the system | ||
| - building variant wheels | ||
|
|
||
| In addition to that, the following questions are left undefined: |
There was a problem hiding this comment.
The question is well-defined, what you are saying is that you aren't going to answer the question.
Which means that this PEP doesn't support installation from multiple sources of wheels. I don't think that's an acceptable position to take, as installing from multiple sources is an extremely common scenario, and if this PEP doesn't support it, that's a significant usability problem.
IMO, what you need to do is identify all of the places in the PEP where having wheels from multiple sources would cause an issue (I've noted a few of them above) and explicitly state in those places that the PEP doesn't define behaviour in that situation1. That changes the position from "multiple indexes are out of scope" to "behaviour for multiple indexes is tool-defined".
Footnotes
-
My gut feeling is that if you do that, the variant ordering algorithm will look a bit of a mess. If that's the case, then that's a good thing, honestly, as it will expose the fact that the PEP relies on some form of index ordering mechanism. Procedurally, that's a problem, as standardising an index ordering mechanism is a whole other can of worms. But I'd rather we faced that issue than simply ignoring it and ending up with a standard that can't be implemented properly by tools that don't support index priority. ↩
There was a problem hiding this comment.
Which means that this PEP doesn't support installation from multiple sources of wheels. I don't think that's an acceptable position to take, as installing from multiple sources is an extremely common scenario, and if this PEP doesn't support it, that's a significant usability problem.
We're specifically say "undefined", not "not supported". Tools can support multiple index in any shape they want, by virtue of the spec saying nothing about it.
That changes the position from "multiple indexes are out of scope" to "behaviour for multiple indexes is tool-defined".
Can you explain what the difference between those two is? Currently, there is no spec for multiple index support: Multiple indexes are out of scope in any other PEP, we're just writing it out explicitly because otherwise people complained about the absence of that, and it's still tool-defined, as tool make choices about multiple indexes right now, in the absence of a spec.
There was a problem hiding this comment.
"Multiple indexes are out of scope" means that an implementation that doesn't allow multiple sources for variant wheels is PEP compliant. That seems to me like it would be a severe limitation on the usability of variants, especially as it would effectively disallow installing from a local directory of wheels (because in the absence of an index, each wheel is its own independent source of variant data).
On the other hand, "behaviour for multiple indexes is tool-defined" means that PEP-compliant implementations need to support multiple indexes/sources, but they get to choose the behaviour in those specific places where the PEP says that behaviour is undefined.
I appreciate that it's a subtle distinction, but IMO it's important. The precise wording doesn't matter to me, but the difference in semantics does.
Multiple indexes are out of scope in any other PEP
I don't know of any other PEP/standard where it matters whether multiple indexes are involved1. This PEP is different precisely because the ordering algorithm is described in terms that assume a single variant.json file is applicable to all wheels being considered, and that means it does matter if the wheels come from multiple places.
Footnotes
-
If you're aware of any, please let me know and I'll check how they handle the situation. ↩
There was a problem hiding this comment.
Could you point us to a document explaining this difference?
I don't really understand how "tool-defined" implies that something has to be implemented. Isn't "reject as not supported" also a valid tool-defined behavior?
Also, does this mean that a tool that currently does not support multiple sources at all won't be able to be compliant with variant wheels without actually implementing support for multiple sources, i.e. something it currently didn't need to do when installing regular wheels?
There was a problem hiding this comment.
No, I can't point you to a document. This isn't a technical term with a precise definition, it's a matter of how the PEP reads to me. And by extension, how I believe it could be read in the future by others - I'm basing this on my experience with other standards where we've had problems after the fact because people have interpreted imprecise wording in a way that we hadn't originally intended.
I don't think this side discussion is helping. It's a minor point in isolation, and it's threatening to overwhelm the main issue I'm trying to draw attention to, which is that I don't see how we can simply ignore (or "leave to tool implementers" if you prefer) the question of how to calculate ordering when faced with multiple sources of information to combine. At the end of the day, the PEP will need to address this issue if it's going to be accepted. I've tried to read the ordering algorithm as described in the PEP multiple times now, and every time I've got stuck, usually because I can't work out how I'd generalise the given algorithm to handle multiple sources (something I expect to have to do for pip, where "pick the first index" isn't a valid option unless we can assume all indexes have the same data).
To be very explicit here (please don't take this as any sort of threat, it's not intended that way, but I do want to be sure there's no misunderstanding), I'm currently not seeing a way I can accept the PEP if it doesn't somehow clarify how tools are supposed to handle multiple sources. I'm trying to help fix that problem, but if my comments are having the opposite effect, I should probably just state the issue and leave it to you to decide how to take things forward.
The PEP doesn't say who the sponsor is (that's something that should be fixed, by the way), but I'd recommend you speak to them as well - they should be able to help navigate the process around incorporating feedback like this, if it's a problem.
Co-authored-by: Paul Moore <p.f.moore@gmail.com>
3 participants
No functional changes, but clarifications to the variant ordering algorithm, index support and scope.
PEP 123: Summary of changes)