Skip to content

Add changes introduced by PEP 685 #1070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Apr 14, 2022
Merged

Add changes introduced by PEP 685 #1070

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 35 additions & 6 deletions source/specifications/core-metadata.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,8 +45,8 @@ Metadata-Version

.. versionadded:: 1.0

Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1"
and "2.2".
Version of the file format; legal values are "1.0", "1.1", "1.2", "2.1",
"2.2", and "2.3".

Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
greater than the highest version they support, and MUST fail if
Expand All @@ -60,7 +60,7 @@ all of the needed fields.

Example::

Metadata-Version: 2.2
Metadata-Version: 2.3


.. _core-metadata-name:
Expand All @@ -84,6 +84,12 @@ Example::

Name: BeagleVote

To normalize a distribution name for comparison purposes, it should be
lowercased with all runs of the characters ``.``, ``-``, or ``_`` replaced with
a single ``-`` character. This can be done using the following snippet of code
(as specified in :pep:`503`)::

re.sub(r"[-_.]+", "-", name).lower()

.. _core-metadata-version:

Expand Down Expand Up @@ -510,7 +516,8 @@ The format of a requirement string contains from one to four parts:
The only mandatory part.
* A comma-separated list of 'extra' names. These are defined by
the required project, referring to specific features which may
need extra dependencies.
need extra dependencies. The names MUST conform to the restrictions
specified by the ``Provides-Extra:`` field.
* A version specifier. Tools parsing the format should accept optional
parentheses around this, but tools generating it should not use
parentheses.
Expand Down Expand Up @@ -613,9 +620,20 @@ Provides-Extra (multiple use)
=============================

.. versionadded:: 2.1
.. versionchanged:: 2.3
:pep:`685` restricted valid values to be unambiguous (i.e. no normalization
required). For older metadata versions, value restrictions were brought into
line with ``Name:`` and normalization rules were introduced.

A string containing the name of an optional feature. A valid name consists only
of lowercase ASCII letters, ASCII numbers, and hyphen. It must start and end
with a letter or number. Hyphens cannot be followed by another hyphen. Names are
limited to those which match the following regex (which guarantees unambiguity)::

^([a-z0-9]|[a-z0-9]([a-z0-9-](?!-))*[a-z0-9])$

A string containing the name of an optional feature. Must be a valid Python
identifier. May be used to make a dependency conditional on whether the

The specified name may be used to make a dependency conditional on whether the
optional feature has been requested.

Example::
Expand All @@ -640,6 +658,17 @@ respectively.
It is legal to specify ``Provides-Extra:`` without referencing it in any
``Requires-Dist:``.

When writing data for older metadata versions, names MUST be normalized
following the same rules used for the ``Name:`` field when performing
comparisons. Tools writing metadata MUST raise an error if two
``Provides-Extra:`` entries would clash after being normalized.

When reading data for older metadata versions, tools SHOULD warn when values
for this field would be invalid under newer metadata versions. If a value would
be invalid following the rules for ``Name:`` in any core metadata version, the
user SHOULD be warned and the value ignored to avoid ambiguity. Tools MAY choose
to raise an error when reading an invalid name for older metadata versions.


Rarely Used Fields
==================
Expand Down
2 changes: 2 additions & 0 deletions source/specifications/dependency-specifiers.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,3 +10,5 @@ component is defined in :pep:`508`.

The environment markers section in this PEP supersedes the environment markers
section in :pep:`345`.

Restrictions on names for extras is defined in :pep:`685`.
3 changes: 2 additions & 1 deletion source/specifications/entry-points.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,8 @@ Within a value, readers must accept and ignore spaces (including multiple
consecutive spaces) before or after the colon, between the object reference and
the left square bracket, between the extra names and the square brackets and
colons delimiting them, and after the right square bracket. The syntax for
extras is formally specified as part of :pep:`508` (as ``extras``).
extras is formally specified as part of :pep:`508` (as ``extras``) and
restrictions on values specified in :pep:`685`.
For tools writing the file, it is recommended only to insert a space between the
object reference and the left square bracket.

Expand Down