PEP 825: add a non-normative section on multiple sources - Michal

peps/pep-0825.rst

@@ -799,6 +799,63 @@ 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
+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.
+
+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. 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
+  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
+- 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
 =========
 
@@ -1071,13 +1128,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
 ================
@@ -1097,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