iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 685: Conform to PEP 12, address textual errors and improve clarity and phrasing (#2396)

This commit is contained in:
CAM Gerlach 2022-03-09 12:50:00 -06:00 committed by GitHub
parent 20f7ce8aa7
commit 49e262f220
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 37 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

69
pep-0685.rst
View File

@ -1,7 +1,7 @@
PEP: 685 PEP: 685
Title: Comparison of extra names for optional distribution dependencies Title: Comparison of extra names for optional distribution dependencies
Author: Brett Cannon <brett@python.org> Author: Brett Cannon <brett@python.org>
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 Status: Draft
Type: Standards Track Type: Standards Track
Content-Type: text/x-rst Content-Type: text/x-rst
@ -12,37 +12,40 @@ Post-History: 08-Mar-2022
Abstract 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. 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. accidentally matching against an unexpected name.
Motivation 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". 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. 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. 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 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. something tool authors can agree to following.
The issue of no standard was brought forward via the discussion at The issue of there being no standard was brought forward by an
https://discuss.python.org/t/what-extras-names-are-treated-as-equal-and-why/7614 `initial discussion <https://discuss.python.org/t/7614>`__
where the extra ``adhoc-ssl`` was not considered equal to the name noting that the extra ``adhoc-ssl`` was not considered equal to the name
``adhoc_ssl`` by pip. ``adhoc_ssl`` by pip.
Rationale Rationale
========= =========
:pep:`503` specifies how to normalize distribution names: :pep:`503` specifies how to normalize distribution names::
``re.sub(r"[-_.]+", "-", name).lower()``.
re.sub(r"[-_.]+", "-", name).lower()
This collapses any run of the substitution character down to a single This collapses any run of the substitution character down to a single
character, character,
e.g. ``---`` gets collapsed down to ``-``. 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. core metadata specification for extra names.
`Setuptools does normalization <https://github.com/pypa/setuptools/blob/b2f7b8f92725c63b164d5776f85e67cc560def4e/pkg_resources/__init__.py#L1324-L1330>`__ `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 The use of an underscore/``_`` differs from PEP 503's use of a
hyphen/``-``. hyphen/``-``.
Runs of characters, unlike PEP 503, do **not** get collapsed, Runs of characters, unlike PEP 503, do **not** get collapsed,
e.g. ``___`` stays the same. e.g. ``___`` stays the same.
For pip, its 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. and so its use is not considered.
Specification Specification
============= =============
[Describe the syntax and semantics of any new language feature.]
When comparing extra names, tools MUST normalize the names being compared When comparing extra names, tools MUST normalize the names being compared
using the equivalent semantics of using the equivalent semantics of::
``re.sub('[^A-Za-z0-9.-]+', '_', name).lower()``.
re.sub('[^A-Za-z0-9.-]+', '_', name).lower()
This normalizes any extra name previously allowed by :pep:`508` in a 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`_, For tools writing `core metadata`_,
they MUST write out extra names in their normalized form. they MUST write out extra names in their normalized form.
This applies to the ``Provides-Extra`` field and the ``Provides-Dist`` This applies to the ``Provides-Extra`` and ``Provides-Dist`` fields,
field both when specifying extras for a distribution as well as the both when specifying extras for a distribution as well as the
``extra`` marker. ``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. 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. 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 It is hoped that relying on setuptools' algorithm for normalization
will minimize the breakage from this. will minimize the breakage from this.
As distributions make new releases using tools which implement this As distributions make new releases using tools which implement this PEP,
PEP,
the backwards-compatibility issues will become less of a concern. the backwards-compatibility issues will become less of a concern.
Security Implications 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 tool ends up installing distributions that somehow weaken the security
of the system. of the system.
This is only hypothetical and if it were to occur it would probably be 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 more of a security concern for the distributions specifying such extras names
the distribution that pulled them in together. rather than the distribution that pulled them in together.
How to Teach This How to Teach This
@ -120,7 +125,7 @@ names which conflict.
Reference Implementation 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 but the expectation is the `packaging project`_ will provide a
function in its ``packaging.utils`` that will implement extra name function in its ``packaging.utils`` that will implement extra name
normalization. normalization.
@ -136,7 +141,7 @@ Normalize names according to PEP 503
------------------------------------ ------------------------------------
For backwards-compatibility concerns, 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. distribution names.