PEP 825: clarifications regarding value lists and merging metadata (#4856)

* PEP 825: clarify that value lists need to be sorted

Signed-off-by: Michał Górny <mgorny@quansight.com>

* PEP 825: merging metadata yields same result irrespective of order

This was essentially the goal, but I originally had trouble wording it
properly.

Signed-off-by: Michał Górny <mgorny@quansight.com>

* Set date in the change history

Signed-off-by: Michał Górny <mgorny@quansight.com>

* PEP 825: update the examples to use more readable labels

Signed-off-by: Michał Górny <mgorny@quansight.com>

---------

Signed-off-by: Michał Górny <mgorny@quansight.com>
Co-authored-by: Jonathan DEKHTIAR <jonathan@dekhtiar.com>

Author: mgorny

peps/pep-0825.rst

@@ -245,7 +245,8 @@ present in that wheel's filename.
 
 It has 3 levels. The first level keys are variant labels, the second
 level keys are namespaces, the third level are feature names, and the
-third level values are lists of feature values.
+third level values are sets of feature values, converted to lists,
+sorted lexically.
 
 
 Example
@@ -281,11 +282,11 @@ Example
 
       "variants": {
         // REQUIRED: in variant.json, always a single entry, with the key
-        // matching the variant label ("x8664v3_openblas") and the value
+        // matching the variant label ("x86_64_v3_openblas") and the value
         // specifying its properties (the system must be compatible with both):
         // - blas_lapack :: library :: openblas
         // - x86_64 :: level :: v3
-        "x8664v3_openblas": {
+        "x86_64_v3_openblas": {
           "blas_lapack": {
             "library": ["openblas"]
           },
@@ -318,8 +319,8 @@ the variant metadata across multiple variant wheels of the same package
 version and the index-level metadata file is consistent. They MAY
 require that keys other than ``variants`` have exactly the same values,
 or they may carefully merge their values, provided that no conflicting
-information is introduced, and the resolution results within a subset of
-variants do not change.
+information is introduced, and the result is the same irrespective of
+the order in which the wheels are processed.
 
 This file SHOULD NOT be considered immutable and MAY be updated in a
 backward compatible way at any point (e.g. when adding a new variant).
@@ -346,10 +347,10 @@ like:
         // if a null variant is present
         "null": {},
 
-        // "x8664v3_openblas" label corresponds to:
+        // "x86_64_v3_openblas" label corresponds to:
         // - blas_lapack :: library :: openblas
         // - x86_64 :: level :: v3
-        "x8664v3_openblas": {
+        "x86_64_v3_openblas": {
           "blas_lapack": {
             "library": ["openblas"]
           },
@@ -358,10 +359,10 @@ like:
           }
         },
 
-        // "x8664v4_mkl" label corresponds to:
+        // "x86_64_v4_mkl" label corresponds to:
         // - blas_lapack :: library :: mkl
         // - x86_64 :: level :: v4
-        "x8664v4_mkl": {
+        "x86_64_v4_mkl": {
           "blas_lapack": {
             "library": ["mkl"]
           },
@@ -680,7 +681,7 @@ Example
     index = "https://pypi.anaconda.org/mgorny/simple"
     wheels = [
         { url = "https://pypi.anaconda.org/mgorny/simple/numpy/2.3.4/numpy-2.3.4-cp314-cp314-linux_x86_64-openblas.whl", hashes = {} },
-        { url = "https://pypi.anaconda.org/mgorny/simple/numpy/2.3.4/numpy-2.3.4-cp314-cp314-linux_x86_64-x8664v4_mkl.whl", hashes = {} },
+        { url = "https://pypi.anaconda.org/mgorny/simple/numpy/2.3.4/numpy-2.3.4-cp314-cp314-linux_x86_64-x86_64_v4_mkl.whl", hashes = {} },
         { url = "https://pypi.anaconda.org/mgorny/simple/numpy/2.3.4/numpy-2.3.4-cp314-cp314-macosx_13_0_x86_64-accelerate.whl", hashes = {} },
         { url = "https://pypi.anaconda.org/mgorny/simple/numpy/2.3.4/numpy-2.3.4-cp314-cp314-macosx_13_0_x86_64-openblas.whl", hashes = {} },
     ]
@@ -693,8 +694,8 @@ Example
 
     [packages.variant_json.variants]
     null = { }
-    x8664v3_openblas = { "blas_lapack" = { "library" = ["openblas"]}, "x86_64" = { "level" = ["v3"]}  }
-    x8664v4_mkl = { "blas_lapack" = { "library" = ["mkl"]}, "x86_64" = { "level" = ["v4"]}  }
+    x86_64_v3_openblas = { "blas_lapack" = { "library" = ["openblas"]}, "x86_64" = { "level" = ["v3"]}  }
+    x86_64_v4_mkl = { "blas_lapack" = { "library" = ["mkl"]}, "x86_64" = { "level" = ["v4"]}  }
 
 
 Suggested implementation logic for tools (non-normative)
@@ -802,6 +803,10 @@ the variant metadata is mirrored in a JSON file published on the index.
 This enables installers to obtain variant property mapping without
 having to fetch individual wheels.
 
+Since JSON format does not feature a set type, sets are represented as
+sorted lists. Sorting ensures that tools can safely use equality
+comparison over dictionaries.
+
 The variant ordering algorithm has been proposed with the assumption
 that variant properties take precedence over Platform compatibility
 tags, as they are primarily used to express user preferences. This
@@ -955,7 +960,7 @@ interpreter) incompatibility, while other tools could still use it.
 However, the authors decided it safer to break the backwards
 compatibility. Additionally, reusing tags posed a potential risk of
 wheel labels being incorrectly combined with compressed tag sets. For
-example, a ``manylinux_2_27_x86_64.manylinux_2_28_x86_64+x8664v3`` tag
+example, a ``manylinux_2_27_x86_64.manylinux_2_28_x86_64+x86_64_v3`` tag
 would be incorrectly deemed compatible because of the
 ``manylinux_2_27_x86_64`` part.
 
@@ -988,6 +993,14 @@ and Zanie Blue.
 Change History
 ==============
 
+- 09-Mar-2026
+
+  - Clarified that feature values in ``variants`` dictionary are sets,
+    and that they ought to be sorted when serializing.
+  - Changed the rule for merging variant metadata to state that the
+    result must be the same irrespective of wheel order. This conveys
+    the goal of avoiding ambiguous results clearer.
+
 - 17-Feb-2026
 
   - Initial version, split from :pep:`817` draft.