PEP 725: expand Specification section

Author: rgommers

peps/pep-0725.rst

@@ -445,6 +445,42 @@ Specification
 If metadata is improperly specified then tools MUST raise an error to notify
 the user about their mistake.
 
+DepURL
+------
+
+A DepURL implements a scheme for identifying packages that is meant to be
+portable across packaging ecosystems. Its design is::
+
+    dep:type/namespace/name@version?qualifiers#subpath
+
+``dep:`` is a fixed string, and always present. ``type`` and ``name`` are
+required, other components are optional. Component definitions:
+
+- ``type`` (required): MUST be either a `PURL`_ ``type``, or ``virtual``.
+- ``namespace`` (optional): MUST be a `PURL`_ ``namespace``, or a namespace in
+  the DepURL central registry (see :pep:`700`). FIXME: PEP number
+- ``name`` (required): MUST be a name that parses as a valid `PURL`_ ``name``.
+  Tools MAY warn or error if a name is not present in the DepURL central
+  registry (:pep:`700`).
+- ``version`` (optional): MUST be one of:
+
+  - A regular `version specifier`_ (PEP 440 semantics) as a single version or
+    version range, with the restriction that only the following operators may
+    be used: ``>=``, ``>``, ``<``, ``<=``, ``==``, ``,``.
+  - A `PURL`_ percent-encoded version string.
+
+- ``qualifiers`` (optional): MUST parse as a valid `PURL`_ ``qualifier``.
+- ``subpath`` (optional): MUST parse as a valid `PURL`_ ``subpath``.
+
+
+External dependency specifiers
+------------------------------
+
+External dependency specifiers MUST contain a DepURL, and MAY contain
+environment markers with the same syntax as used in regular `dependency
+specifiers`_ (as originally specified in :pep:`508`).
+
+
 Changes in Core Metadata
 ------------------------
 
@@ -459,7 +495,8 @@ Additions
 
 Two new fields are added to Core Metadata:
 
-- ``Requires-External-Dep``. An external requirement expressed as a ``dep:`` URL.
+- ``Requires-External-Dep``. An external requirement expressed as an external
+  dependency specifier string.
 - ``Provides-External-Extra``. An *extra* group that carries external dependencies
   (as found in ``Requires-External-Dep``) only.
 
@@ -490,72 +527,73 @@ to be present on the system already.
 ``build-requires``/``optional-build-requires``
 ''''''''''''''''''''''''''''''''''''''''''''''
 
-- Format: Array of ``dep:`` strings (``build-requires``) and a table
-  with values of arrays of ``dep:`` strings (``optional-build-requires``)
+- Format: Array of external dependency specifiers (``build-requires``) and a
+  table with values of arrays of external dependency strings
+  (``optional-build-requires``)
 - `Core metadata`_: N/A
 
 The (optional) external build requirements needed to build the project.
 
 For ``build-requires``, it is a key whose value is an array of strings. Each
 string represents a build requirement of the project and MUST be formatted as
-a valid ``dep:`` string.
+a valid external dependency string.
 
 For ``optional-build-requires``, it is a table where each key specifies an
 extra set of build requirements and whose value is an array of strings. The
-strings of the arrays MUST be valid ``dep:`` strings.
+strings of the arrays MUST be valid external dependency strings.
 
 ``host-requires``/``optional-host-requires``
 ''''''''''''''''''''''''''''''''''''''''''''
 
-- Format: Array of ``dep:`` strings (``host-requires``) and a table
-  with values of arrays of ``dep:`` strings (``optional-host-requires``)
-- `Core metadata`_: N/A
+- Format: Array of external dependency strings (``host-requires``) and a table
+  with values of arrays of external dependency strings (``optional-host-requires``) -
+  `Core metadata`_: N/A
 
 The (optional) external host requirements needed to build the project.
 
 For ``host-requires``, it is a key whose value is an array of strings. Each
 string represents a host requirement of the project and MUST be formatted as
-a valid ``dep:`` string.
+a valid external dependency string.
 
 For ``optional-host-requires``, it is a table where each key specifies an
 extra set of host requirements and whose value is an array of strings. The
-strings of the arrays MUST be valid ``dep:`` strings.
+strings of the arrays MUST be valid external dependency strings.
 
 ``dependencies``/``optional-dependencies``
 ''''''''''''''''''''''''''''''''''''''''''
 
-- Format: Array of ``dep:`` strings (``dependencies``) and a table
-  with values of arrays of ``dep:`` strings (``optional-dependencies``)
+- Format: Array of external dependency strings (``dependencies``) and a table
+  with values of arrays of external dependency strings
+  (``optional-dependencies``)
 - `Core metadata`_: ``Requires-External-Dep``, ``Provides-External-Extra``
 
 The (optional) runtime dependencies of the project.
 
 For ``dependencies``, it is a key whose value is an array of strings. Each
-string represents a dependency of the project and MUST be formatted as either a
-valid ``dep:`` string. Each string must be added to `Core Metadata`_ as a
+string represents a dependency of the project and MUST be formatted as a valid
+external dependency string. Each string must be added to `Core Metadata`_ as a
 ``Requires-External-Dep`` field.
 
 For ``optional-dependencies``, it is a table where each key specifies an *extra*
 and whose value is an array of strings. The strings of the arrays MUST be valid
-``dep:`` strings. For each ``optional-dependencies`` group:
+external dependency strings. For each ``optional-dependencies`` group:
 
 - The name of the group MUST be added to `Core Metadata`_ as a
   ``Provides-External-Extra`` field.
-- The ``dep:`` URLs in that group MUST be added to `Core Metadata`_ as a
-  ``Requires-External-Dep`` field, with the corresponding ``; extra == 'name'``
-  environment marker.
+- The external dependency specifiers in that group MUST be added to `Core
+  Metadata`_ as a ``Requires-External-Dep`` field, with the corresponding ``;
+  extra == 'name'`` environment marker.
 
 ``dependency-groups``
 '''''''''''''''''''''
 
 - Format: A table where each key is the name of the group, and the values are
-  arrays of ``dep:`` strings, tables, or a mix of both.
+  arrays of external dependency strings, tables, or a mix of both.
 - `Core metadata`_: N/A
 
-PEP 735 -style dependency groups, but using ``dep:`` URLs instead of PEP 508 strings as
-dependency specifiers. Every other detail (e.g. group inclusion, name normalization)
-follows the official `Dependency Groups specification
-<https://packaging.python.org/en/latest/specifications/dependency-groups/>`__.
+PEP 735 -style dependency groups, but using external dependency specifiers
+instead of PEP 508 strings. Every other detail (e.g. group inclusion, name
+normalization) follows the official `dependency groups specification`_.
 
 Examples
 --------
@@ -1017,6 +1055,9 @@ CC0-1.0-Universal license, whichever is more permissive.
 .. _setuptools metadata: https://setuptools.readthedocs.io/en/latest/setuptools.html#metadata
 .. _SPDX: https://spdx.dev/
 .. _PURL: https://github.com/package-url/purl-spec/
+.. _version specifier: https://packaging.python.org/en/latest/specifications/version-specifiers/
+.. _dependencies specifier: https://packaging.python.org/en/latest/specifications/dependency-specifiers/
+.. _dependency groups specification: https://packaging.python.org/en/latest/specifications/dependency-groups/
 .. _packageurl-python: https://pypi.org/project/packageurl-python/
 .. _vers: https://github.com/package-url/purl-spec/blob/version-range-spec/VERSION-RANGE-SPEC.rst
 .. _vers implementation for PURL: https://github.com/package-url/purl-spec/pull/139