From e34c49671b375c92db1dd780a113258861bfa0f0 Mon Sep 17 00:00:00 2001 From: Matt Wozniski Date: Wed, 8 Jan 2025 15:04:47 -0500 Subject: [PATCH 1/2] Document that Requires-Dist can use explicit URLs The core-metadata documentation currently implies that `Requires-Dist` can only use name-based specifiers, but then references PEP 508 which allows for URL based specifiers. Update the documentation to reflect this alternative specifier format. --- source/specifications/core-metadata.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index c1ce528e7..e155f8add 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -539,19 +539,21 @@ Requires-Dist (multiple use) The field format specification was relaxed to accept the syntax used by popular publishing tools. -Each entry contains a string naming some other distutils -project required by this distribution. +Each entry contains a string naming some other distribution required by this +distribution. -The format of a requirement string contains from one to four parts: +A requirement string has one mandatory and three optional parts. * A project name, in the same format as the ``Name:`` field. 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. 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 +* A comma-separated list of 'extra' names in square brackets, like + ``[extra1,extra2]``. These names are defined by the required + project, referring to specific features which may need extra + dependencies. The names MUST conform to the restrictions specified + by the ``Provides-Extra:`` field. +* Either a version specifier or an ``@`` sign followed by a URL. + Tools parsing the format should accept optional parentheses around + a version specifier, but tools generating it should not use parentheses. * An environment marker after a semicolon. This means that the requirement is only needed in the specified conditions. From 8fda67804e0745900bc78e2d59e89fe8c85552e0 Mon Sep 17 00:00:00 2001 From: Matt Wozniski Date: Fri, 10 Jan 2025 17:50:59 -0500 Subject: [PATCH 2/2] Address review feedback --- source/specifications/core-metadata.rst | 19 +++++++++---------- source/specifications/version-specifiers.rst | 1 + 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/source/specifications/core-metadata.rst b/source/specifications/core-metadata.rst index e155f8add..ea781de5d 100644 --- a/source/specifications/core-metadata.rst +++ b/source/specifications/core-metadata.rst @@ -544,28 +544,27 @@ distribution. A requirement string has one mandatory and three optional parts. -* A project name, in the same format as the ``Name:`` field. - The only mandatory part. +* A project name, in :ref:`the same format ` + as the ``Name:`` field. The only mandatory part. * A comma-separated list of 'extra' names in square brackets, like ``[extra1,extra2]``. These names are defined by the required project, referring to specific features which may need extra dependencies. The names MUST conform to the restrictions specified by the ``Provides-Extra:`` field. -* Either a version specifier or an ``@`` sign followed by a URL. - Tools parsing the format should accept optional parentheses around - a version specifier, but tools generating it should not use - parentheses. +* Either a :ref:`version specifier ` or a + :ref:`direct reference `. Tools parsing the format + should accept optional parentheses around a version specifier, but + tools generating it should not use parentheses. If a distribution + requires a direct reference it cannot be uploaded to PyPI, but private + repositories may allow such distributions. * An environment marker after a semicolon. This means that the requirement is only needed in the specified conditions. -See :pep:`508` for full details of the allowed format. +See :ref:`dependency-specifiers` for full details of the allowed format. The project names should correspond to names as found on the `Python Package Index`_. -Version specifiers must follow the rules described in -:doc:`version-specifiers`. - Examples:: Requires-Dist: pkginfo diff --git a/source/specifications/version-specifiers.rst b/source/specifications/version-specifiers.rst index d18596ee0..a670926c2 100644 --- a/source/specifications/version-specifiers.rst +++ b/source/specifications/version-specifiers.rst @@ -1078,6 +1078,7 @@ Examples * ``~=3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and not version 3.2.0 or later. +.. _direct-references: Direct references =================