PEP 825: provide a high-level ordering overview and clarify

Provide a high-level description of how ordering works and what it is
meant to achieve, in addition to the precise algorithm provided right
now.  Add clarifications to the algorithm, to make it clear in what
order the lists are actually arranged.

Signed-off-by: Michał Górny <mgorny@quansight.com>
Co-authored-by: konstin <konstin@mailbox.org>
Co-authored-by: rgommers <ralf.gommers@gmail.com>

Author: 3 people

peps/pep-0825.rst

@@ -256,7 +256,7 @@ Default priorities
 
 The ``default-priorities`` dictionary defines the ordering of
 namespaces which is used in variant ordering. The exact algorithm is
-described in the `Variant ordering`_ section.
+described in the `Variant ordering and selection`_ section.
 
 The following key is REQUIRED:
 
@@ -462,11 +462,97 @@ consistency`_ and set out in full in
 :ref:`pep825-metadata-consistency`.
 
 
-Variant ordering
-----------------
+Variant ordering and selection
+------------------------------
+
+High-level overview
+'''''''''''''''''''
+
+This specification defines an ordering of wheels based on their variant
+metadata, from the most preferable to the least preferable.
+
+The ordering of wheels by platform compatibility tags is not currently
+defined by the specification, beyond a guideline that more specific
+wheels should be preferred. This has not been a big problem, as usually
+there is only one wheel that is compatible with the system, and where
+there are more, the ordering is either clear or insignificant.
+
+With wheel variants, there can be several compatible wheels per project
+version. We define a total ordering to give package authors and users
+control over wheel preference and to ensure that all tools select the
+same variant without ambiguity. Tools may allow users to override this
+ordering.
+
+Every variant property is a ``namespace :: feature :: value`` triple
+whose components are ranked in that order: by namespace first, then by
+feature within the namespace, then by value within the feature. Only
+properties compatible with the target system take part, and only the highest
+ranking compatible value for each feature. The ranking for namespaces comes
+from the package's variant metadata. The ranking for their features and the
+ranking of values within features will be defined in a subsequent PEP.
+
+Variant wheels sort as Python sorts lists of tuples, each wheel being
+the list of its property triples ordered best first. Where one wheel's
+triples run out, the longer list therefore wins. The intuition is that
+this selects the wheel that makes the best use of the target hardware.
+
+Spelled out: compare two wheels by their best-ranked property triple; if
+those are equal, use the next lower-ranked property as a tiebreaker,
+repeatedly until an ordering is established. Comparing all compatible
+wheels this way yields the most preferred wheel.
+
+As an example, take four variant wheels of a package that ranks the
+``nvidia`` namespace above ``x86_64``:
+
+.. code:: python
 
-This specification defines an ordering between different wheels based on
-the presence of variant metadata.
+    # Rankings, most preferred first. The namespace ranking comes from
+    # the package's variant metadata; the feature and value rankings
+    # will be defined in a subsequent PEP.
+    namespaces = ["nvidia", "x86_64"]
+    features = {"nvidia": ["cuda_version_lower_bound"], "x86_64": ["level"]}
+    values = {
+        "nvidia": {"cuda_version_lower_bound": ["13.0", "12.0"]},
+        "x86_64": {"level": ["v4", "v3", "v2"]},
+    }
+
+    # Each variant label maps to its properties, with only the best
+    # compatible value kept for every feature.
+    variant_wheels = {
+        "gpu": [("nvidia", "cuda_version_lower_bound", "13.0")],
+        "gpu_cpuv2": [("nvidia", "cuda_version_lower_bound", "13.0"),
+                      ("x86_64", "level", "v2")],
+        "gpu_cpuv4": [("nvidia", "cuda_version_lower_bound", "13.0"),
+                      ("x86_64", "level", "v4")],
+        "cpuv4": [("x86_64", "level", "v4")],
+    }
+
+    def rank(prop):
+        """Rank a triple. The ranking lists put the best first, so negate
+        the positions to make a bigger rank mean a better property."""
+        namespace, feature, value = prop
+        return (-namespaces.index(namespace),
+                -features[namespace].index(feature),
+                -values[namespace][feature].index(value))
+
+    def sort_key(label):
+        """Rank a wheel: its property ranks, best first."""
+        return sorted(map(rank, variant_wheels[label]), reverse=True)
+
+    sorted(variant_wheels, key=sort_key, reverse=True)
+    # ['gpu_cpuv4', 'gpu_cpuv2', 'gpu', 'cpuv4']
+
+The ``gpu*`` wheels sort ahead of ``cpuv4`` because their best triple
+is in the higher-ranked ``nvidia`` namespace. ``gpu_cpuv4`` beats
+``gpu_cpuv2`` on their second triple, since ``v4`` outranks ``v2``. Both
+beat ``gpu``, whose triples run out first, as the wheel with more
+properties wins.
+
+The ordering for non-variant wheels remains unchanged.
+
+
+Ordering algorithm
+''''''''''''''''''
 
 For the purpose of ordering, the combined variant metadata for all
 candidate variant wheels MUST be obtained. It can be sourced either from
@@ -481,12 +567,12 @@ features, and features into namespaces. For every namespace, the tool
 MUST obtain a list of compatible features, and for every feature, a list
 of compatible values. The method of obtaining these lists will be
 defined in a subsequent PEP. The items in these lists will be provided
-in specific order that will impact variant wheel ordering.
+ordered from the most preferable to the least preferable.
 
 The compatible wheels corresponding to a particular combination of
-package name, version and build number MUST be grouped by their variant
-label, and a separate group of non-variant wheels MUST be formed. The
-groups of variant wheels MUST then be ordered according to the following
+package name and version MUST be grouped by their variant label, and a
+separate group of non-variant wheels MUST be formed. The groups of
+variant wheels MUST then be ordered according to the following
 algorithm:
 
 1. Construct the ordered list of namespaces by copying the value of the
@@ -502,7 +588,7 @@ algorithm:
 4. For every group, determine the most preferred value corresponding to
    every variant feature present in the variant properties corresponding
    to the group. This is done by finding among the values the one that
-   has the lowest position in the ordered property value list. After
+   has the lowest index in the ordered property value list. After
    this step, a list of features along with their best values is
    available for every variant. This is done in the
    ``VariantWheel.best_value_properties()`` method in the example.
@@ -514,7 +600,9 @@ algorithm:
    function in the example.
 
 6. For every group, sort the list constructed in step 4 using the sort
-   keys constructed in step 5, in ascending order. This is done by the
+   keys constructed in step 5, in ascending order. The resulting list
+   will be ordered from the most preferable feature to the least
+   preferable feature. This is done by the
    ``VariantWheel.sorted_properties()`` method in the example.
 
 7. To order groups, compare their sorted lists from step 6. If the
@@ -524,17 +612,21 @@ algorithm:
    found or the list in one of the groups is exhausted. In the latter
    case, the group with more keys is sorted earlier. As a fallback,
    if both groups have the same number of keys, they are ordered
-   lexically by the variant label, ascending. This is done by the
-   ultimate step of the example algorithm, with the comparison function
-   being implemented as ``VariantWheel.__lt__()``.
+   lexically by the variant label, ascending. The resulting list of
+   groups will be sorted from the most preferable to the least
+   preferable. This is done by the ultimate step of the example
+   algorithm, with the comparison function being implemented as
+   ``VariantWheel.__lt__()``.
 
 The algorithm sorts the group of null variant wheels last, as they
 feature no variant properties. The group of non-variant wheels MUST be
 placed after all the other groups.
 
 Within every group, the wheels MUST then be ordered according to their
-platform compatibility tags. After this process, the variant wheels are
-sorted from the most preferred to the least preferred.
+remaining properties, such as platform compatibility tags and build
+numbers. This specification does not alter this ordering; it remains the
+same as before. After completing this process, the wheels are sorted
+from the most preferred to the least preferred.
 
 The tools MAY provide options to override the default ordering, for
 example by specifying a preference for specific namespaces, features
@@ -696,7 +788,7 @@ The variant markers MUST only be used in dependency specifiers and MUST
 NOT take part in selecting a wheel. These markers gate the individual
 dependency specifiers of a wheel that has already been selected. They
 MUST be evaluated only once variant wheel selection, as described in
-`variant ordering`_, has taken place.
+`variant ordering and selection`_, has taken place.
 
 Their values MUST be determined as follows:
 
@@ -883,9 +975,9 @@ behavior would be to:
 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
-   properties, per `variant ordering`_, and select the most preferred
-   variant. If no variant wheel matched, use the non-variant wheels by
-   their rules.
+   properties and select the most preferred variant, per `variant
+   ordering and selection`_. If no variant wheel matched, use the
+   non-variant wheels by their rules.
 9. If multiple wheels for a given version share the same variant label,
    order them by Platform compatibility tags and build number, and
    select the best wheel.
@@ -1034,8 +1126,8 @@ When a package manager is requested to install ``torch``, in order:
    the list.
 
 5. If variant wheels with multiple different labels remain on the list,
-   the results are sorted per the algorithm in `variant ordering`_.
-   The most preferred label is selected.
+   the results are sorted per the algorithm in `variant ordering and
+   selection`_. The most preferred label is selected.
 
    For example, in this case the ``cuda*`` wheels are ordered by their
    properties, using the lists obtained in step 4. The wheels for CUDA
@@ -1103,9 +1195,9 @@ 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.
+using the `variant ordering and selection`_ 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
@@ -1264,12 +1356,12 @@ and a publisher of variant wheels may still take that route.
 The requirement is what makes several of the mechanisms defined here
 work at all. If the wheels of one release disagreed about namespace
 order, there would be no total order over the variants, so `variant
-ordering`_ would have no defined output and two conforming installers
-could select different wheels from the same inputs. ``pylock.toml``
-inlines combined variant metadata, so non-deterministic combination
-would mean that two lock runs over one release can produce different
-lock files. And the `index-level metadata`_ file could neither be
-generated from the uploaded wheels alone, nor be relied upon once
+ordering and selection`_ would have no defined output and two conforming
+installers could select different wheels from the same inputs.
+``pylock.toml`` inlines combined variant metadata, so non-deterministic
+combination would mean that two lock runs over one release can produce
+different lock files. And the `index-level metadata`_ file could neither
+be generated from the uploaded wheels alone, nor be relied upon once
 generated, since a resolver would then have to fetch every candidate
 wheel to discover the true combined picture.
 
@@ -1319,7 +1411,7 @@ only ``120_real``, much as a dependency that supports a single CPU
 architecture is gated on ``platform_machine``. Where a dependency does
 exist for every value of a feature, it can instead be published as a
 variant package and depended upon unconditionally, leaving the choice to
-`variant ordering`_.
+`variant ordering and selection`_.
 
 Because of this filtering, the variant markers do not depart from the
 established meaning of an environment marker. Every property in
@@ -1342,10 +1434,10 @@ Three consequences of this design are worth noting:
   for every feature it declares (see `variant properties`_).
   ``variant_features`` and ``variant_namespaces`` therefore always list
   every feature and namespace the wheel was built for. This is why the
-  overrides permitted in `variant ordering`_ may not reach past the
-  compatibility filter: a wheel selected in spite of being unsupported
-  could have its properties filtered away, and the dependencies gated on
-  them would silently disappear.
+  overrides permitted in `variant ordering and selection`_ may not reach
+  past the compatibility filter: a wheel selected in spite of being
+  unsupported could have its properties filtered away, and the
+  dependencies gated on them would silently disappear.
 
 - For the null variant, ``variant_label`` is ``"null"`` and the three
   set-valued markers are empty sets, as the null variant has zero
@@ -1610,6 +1702,13 @@ Change History
     The investigation in the appendix settles the question in favour of
     markers, so the Open Issues section has been removed and the
     reasoning recorded in the Rationale instead.
+  - Removed grouping by build numbers, instead relegating them to
+    tie-breaking along with other wheel properties. This reverts a
+    potential change in behavior for non-variant wheels.
+  - Added a high-level overview to `variant ordering and selection`_,
+    clarified that the ordering of the lists used in the algorithm is
+    from the most preferable to the least preferable and that the
+    ordering by platform compatibility tags is not changed.
 
 - 19-Aug-2026