Apply suggestions from code review

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

Author: mgorny

peps/pep-0817.rst

@@ -46,8 +46,8 @@ proposes:
   dynamically detect platform attributes and select the most suitable
   wheel.
 
-The goal is for a familiar ``[uv] pip install <package>`` to provide
-the best user experience.
+The goal is for the obvious installation commands (``{tool} install <package>``)
+to select the most appropriate wheel, and provide the best user experience.
 
 
 Motivation
@@ -73,7 +73,7 @@ These include maintaining separate package indexes for different
 hardware configurations, bundling all potential variants into a single
 wheel of considerable size, or using separate package names
 (``mypackage-gpu``, ``mypackage-cpu``, etc.). Each of these approaches
-has significant drawbacks.
+has significant drawbacks and potential security implications.
 
 According to the `2024 Python Developers Survey
 <https://lp.jetbrains.com/python-developers-survey-2024/#purposes-for-using-python>`__,
@@ -144,13 +144,13 @@ tags:
 While these tags effectively handle traditional compatibility
 dimensions, they cannot express modern requirements:
 
-**GPU Accelerated Frameworks:** A wheel filename like
+* **GPU Accelerated Frameworks:** A wheel filename like
 ``torch-2.9.0-cp313-cp313-manylinux_2_28_x86_64.whl`` provides no
 indication whether it supports NVIDIA CUDA, AMD ROCm,
 Intel XPU, or is CPU-only. Users cannot determine compatibility
 with their GPU hardware or drivers.
 
-**CPU Instruction Sets:** A wheel filename like
+* **CPU Instruction Sets:** A wheel filename like
 ``numpy-2.3.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl``
 provides no indication whether it uses optimized instructions
 for modern processors with AVX512, SHA-NI, and other specialized
@@ -159,7 +159,7 @@ require specific CPU baseline. This forces maintainers to either use
 inconvenient runtime dispatching, or rely on the lowest common
 denominator, leaving performance improvements on the table.
 
-**Runtime Dependencies:** Scientific computing packages often depend on
+* **Runtime Dependencies:** Scientific computing packages often depend on
 specific BLAS implementations (OpenBLAS vs Intel MKL), MPI providers
 (OpenMPI vs MPICH), or other system libraries that affect both
 functionality and performance. The current wheel format is not able to
@@ -191,8 +191,8 @@ Projects such as `PyTorch <https://pytorch.org/get-started/locally/>`__
 and `RAPIDS <https://docs.rapids.ai/install/#selector>`__
 currently distribute packages that approximate "variants" through
 separate package indexes with custom URLs. We will use the
-example of PyTorch, while the problem, the workarounds and the impact
-for users also apply to other packages.
+example of PyTorch, while the problem, the workarounds, and the impact
+on users also apply to other packages.
 
 .. figure:: pep-0817/pytorch_variant_selector.png
     :alt: A grid-based selector for PyTorch versions. Individual rows
@@ -219,7 +219,7 @@ Tools need to implement special handling for the way PyTorch uses local
 version segments. These requirements break the pattern that packages
 are usually installed with. Problems with installing PyTorch
 are a very common point of user confusion. To quantify this, on
-2025-12-05, 552 out of 8136, or 6.8%, of issues on `uv's issue tracker
+2025-12-05, 552 out of 8136 (6.8%), of issues on `uv's issue tracker
 <https://github.com/astral-sh/uv/issues/>`__ contained the term "torch".
 
 Wheel variants remove this special casing and make GPU and TPU packages
@@ -286,8 +286,7 @@ clearly highlights the limit of such an approach. End users need to
 carefully read the CuPy installation documentation to figure out
 which package they need. Continuously having to create new PyPI
 packages, request increasing limits and keep the build infrastructure
-and documentation in sync, requires significant effort from software
-maintainers.
+and documentation in sync, requires significant effort from maintainers.
 
 .. code:: text
 
@@ -305,8 +304,8 @@ maintainers.
     cupy-rocm-6-0 cupy-rocm-6-1 cupy-rocm-6-2 cupy-rocm-6-3
 
 
-Extra-Dependency as variants
-''''''''''''''''''''''''''''
+Package extras as variants
+''''''''''''''''''''''''''
 
 `JAX <https://docs.jax.dev/en/latest/installation.html>`__ uses a
 plugin-based approach. The central ``jax`` package provides a number of
@@ -316,7 +315,7 @@ e.g. ``jax[cuda12]`` or ``jax[tpu]``. This is far from ideal as
 installation, and consequently dependency chains, a fundamental expected
 behavior in the Python ecosystem, are dysfunctional.
 
-JAX includes 12 extra selectors to cover all use cases - many of which
+JAX includes 12 extras to cover all use cases - many of which
 overlap and could be misleading to users if they don't read the
 documentation in detail.
 
@@ -376,18 +375,18 @@ preventing proper provenance tracking.
 Ecosystem fragmentation
 '''''''''''''''''''''''
 
