PEP 685: Conform to PEP 12, address textual errors and improve clarity and phrasing

pep-0685.rst

@@ -1,7 +1,7 @@
 PEP: 685
 Title: Comparison of extra names for optional distribution dependencies
 Author: Brett Cannon <[email protected]>
-Discussions-To: https://discuss.python.org/t/pep-685-comparison-of-extra-names-for-optional-distribution-dependencies/14141
+Discussions-To: https://discuss.python.org/t/14141
 Status: Draft
 Type: Standards Track
 Content-Type: text/x-rst
@@ -12,75 +12,81 @@ Post-History: 08-Mar-2022
 Abstract
 ========
 
-This PEP specifies how to normalize `distribution _extra_ <Provides-Extra_>`_
+This PEP specifies how to normalize `distribution extra <Provides-Extra_>`_
 names when performing comparisons.
-This prevents tools from either failing to find an extra name or
+This prevents tools from either failing to find an extra name, or
 accidentally matching against an unexpected name.
 
 
 Motivation
 ==========
 
-The `Provides-Extra`_ core metadata specification says that an extra's
+The `Provides-Extra`_ core metadata specification states that an extra's
 name "must be a valid Python identifier".
-:pep:`508` says that the value of an ``extra`` marker may contain a
+:pep:`508` specifies that the value of an ``extra`` marker may contain a
 letter, digit, or any one of ``.``, ``-``, or ``_`` after the initial character.
-Otherwise there is no other specification at https://packaging.python.org
+Otherwise, there is no other `PyPA specification
+<https://packaging.python.org/en/latest/specifications/>`_
 which outlines how extra names should be written or normalization for comparison.
-Due to the amount of packaging-related code out there,
+Due to the amount of packaging-related code in existence,
 it is important to evaluate current practices by the community and
-standardize on a practice that doesn't break most code while being
+standardize on one that doesn't break most code, while being
 something tool authors can agree to following.
 
-The issue of no standard was brought forward via the discussion at
-https://discuss.python.org/t/what-extras-names-are-treated-as-equal-and-why/7614
-where the extra ``adhoc-ssl`` was not considered equal to the name
+The issue of there being no standard was brought forward by an
+`initial discussion <https://discuss.python.org/t/7614>`__
+noting that the extra ``adhoc-ssl`` was not considered equal to the name
 ``adhoc_ssl`` by pip.
 
 
 Rationale
 =========
 
-:pep:`503` specifies how to normalize distribution names:
-``re.sub(r"[-_.]+", "-", name).lower()``.
+:pep:`503` specifies how to normalize distribution names::
+
+    re.sub(r"[-_.]+", "-", name).lower()
+
 This collapses any run of the substitution character down to a single
 character,
 e.g. ``---`` gets collapsed down to ``-``.
 This does not produce a valid Python identifier as specified by the
 core metadata specification for extra names.
 
 `Setuptools does normalization <https://github.com/pypa/setuptools/blob/b2f7b8f92725c63b164d5776f85e67cc560def4e/pkg_resources/__init__.py#L1324-L1330>`__
-via ``re.sub('[^A-Za-z0-9.-]+', '_', name).lower()``.
+via::
+
+    re.sub('[^A-Za-z0-9.-]+', '_', name).lower()
+
 The use of an underscore/``_`` differs from PEP 503's use of a
 hyphen/``-``.
 Runs of characters, unlike PEP 503, do **not** get collapsed,
 e.g. ``___`` stays the same.
 
 For pip, its
-"extra normalisaton behaviour is quite convoluted and eratic",
+"extra normalisation behaviour is quite convoluted and erratic",
 and so its use is not considered.
 
 
 Specification
 =============
 
-[Describe the syntax and semantics of any new language feature.]
-
 When comparing extra names, tools MUST normalize the names being compared
-using the equivalent semantics of
-``re.sub('[^A-Za-z0-9.-]+', '_', name).lower()``.
+using the equivalent semantics of::
+
+    re.sub('[^A-Za-z0-9.-]+', '_', name).lower()
+
 This normalizes any extra name previously allowed by :pep:`508` in a
-consistent fashion with setuptools.
+fashion consistent with setuptools.
 
 For tools writing `core metadata`_,
 they MUST write out extra names in their normalized form.
-This applies to the ``Provides-Extra`` field and the ``Provides-Dist``
-field both when specifying extras for a distribution as well as the
+This applies to the ``Provides-Extra`` and ``Provides-Dist`` fields,
+both when specifying extras for a distribution as well as the
 ``extra`` marker.
-This will also help enforce the curren requirement from the core
+This will also help enforce the current requirement from the core
 metadata specification that extra names be valid Python identifiers.
 
-Tools generating metadata MUST also raise an error if a user specified
+Tools generating metadata MUST raise an error if a user specified
 two or more extra names which would normalize to the same name.
 
 
@@ -93,20 +99,19 @@ as independent options, but instead as a single extra.
 It is hoped that relying on setuptools' algorithm for normalization
 will minimize the breakage from this.
 
-As distributions make new releases using tools which implement this
-PEP,
+As distributions make new releases using tools which implement this PEP,
 the backwards-compatibility issues will become less of a concern.
 
 
 Security Implications
 =====================
 
-It is possible that a distribution has conflicting extra names and a
+It is possible that for a distribution that has conflicting extra names, a
 tool ends up installing distributions that somehow weaken the security
 of the system.
-This is only hypothetical and if it were to occur it would probably be
-more of a security concern for the distributions involved more than
-the distribution that pulled them in together.
+This is only hypothetical and if it were to occur, it would probably be
+more of a security concern for the distributions specifying such extras names
+rather than the distribution that pulled them in together.
 
 
 How to Teach This
@@ -120,7 +125,7 @@ names which conflict.
 Reference Implementation
 ========================
 
-No reference implementation is provided,
+No reference implementation is provided aside from the code above,
 but the expectation is the `packaging project`_ will provide a
 function in its ``packaging.utils`` that will implement extra name
 normalization.
@@ -136,7 +141,7 @@ Normalize names according to PEP 503
 ------------------------------------
 
 For backwards-compatibility concerns,
-it was decided not to follow :pep:`503` and how it normalizes
+it was decided not to strictly follow how :pep:`503` normalizes
 distribution names.