PEP 685: Conform to PEP 12, address textual errors and improve clarity and phrasing (#2396)
This commit is contained in:
CAM Gerlach
GitHub
parent
20f7ce8aa7
commit
49e262f220
69
pep-0685.rst
69
pep-0685.rst
|
|
@ -1,7 +1,7 @@
|
|||
PEP: 685
|
||||
Title: Comparison of extra names for optional distribution dependencies
|
||||
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
|
||||
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_ <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 ``-``.
|
||||
|
|
@ -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 <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.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue