From 735233da9fc0d5e5b2ed647eed71ef42f3636591 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Tue, 18 Aug 2026 20:06:24 +0200 Subject: [PATCH 1/4] PEP 825: indicate that a future spec may cover transition to new ver MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- peps/pep-0825.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 3de55594b80..d2bbfbee069 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -218,7 +218,9 @@ will be promoted to version ``1.0.0``. If a backwards incompatible change is done to the specification, the major version number MUST be incremented, and the remaining version components MUST be zeroed. Tools MUST reject metadata with a major -version number that they do not support. +version number that they do not support. The specification update +introducing such a change can provide further backwards compatibility +and transition considerations. If a backwards compatible change is done to the specification, the minor version number MUST be incremented, and the patch number MUST be zeroed. From a35962559d352b13a91f0575640c87fc2eb0f961 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Tue, 18 Aug 2026 20:11:26 +0200 Subject: [PATCH 2/4] PEP 825: disallow optional attributes for index-level metadata entry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- peps/pep-0825.rst | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index d2bbfbee069..8ff3e79910d 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -346,9 +346,8 @@ It should follow the rules for files in the :ref:`packaging:simple-repository-api`, except that the optional metadata attributes 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. +meaningful for that file. Indexes MUST skip these attributes, and tools +MUST ignore them. This file uses the same structure as `variant metadata`_, except that the ``variants`` object is index-scoped and it MUST list all variants @@ -1179,11 +1178,9 @@ The index support aims to account for three scenarios: 2. An index implementation that has more complete wheel support but does not wish to implement full variant wheel support immediately. The - index needs only to permit the user to upload said JSON file. To - account for minimalistic implementation, the specification permits - the index to treat said file similarly to a wheel, including - publishing attributes such as ``yanked``, as long as their values do - not prevent clients from working. + index needs to permit the user to upload said JSON file and it needs + to account for it in the wheel listings, but it does not need to + process variant metadata directly. 3. An index implementation that implements complete wheel variant support. Such an index will parse uploaded variant wheels, and @@ -1548,6 +1545,12 @@ and Zanie Blue. Change History ============== +- 19-Aug-2026 + + - Strengthened the index rules to require that the irrelevant optional + attributes are not published by the index, and that they are ignored + by tools. + - 10-Aug-2026 - Decoupled most of the specification from `index-level metadata`_, From e53d94a485af3e95c1593d6374d143067f85b0a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Tue, 18 Aug 2026 20:18:12 +0200 Subject: [PATCH 3/4] PEP 825: suggest how to deal with variants missing from index JSON MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- peps/pep-0825.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 8ff3e79910d..031636d8a29 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -355,6 +355,10 @@ available on the package index for the package version in question. It MUST be consistent with the `variant metadata`_ of the individual wheels, as specified in `metadata consistency`_. +If clients find variant wheels with labels that are not listed in the +index-level metadata file, they MAY either elect to ignore these wheels +or to fetch variant metadata from them directly. + This file SHOULD NOT be considered immutable and MAY be updated in a backward compatible way at any point (e.g. when adding a new variant). @@ -863,8 +867,9 @@ behavior would be to: the non-variant wheels instead. 6. Map the variant labels into sets of variant properties using the combined variant metadata. If any of the labels present in wheel - filenames are missing from it, assume that the respective wheels are - incompatible. + filenames are missing from it, either assume that the respective + wheels are incompatible or read their metadata directly from wheels, + as indicated in step 5. 7. Obtain the ordered lists of compatible variant properties. The mechanism for this will be specified in a subsequent PEP. 8. Filter and order variants based on the lists of compatible @@ -1550,6 +1555,8 @@ Change History - Strengthened the index rules to require that the irrelevant optional attributes are not published by the index, and that they are ignored by tools. + - Added a suggestion for dealing with missing variants in index-level + metadata file. - 10-Aug-2026 From 2edb0db7a58a7edc505845d23621a19be1d495f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Tue, 18 Aug 2026 20:20:12 +0200 Subject: [PATCH 4/4] PEP 825: allow JSON cache to be used outside indexes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Michał Górny --- peps/pep-0825.rst | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 031636d8a29..8ab8e115c6a 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -366,6 +366,11 @@ Variant indexes MAY elect to either auto-generate the file from the uploaded variant wheels or allow the user to manually generate it themselves and upload it to the index. +The same ``{name}-{version}-variants.json`` file can also be published +alongside variant wheels in other (tool-specific) collections of wheels. +An example of this would be a directory referenced by the commonly used +``--find-links`` option. + The ``foo-1.2.3-variants.json`` corresponding to the package with two wheel variants, one of them listed in the previous example, would look like: @@ -1557,6 +1562,8 @@ Change History by tools. - Added a suggestion for dealing with missing variants in index-level metadata file. + - Indicated that the index-level metadata file can also be used in + non-standard sources of wheels. - 10-Aug-2026