-The lack of standardized variant support has led to ecosystem
-fragmentation:
+The lack of standardized support for solving against hardware
+and ABI requirements has led to ecosystem fragmentation:
 
-**Inconsistent User Experience**: Each package uses different
-installation methods, creating confusion and reducing discoverability.
+* **Inconsistent User Experience**: Each project uses different
+ installation methods, creating confusion and reducing discoverability.
 
-**Development Tool Complications**: Installation tools, IDEs, and CI/CD
-systems struggle to handle non-standard installation requirements.
+* **Development Tool Complications**: Installers, IDEs, and CI/CD
+  systems struggle to handle non-standard installation requirements.
 
-**Error-proneness**: The established workarounds are often error-prone,
-and in the past they have lead to issues such as downloading incorrect
-artifacts.
+* **Fragility**: The established workarounds are often error-prone,
+  and in the past they have lead to issues such as downloading incorrect
+  artifacts.
 
 
 Impact on scientific computing and AI/ML workflows
@@ -736,18 +735,22 @@ end to ensure that the existing filename validation algorithms reject
 it:
 
 - If both the build tag and the variant label are present, the filename
-  contains too many components.
+  contains too many components. Example:
 
-  Example:
-  ``numpy-2.3.2-1-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl``
+  .. code-block:: text
+  
+     numpy-2.3.2-1-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
+                                                    ^^^^^^^^^^
 
 - If only the variant label is present, the Python tag at third position
   will be misinterpreted as a build number. Since the build number must
   start with a digit and no Python tags at the time start with digits,
-  the filename is considered invalid.
+  the filename is considered invalid. Example:
 
-  Example:
-  ``numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl``
+  .. code-block:: text
+  
+     numpy-2.3.2-cp313-cp313t-musllinux_1_2_x86_64-x86_64_v3.whl
+                 ^^^^^
 
 This behavior was confirmed for a number of existing tools:
 `auditwheel
@@ -760,7 +763,7 @@ This behavior was confirmed for a number of existing tools:
 <https://github.com/pypa/pip/blob/c46141c29c3646a3328bc4e51d354cc732fb1432/src/pip/_internal/models/wheel.py#L38-L46>`__,
 `poetry
 <https://github.com/python-poetry/poetry/blob/1c04c65149776ae4993fa508bef53373f45c66eb/src/poetry/utils/wheel.py#L23-L27>`__,
-`uv
+and `uv
 <https://github.com/astral-sh/uv/blob/f6a9b55eb73be4f1fb9831362a192cdd8312ab96/crates/uv-distribution-filename/src/wheel.rs#L182-L299>`__.
 
 
@@ -776,7 +779,7 @@ to group features defined by a single provider, and to avoid conflicts
 should multiple providers define a feature with the same name. This
 permits independent governance and evolution of every namespace.
 
-The keys are restricted to lowercase letters, digits and underscores.
+The keys are restricted to lowercase letters, digits, and underscores.
 Uppercase characters are disallowed to avoid different spellings of the
 same name. The character set for values is more relaxed, to permit
 values resembling versions.
@@ -793,7 +796,7 @@ boolean logic.
 Variant properties are serialized into a structured 3-tuple format
 inspired by Trove Classifiers in :pep:`301`:
 
-::
+.. code-block:: text
 
     {namespace} :: {feature_name} :: {feature_value}
 
@@ -1180,7 +1183,7 @@ dependencies pinned to different versions could prevent different
 plugins from being installed simultaneously in the same environment.
 
 It is recommended that these tools vendor, reimplement or lock the most
-commonly used plugins to specific specific wheels after verifying
+commonly used plugins to specific wheels after verifying
 their trustworthiness, to enable the ability to securely install variant
 wheels out-of-the-box. To reduce the maintenance costs, repositories of
 such vetted plugins could be maintained collaboratively and shared
@@ -1253,7 +1256,7 @@ This is equivalent to the following regular expression:
 ``^[0-9a-z._]{1,16}$``.
 
 Every label must uniquely correspond to a specific set of variant
-properties, same for all wheels using the same label within a single
+properties, which must be the same for all wheels using the same label within a single
 package version. Variant labels should be specified at wheel build time,
 as human-readable strings. The label ``null`` is reserved for the null
 variant and must use an empty set of variant properties.
@@ -1370,8 +1373,8 @@ The top-level object is a dictionary rooted at a specific point in the
 containing file. Its individual keys are sub-dictionaries that are
 described in the subsequent sections, along with the requirements for
 their presence. The tools must ignore unknown keys in the dictionaries
-to permit future backwards compatible updates to the PEP. However, users
-should not introduce custom keys to avoid potential future conflicts.
+for forwards compatibility of updates to the PEP. However, users
+MUST NOT use unsupported keys to avoid potential future conflicts.
 
 A `JSON schema <https://json-schema.org/>`_ is included in the Appendix
 of this PEP, to ease comprehension and validation of the metadata