Skip to content
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
PEP 825: clarify index-level metadata in simple repository API
  • Loading branch information
mgorny authored and konstin committed May 10, 2026
commit 68f49fc6cf40f75d61f278845888db0365fb2b11
16 changes: 11 additions & 5 deletions peps/pep-0825.rst
Original file line number Diff line number Diff line change
Expand Up @@ -308,11 +308,17 @@ there MUST exist a corresponding ``{name}-{version}-variants.json``
file. The ``{name}`` and ``{version}`` placeholders correspond to the
package name and version, normalized according to the same rules as
wheel files, as found in the :ref:`packaging:wheel-file-name-spec` of
the Binary Distribution Format specification. The exact URL where the
file is hosted is insignificant, but a link to it MUST be present on all
index pages where the variant wheels are linked. It is presented in the
same simple repository format as source distribution and wheel links in
the index, including an (OPTIONAL) hash.
the Binary Distribution Format specification.

The exact URL where the file is hosted is insignificant, but it MUST
be provided in all the responses where the variant wheels are included.
It should follow the rules for files in the
:ref:`packaging:simple-repository-api`, except that the various metadata
served by the index (such as ``core-metadata``, ``dist-info-metadata``,
``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.
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

  1. I'm only making an exception for upload time because I can see cases where it might be useful, in analysing index data.

  2. 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).

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


This file uses the same structure as `variant metadata`_, except that
the ``variants`` object MUST list all variants available on the package
Expand Down