diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index ef28081cc..7187e7784 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -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 @@ -60,7 +60,7 @@ all of the needed fields. Example:: - Metadata-Version: 2.2 + Metadata-Version: 2.3 .. _core-metadata-name: @@ -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: @@ -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. @@ -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:: @@ -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 ================== diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst index d2046e911..ab33de726 100644 --- a/source/specifications/dependency-specifiers.rst +++ b/source/specifications/dependency-specifiers.rst @@ -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`. diff --git a/source/specifications/entry-points.rst b/source/specifications/entry-points.rst index eab99b41a..6c94a25fb 100644 --- a/source/specifications/entry-points.rst +++ b/source/specifications/entry-points.rst @@ -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.