From 49e262f22028043544a458be7f0000a7a29e3c31 Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Wed, 9 Mar 2022 12:50:00 -0600 Subject: [PATCH] PEP 685: Conform to PEP 12, address textual errors and improve clarity and phrasing (#2396) --- pep-0685.rst | 69 ++++++++++++++++++++++++++++------------------------ 1 file changed, 37 insertions(+), 32 deletions(-) diff --git a/pep-0685.rst b/pep-0685.rst index 082cf9688..14ee5e08f 100644 --- a/pep-0685.rst +++ b/pep-0685.rst @@ -1,7 +1,7 @@ PEP: 685 Title: Comparison of extra names for optional distribution dependencies Author: Brett Cannon -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,37 +12,40 @@ Post-History: 08-Mar-2022 Abstract ======== -This PEP specifies how to normalize `distribution _extra_ `_ +This PEP specifies how to normalize `distribution 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 +`_ 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 `__ +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 ``-``. @@ -50,37 +53,40 @@ This does not produce a valid Python identifier as specified by the core metadata specification for extra names. `Setuptools does normalization `__ -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.