diff --git a/peps/pep-0825.rst b/peps/pep-0825.rst index d85876a44f6..39252086ca1 100644 --- a/peps/pep-0825.rst +++ b/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.