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)¹?

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 response².

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?

Specifically note the provision:

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.

This is intended as "you don't have to go out of your way to special case that one file", as long as you don't do something really wrong there.

"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.

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.

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?

The whole point is that you can start the implementation (provided that you're ready to take the risk that the details will change). We say "subsequent PEP" in very specific places, telling you to leave specific gaps. Like "you can implement most of the sort algorithm, just leave the gap for functions that will provide these lists"; even the example below literally provides an implementation with gaps for these functions.

I don't think "guessing" really works here. I suppose you can infer what the implementation will be from PEP 817, or you can do your own thing. Whether this makes you PEP 825 compliant is unclear to me, since the PEP by design is part of the larger series, and therefore full compliance implies implementing all of them. A tool that implements PEP 825 but then diverges from subsequent PEPs does not really implement "variant wheels"; it implements a custom solution that is partially based on "variant wheels" but it is definitely not compliant with the design as a whole, and therefore it is not guaranteed to be interoperable.

OK. Let me think about this some more. The idea was that we split PEP 817 into independent parts, but if it's simply not possible to make those parts independent, then maybe we're better accepting that and going back to the single unified approach with PEP 817. Or maybe this approach of having a series of PEPs that don't work independently, but which need to be accepted or rejected as a whole is the right approach - but I don't know of any prior occasions when this was done, so I'd need to do some research to decide how viable it is.

This ordered list is not well defined if multiple indexes are involved.

See my comment about multiple indexes at the bottom.

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.

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.

Sure, if you want to move this "baseline assumption" into the specification section as a requirement, that works for me.

But it literally does that, in the fragment you've commented on above:

The items in these lists will be provided in specific order that will impact variant wheel ordering.

We're merely trying to provide a bit more context of why this requirement is baked in there.

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.

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 situation¹. That changes the position from "multiple indexes are out of scope" to "behaviour for multiple indexes is tool-defined".

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.

"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 involved¹. 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.

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?

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.

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.

A sponsor isn't needed here because Barry and Donald are co-authors and on the core team, so you can speak to them.