PEP 825: Wheel Variants, Package Format (split from PEP 817)

Yeah, I think it’s worth stating explicitly. My experience has been that you can never be too explicit in a PEP - users are surprisingly adept at finding ways to make use of loopholes :slightly_smiling_face:

On the same principle of you can never be too explicit, I think it’s worth explicitly listing what “consistency requirements” you mean here. It’s surprisingly easy for someone to assume that what you think is clearly a consistency requirement, is actually just an example of one possible situation…

Also, I’d tend to avoid wording like “at fault” - it makes it feel like a matter of assigning blame. Better (IMO) would be to say something like

Publishers are responsible for ensuring that the following consistency requirements are met. When a user is referencing multiple published sources (e.g., multiple indexes) it is the user’s responsibility to ensure that all publishers are consistent with each other. Tools can simply assume consistency, and no requirements are placed on what tools must do if the data provided is not consistent.
(List the consistency requirements here…)

That’s wordy, but only in the interests of being painfully explicit :slightly_smiling_face:

Honestly, I think you’re probably best placed as the authors to make judgements on how the information should be presented. Just focus on the basic rule that you should be painfully explicit, and not leave anything to the reader’s imagination, and you should be good. If there’s any particular cases you aren’t sure about, pop a quick post here and I’ll give you my view (or DM me if you prefer, although I’ll respond just as quickly to public posts). And if you’re still having trouble deciding, you can always post a draft of what you’re thinking[1] and I’ll let you know how it looks to me.

But if you want my gut instinct, I’d tend to start with a list of the consistency constraints, all in one place, something like I described above, and see how that looked.


  1. No pressure to be polished, work in progress can be as rough as you like ↩︎

4 Likes