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: Copyedit and fix various minor issues following further changes (#2428) 

* Update headers & fix reST syntax, links & punctuation

* Fix grammar & clarity issues, improve phrasing & avoid rep

* Restore citations as originally intended
This commit is contained in:
CAM Gerlach 2022-03-16 15:35:17 -05:00 committed by GitHub
parent 9a7e3b26a2
commit 819e9cb020
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 34 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
pep-0685.rst
View File

@ -7,7 +7,7 @@ Status: Draft
Type: Standards Track Type: Standards Track
Content-Type: text/x-rst Content-Type: text/x-rst
Created: 08-Mar-2022 Created: 08-Mar-2022
Post-History: 08-Mar-2022 Post-History: `08-Mar-2022 <https://discuss.python.org/t/14141>`__
Abstract Abstract
@ -28,13 +28,13 @@ name "must be a valid Python identifier".
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 `PyPA specification Otherwise, there is no other `PyPA specification
<https://packaging.python.org/en/latest/specifications/>`_ <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 normalized for comparison.
Due to the amount of packaging-related code in existence, 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 one that doesn't break most code, while being standardize on one that doesn't break most existing code, while being
something tool authors can agree to following. something tool authors can agree to following.
The issue of there being no standard was brought forward by an The issue of there being no consistent standard was brought forward by an
`initial discussion <https://discuss.python.org/t/7614>`__ `initial discussion <https://discuss.python.org/t/7614>`__
noting that 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 22. ``adhoc_ssl`` by pip 22.
@ -47,27 +47,29 @@ Rationale
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 characters ``-``, ``_`` and ``.``
character, down to a single ``-``.
e.g. ``---`` gets collapsed down to ``-``. For example, ``---`` ``.`` and ``__`` all get converted to just ``-``.
This does **not** produce a valid Python identifier as specified by This does **not** produce a valid Python identifier, per
the core metadata 2.2 specification for extra names. the core metadata 2.2 specification for extra names.
`Setuptools 60 does normalization <https://github.com/pypa/setuptools/blob/b2f7b8f92725c63b164d5776f85e67cc560def4e/pkg_resources/__init__.py#L1324-L1330>`__ `Setuptools 60 performs normalization <https://github.com/pypa/setuptools/blob/b2f7b8f92725c63b164d5776f85e67cc560def4e/pkg_resources/__init__.py#L1324-L1330>`__
via:: via::
re.sub(r'[^A-Za-z0-9-.]+', '_', name).lower() re.sub(r'[^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/``-``. and it also normalizes characters outside of those allowed by :pep`508`.
Runs of ``.`` and ``-``, unlike PEP 503, do **not** get collapsed, Runs of ``.`` and ``-``, unlike PEP 503, do **not** get normalized to one ``_``,
e.g. ``..`` stays the same. e.g. ``..`` stays the same. To note, this is inconsistent with this function's
docstring, which *does* specify that all non-alphanumeric characters
(which would include ``-`` and ``.``) are normalized and collapsed.
For pip 22, its For pip 22, its
"extra normalisation behaviour is quite convoluted and erratic" [pip-erratic]_, "extra normalisation behaviour is quite convoluted and erratic" [pip-erratic]_
and so its use is not considered. and so its use is not considered.
.. [pip-erratic] https://discuss.python.org/t/what-extras-names-are-treated-as-equal-and-why/7614/10? .. [pip-erratic] Tzu-ping Chung on Python Discourse <https://discuss.python.org/t/7614/10
Specification Specification
@ -96,39 +98,38 @@ name is provided as appropriate for the specified core metadata version.
If an older core metadata version is specified and the name would be If an older core metadata version is specified and the name would be
invalid with newer core metadata versions, invalid with newer core metadata versions,
tools SHOULD warn the user. tools SHOULD warn the user.
Tools SHOULD warn users when an invalid extra name is read and not use Tools SHOULD warn users when an invalid extra name is read and SHOULD not use
the name to avoid ambiguity. the name to avoid ambiguity.
Tools MAY raise an error instead of a warning when reading an Tools MAY raise an error instead of a warning when reading an
invalid name if they so desire. invalid name, if they so desire.
Backwards Compatibility Backwards Compatibility
======================= =======================
Moving to :pep:`503` normalization and :pep:`508` name acceptance, it Moving to :pep:`503` normalization and :pep:`508` name acceptance
allows for all preexisting, valid names to continue to be valid. allows for all preexisting, valid names to continue to be valid.
Based on research looking at a collection of wheels on PyPI [pypi-results]_, Based on research looking at a collection of wheels on PyPI [pypi-results]_,
the risk of extra name clashes is limited to 73 clashes when considering the risk of extra name clashes is limited to 73 instances when considering
even invalid names, all extras names on PyPI, valid or not (not just those within a single package)
while *only* looking at valid names leads to only 3 clashes: while *only* looking at valid names leads to only 3 clashes:
1. dev-test: dev_test, dev-test, dev.test * ``dev-test``: ``dev_test``, ``dev-test``, ``dev.test``
2. dev-lint: dev-lint, dev.lint, dev_lint * ``dev-lint``: ``dev-lint``, ``dev.lint``, ``dev_lint``
3. apache-beam: apache-beam, apache.beam * ``apache-beam``: ``apache-beam``, ``apache.beam``
By requiring tools writing core metadata to only record the normalized name, By requiring tools writing core metadata to only record the normalized name,
the issue of preexisting, invalid extra names should be diminished over the issue of preexisting, invalid extra names should diminish over time.
time.
.. [pypi-results] https://discuss.python.org/t/pep-685-comparison-of-extra-names-for-optional-distribution-dependencies/14141/17?u=brettcannon .. [pypi-results] Paul Moore on Python Discourse https://discuss.python.org/t/14141/17
Security Implications Security Implications
===================== =====================
It is possible that for a distribution that has conflicting extra names, 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 dependencies that somehow weaken the security
of the system. of the system.
This is only hypothetical and if it were to occur, This is only hypothetical and if it were to occur,
it would probably be more of a security concern for the distributions it would probably be more of a security concern for the distributions
@ -149,7 +150,7 @@ Reference Implementation
No reference implementation is provided aside from the code above, 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`` module that will implement extra name
normalization. normalization.
It will also implement extra name comparisons appropriately. It will also implement extra name comparisons appropriately.
Finally, if the project ever gains the ability to write out metadata, Finally, if the project ever gains the ability to write out metadata,
@ -162,11 +163,12 @@ Rejected Ideas
Using setuptools 60's normalization Using setuptools 60's normalization
----------------------------------- -----------------------------------
Initially this PEP proposed following setuptools to try and minimize Initially, this PEP proposed using setuptools ``safe_extra()`` for normalization
backwards-compatibility issues. to try to minimize backwards-compatibility issues.
But after checking various wheels on PyPI, However, after checking various wheels on PyPI,
it became clear that standardizing **all** naming on :pep:`508` and it became clear that standardizing **all** naming on :pep:`508` and
:pep:`503` semantics was easier and better long-term. :pep:`503` semantics was easier and better long-term,
while causing minimal backwards compatibility issues.
Open Issues Open Issues