PEP 825: reword ordering to avoid introducing new terms

peps/pep-0825.rst

@@ -379,17 +379,23 @@ like:
 Variant ordering
 ----------------
 
-To determine which variant wheel to install when multiple wheels are
-compatible, variants MUST be totally ordered by their variant
-properties.
+To determine which wheel to install when multiple wheels are compatible,
+variant metadata MUST be taken into consideration. This section
+describes the selection based on the assumption that all wheels are
+sorted in the order of priority. Tools that select wheels using
+different algorithms MUST implement them so that they arrive at the same
+result.
 
 For the purpose of ordering, variant properties are grouped into
 features, and features into namespaces. For every namespace, the tool
 MUST obtain an ordered list of compatible features, and for every
 feature, an ordered list of compatible values. The method of obtaining
 these lists will be defined in a subsequent PEP.
 
-The default ordering MUST be performed equivalent to the following
+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
 algorithm:
 
 1. Construct the ordered list of namespaces by copying the value of the
@@ -422,41 +428,42 @@ algorithm:
    After this step, a list of ordered property values is available for
    every feature. This is ``value_order`` in the example.
 
-4. For every compatible variant, determine the most preferred value
-   corresponding to every feature in that variant. This is done by
-   finding among the values present in the variant properties the one
-   that has the lowest position 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
-   ``Variant.best_value_properties()`` method in the example.
+4. For every group, determine the most preferred value corresponding to
+   every variant feature present. This is done by finding among the
+   values present in the variant properties the one that has the lowest
+   position 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.
 
 5. For every item in the list constructed in the previous step,
    construct a sort key that is a 3-tuple consisting of
    its namespace, feature name and best feature value indices in the
    respective ordered lists. This is done by the ``property_key()``
    function in the example.
 
-6. For every compatible variant, sort the list constructed in step 4
-   using the sort keys constructed in step 5, in ascending order. This
-   is done by the ``Variant.sorted_properties()`` method 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
+   ``VariantWheel.sorted_properties()`` method in the example.
 
-7. To order variants, compare their sorted lists from step 6. If the
-   sort keys at the first position are different, the variant with the
+7. To order groups, compare their sorted lists from step 6. If the
+   sort keys at the first position are different, the group with the
    lower key is sorted earlier. If they are the same, compare the keys
    at the second position, and so on, until either a tie-breaker is
-   found or the list in one of the variants is exhausted. In the latter
-   case, the variant with more keys is sorted earlier. As a fallback,
-   if both variants have the same number of keys, they are ordered
-   lexically by their variant label, ascending. This is done by the
+   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 ``Variant.__lt__()``.
+   being implemented as ``VariantWheel.__lt__()``.
 
-After this process, the variant wheels are sorted from the most
-preferred to the least preferred. The algorithm sorts the null variant
-after all the other variants. The non-variant wheel MUST be ordered
-after the null variant. Multiple wheels with the same variant property
-set (and multiple non-variant wheels) MUST then be ordered according to
-their platform compatibility tags.
+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.
 
 The tools MAY provide options to override the default ordering, for
 example by specifying a preference for specific namespaces, features
@@ -465,7 +472,8 @@ variants, or to select a particular variant.
 
 Alternatively, the sort algorithm for variant wheels could be described
 using the following pseudocode. For simplicity, this code does not
-account for non-variant wheels or tags.
+account for non-variant wheels or the subsequent ordering by platform
+compatibility tags.
 
 .. code:: python
 
@@ -530,7 +538,7 @@ account for non-variant wheels or tags.
         )
 
 
-    class Variant:
+    class VariantWheel:
         """Example class exposing properties of a variant wheel"""
 
         label: str
@@ -571,13 +579,13 @@ account for non-variant wheels or tags.
             return self.label < other.label
 
 
-    # A list of variants to sort.
-    variants: list[Variant] = [...]
+    # A list of variant wheels to sort.
+    variant_wheels: list[VariantWheel] = [...]
 
 
-    # 7. Order variants by comparing their sorted properties
-    # (see Variant.__lt__())
-    variants.sort()
+    # 7. Order variant wheels by comparing their sorted properties
+    # (see VariantWheel.__lt__())
+    variant_wheels.sort()
 
 
 Environment markers