diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index a89f110b747..0a36ed50041 100644 --- a/peps/pep-0825.rst +++ b/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