From 0e560f713f3f2b08ead00a3dbb26825d6a6cb68e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Tue, 30 Jun 2026 14:16:14 +0200 Subject: [PATCH 1/3] PEP 825: add a non-normative section on multiple sources 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 | 60 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 53 insertions(+), 7 deletions(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index a89f110b747..0f463c9b664 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -799,6 +799,59 @@ To generate the ``{name}-{version}-variants.json`` file: ``default-priorities.namespace`` value +Installing wheels from multiple sources (non-normative) +------------------------------------------------------- + +As of the time of writing, there are no accepted standards addressing +the support for installing packages from multiple sources, and the +existing tools (such as ``pip`` and ``uv``) disagree on the exact +behavior. This problem is described in more detail in the informational +:pep:`766`. Variant wheels expand the problem scope, as the variant +metadata that influences the selection among multiple wheels is scoped +at index level, and therefore the metadata acquired from different +indexed cannot be compared or combined in a meaningful way. For these +reasons, the specification does not attempt to standardize a behavior, +but instead considers it implementation-defined and provides a few +non-normative suggestions on the possible solutions. + +It is entirely valid for tools not to support this behavior, either by +not providing support for using multiple sources at all, or by rejecting +to proceed if more than one of the sources includes variant wheels. + +When processing variant wheels from different sources, it is recommended +to consider their variant metadata in isolation. In particular, tools +should not assume that matching variant labels or namespaces across +different sources are equal. + +If index priorities are supported and considered above platform +compatibility tag level (as in the "index priority" variant described in +:pep:`766`, for example), the tools need to be only concerned about +ordering variant wheels from a single source at a time, and the +algorithm specified in this PEP works without changes. + +If tools need to directly compare wheels from different sources (as in +the "version priority" variant described in :pep:`766`), and only one of +the sources features at least one compatible variant wheel, only wheels +from this source need to be considered, as variants are preferred over +non-variant wheels. + +If tools need to compare variant wheels from different sources and the +variant metadata between them is consistent as specified in +`index-level metadata`_ section, then the method of merging specified +there can be used. + +If the variant metadata is not consistent, there are multiple valid +choices, including but not limited to: + +- refusing to install with an error +- printing a warning and ignoring variant wheels, falling back to + selection among non-variant wheels +- using a deterministic criterion for selecting among multiple + compatible variant wheels, for example by preferring the wheel from + the index that came earlier in the option arguments +- requested additional input from the user + + Rationale ========= @@ -1071,13 +1124,6 @@ The following problems are deferred to subsequent PEPs in the series: - overriding the compatibility detection using static data - building variant wheels -In addition to that, the following matters are left -implementation-defined: - -- Selecting variant wheels from multiple sources. Currently, there is no - standard defined behavior for regular wheels, nor consensus across - different packaging tools on how to handle that. - Acknowledgements ================ From ced7a4b390a5a71cd487e396bde97ee785e95385 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Fri, 3 Jul 2026 16:46:00 +0200 Subject: [PATCH 2/3] Recombine some of Jonathan's ideas 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 | 57 +++++++++++++++++++++++++++-------------------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 0f463c9b664..678db033e20 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -819,29 +819,28 @@ not providing support for using multiple sources at all, or by rejecting to proceed if more than one of the sources includes variant wheels. When processing variant wheels from different sources, it is recommended -to consider their variant metadata in isolation. In particular, tools -should not assume that matching variant labels or namespaces across -different sources are equal. - -If index priorities are supported and considered above platform -compatibility tag level (as in the "index priority" variant described in -:pep:`766`, for example), the tools need to be only concerned about -ordering variant wheels from a single source at a time, and the -algorithm specified in this PEP works without changes. - -If tools need to directly compare wheels from different sources (as in -the "version priority" variant described in :pep:`766`), and only one of -the sources features at least one compatible variant wheel, only wheels -from this source need to be considered, as variants are preferred over -non-variant wheels. - -If tools need to compare variant wheels from different sources and the -variant metadata between them is consistent as specified in -`index-level metadata`_ section, then the method of merging specified -there can be used. - -If the variant metadata is not consistent, there are multiple valid -choices, including but not limited to: +to consider their variant metadata in isolation. Matching variant labels +or namespaces do not establish that they have the same meaning across +sources. + +A tool that searches sources in priority order (for example, the "index +priority" in :pep:`766`) can order variants from one source at a time +using the `variant ordering`_ algorithm, and proceed to the next source +only if the current one has no viable candidates. No cross-source +metadata merge is necessary. + +A tool that collates candidates from all sources before selecting among +them (for example, "version priority" in :pep:`766`) must compare wheels +from different sources directly. For a package version, if exactly one +source provides compatible variant wheels, those variants can be +selected ahead of non-variant wheels, as generally variant wheels are +preferred over non-variant wheels. If multiple sources provide +compatible variants, their metadata can be combined unambiguously only +when the metadata is consistent as specified in the `index-level +metadata`_ section. + +When metadata cannot be combined unambiguously, there is no uniquely +correct global ordering. Valid tool-specific choices include: - refusing to install with an error - printing a warning and ignoring variant wheels, falling back to @@ -849,7 +848,12 @@ choices, including but not limited to: - using a deterministic criterion for selecting among multiple compatible variant wheels, for example by preferring the wheel from the index that came earlier in the option arguments -- requested additional input from the user +- requesting additional input from the user + +These choices can produce a valid installation without guaranteeing a +globally optimal selection. Silently fabricating a combined order or +resolving conflicting label mappings is technically possible, but +discouraged: it fabricates semantics that no source declared. Rationale @@ -1143,6 +1147,11 @@ and Zanie Blue. Change History ============== +- 03-Jul-2026 + + - Added a non-normative guidance for installing variant wheels from + multiple sources. + - 06-Apr-2026 - Added a formal requirement that Python tags must not start with From 6135285eb45a36b6788d1bf6846d8238f0fdbfa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20G=C3=B3rny?= Date: Wed, 8 Jul 2026 12:38:33 +0200 Subject: [PATCH 3/3] Update peps/pep-0825.rst Co-authored-by: Ralf Gommers --- peps/pep-0825.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index 678db033e20..0a36ed50041 100644 --- a/peps/pep-0825.rst +++ b/peps/pep-0825.rst @@ -809,7 +809,7 @@ behavior. This problem is described in more detail in the informational :pep:`766`. Variant wheels expand the problem scope, as the variant metadata that influences the selection among multiple wheels is scoped at index level, and therefore the metadata acquired from different -indexed cannot be compared or combined in a meaningful way. For these +indexes cannot be compared or combined in a meaningful way. For these reasons, the specification does not attempt to standardize a behavior, but instead considers it implementation-defined and provides a few non-normative suggestions on the possible solutions.