diff --git a/pep-0426.txt b/pep-0426.txt index c91d94261..755c1af41 100644 --- a/pep-0426.txt +++ b/pep-0426.txt @@ -636,7 +636,7 @@ All source URL references SHOULD specify a secure transport mechanism (such as ``https``), include an expected hash value in the URL for verification purposes, or both. If an insecure transport is specified without any hash information, with hash information that the tool doesn't -understand, or with a selected hash algortihm that the tool considers too +understand, or with a selected hash algorithm that the tool considers too weak to trust, automated tools SHOULD at least emit a warning and MAY refuse to rely on the URL. @@ -647,7 +647,7 @@ for source archive hashes. At time of writing, that list consists of ``'sha512'``. For source archive references, an expected hash value may be specified by -including a ``=`` as part of the URL +including a ``=`` entry as part of the URL fragment. For version control references, the ``VCS+protocol`` scheme SHOULD be @@ -926,10 +926,11 @@ Dependency specifications Individual dependencies are typically defined as strings containing a distribution name (as found in the ``name`` field). The dependency name may be followed by an extras specifier (enclosed in square -brackets) and by a version specification (within parentheses). +brackets) and by a version specifier or direct reference (within +parentheses). See `Extras (optional dependencies)`_ for details on extras and PEP 440 -for details on version specifiers. +for details on version specifiers and direct references. The distribution names should correspond to names as found on the `Python Package Index`_; while these names are often the same as the module names @@ -1054,12 +1055,12 @@ depending on this metadistribution. In this field, automated tools: * MUST allow strict version matching -* MAY allow direct reference clauses * MUST NOT allow more permissive version specifiers. +* MAY allow direct references Public index servers SHOULD NOT allow the use of direct references in -uploaded distributions. Direct references are intended as a tool for -software integrators rather than publishers. +uploaded distributions. Direct references are intended primarily as a +tool for software integrators rather than publishers. Distributions that rely on direct references to platform specific binary archives SHOULD define appropriate constraints in their @@ -1084,12 +1085,12 @@ Any extras referenced from this field MUST be named in the `Extras`_ field. In this field, automated tools: * MUST allow strict version matching -* MAY allow direct reference clauses * MUST NOT allow more permissive version specifiers. +* MAY allow direct references Public index servers SHOULD NOT allow the use of direct references in -uploaded distributions. Direct references are intended as a tool for -software integrators rather than publishers. +uploaded distributions. Direct references are intended primarily as a +tool for software integrators rather than publishers. Distributions that rely on direct references to platform specific binary archives SHOULD defined appropriate constraints in their @@ -1155,7 +1156,7 @@ for this distribution.. Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: @@ -1174,7 +1175,7 @@ Any extras referenced from this field MUST be named in the `Extras`_ field. Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: @@ -1203,7 +1204,7 @@ built, the installation is a *deployment* scenario for the dependencies. Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: @@ -1229,7 +1230,7 @@ installing build dependencies. Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: @@ -1262,7 +1263,7 @@ Additional dependencies that may be listed in this field include: Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: @@ -1288,7 +1289,7 @@ installing development dependencies. Automated tools MAY disallow strict version matching clauses and direct references in this field and SHOULD at least emit a warning for such clauses. -Public index servers SHOULD disallow strict version matching clauses and +Public index servers SHOULD NOT allow strict version matching clauses or direct references in this field. Example:: diff --git a/pep-0440.txt b/pep-0440.txt index 0434fd421..79e8bc1eb 100644 --- a/pep-0440.txt +++ b/pep-0440.txt @@ -550,7 +550,6 @@ clause: * ``~=``: `Compatible release`_ clause * ``==``: `Version matching`_ clause * ``!=``: `Version exclusion`_ clause -* ``is``: `Direct reference`_ clause * ``<=``, ``>=``: `Inclusive ordered comparison`_ clause * ``<``, ``>``: `Exclusive ordered comparison`_ clause @@ -679,61 +678,6 @@ match or not as shown:: != 1.1.* # Same prefix, so 1.1.post1 does not match clause -Direct reference ----------------- - -A direct reference includes the direct reference operator ``is`` and -an explicit URL. - -Whether or not direct references are appropriate depends on the specific -use case for the version specifier. Automated tools SHOULD at least issue -warnings and MAY reject them entirely when direct references are used -inappropriately. - -Depending on the use case, some appropriate targets for a direct URL -reference are a source archive, an sdist, a wheel binary archive or a -direct reference to a tag or specific commit in an online version control -system. The exact URLs and targets supported will be automated tool -specific. - -For example, a local source archive may be referenced directly:: - - pip (is file:///localbuilds/pip-1.3.1.zip) - -Alternatively, a prebuilt archive may also be referenced:: - - pip (is file:///localbuilds/pip-1.3.1-py33-none-any.whl) - - -All direct URL references that do not refer to a local file URL SHOULD -specify a secure transport mechanism (such as ``https``), include an -expected hash value in the URL for verification purposes, or both. If an -insecure transport is specified without any hash information, with hash -information that the tool doesn't understand, or with a selected hash -algortihm that the tool considers too weak to trust, automated tools -SHOULD at least emit a warning and MAY refuse to rely on the URL. - -Index servers MAY place additional restrictions on direct references (such -as requiring all references be to files hosted on the index server itself). - -It is RECOMMENDED that only hashes which are unconditionally provided by -the latest version of the standard library's ``hashlib`` module be used -for source archive hashes. At time of writing, that list consists of -``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and -``'sha512'``. - -For source archive and wheel references, an expected hash value may be -specified by including a ``=`` as part of -the URL fragment. - -Version control references, the ``VCS+protocol`` scheme SHOULD be -used to identify both the version control system and the secure transport. - -To support version control systems that do not support including commit or -tag references directly in the URL, that information may be appended to the -end of the URL using the ``@`` notation. - - Inclusive ordered comparison ---------------------------- @@ -815,6 +759,67 @@ Examples not version 3.2.0 or later. +Direct references +================= + +Some automated tools may permit the use of a direct reference as an +alternative to a normal version specifier. A direct reference consists of +the word ``from`` and an explicit URL. + +Whether or not direct references are appropriate depends on the specific +use case for the version specifier. Automated tools SHOULD at least issue +warnings and MAY reject them entirely when direct references are used +inappropriately. + +Public index servers SHOULD NOT allow the use of direct references in +uploaded distributions. Direct references are intended as a tool for +software integrators rather than publishers. + +Depending on the use case, some appropriate targets for a direct URL +reference may be a valid ``source_url`` entry (see PEP 426), an sdist, or +a wheel binary archive. The exact URLs and targets supported will be tool +dependent. + +For example, a local source archive may be referenced directly:: + + pip (from file:///localbuilds/pip-1.3.1.zip) + +Alternatively, a prebuilt archive may also be referenced:: + + pip (from file:///localbuilds/pip-1.3.1-py33-none-any.whl) + +All direct references that do not refer to a local file URL SHOULD +specify a secure transport mechanism (such as ``https``), include an +expected hash value in the URL for verification purposes, or both. If an +insecure transport is specified without any hash information, with hash +information that the tool doesn't understand, or with a selected hash +algorithm that the tool considers too weak to trust, automated tools +SHOULD at least emit a warning and MAY refuse to rely on the URL. + +It is RECOMMENDED that only hashes which are unconditionally provided by +the latest version of the standard library's ``hashlib`` module be used +for source archive hashes. At time of writing, that list consists of +``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and +``'sha512'``. + +For source archive and wheel references, an expected hash value may be +specified by including a ``=`` entry as +part of the URL fragment. + +Version control references, the ``VCS+protocol`` scheme SHOULD be +used to identify both the version control system and the secure transport. + +To support version control systems that do not support including commit or +tag references directly in the URL, that information may be appended to the +end of the URL using the ``@`` notation. + +Remote URL examples:: + + pip (from https://github.com/pypa/pip/archive/1.3.1.zip) + pip (from http://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686) + pip (from git+https://github.com/pypa/pip.git@1.3.1) + + Updating the versioning specification ===================================== @@ -830,13 +835,14 @@ Summary of differences from \PEP 386 * Moved the description of version specifiers into the versioning PEP -* Aadded the "source label" concept to better handle projects that wish to +* Added the "source label" concept to better handle projects that wish to use a non-compliant versioning scheme internally, especially those based on DVCS hashes - -* Added the "compatible release" clause -* Added the "direct reference" clause +* Added the "direct reference" concept as a standard notation for direct + references to resources (rather than each tool needing to invents its own) + +* Added the "compatible release" clause * Added the trailing wildcard syntax for prefix based version matching and exclusion @@ -1032,14 +1038,23 @@ added to make it possible to sensibly define both compatible release clauses and the desired pre- and post-release handling semantics for ``<`` and ``>`` ordered comparison clauses. + +Adding direct references +------------------------ + Direct references are added as an "escape clause" to handle messy real world situations that don't map neatly to the standard distribution model. This includes dependencies on unpublished software for internal use, as well as handling the more complex compatibility issues that may arise when wrapping third party libraries as C extensions (this is of especial concern -to the scientific community). Index servers are given a lot of freedom to -disallow them, since they're intended primarily as a tool for integrators -rather than publishers. +to the scientific community). + +Index servers are deliberately given a lot of freedom to disallow direct +references, since they're intended primarily as a tool for integrators +rather than publishers. PyPI in particular is currently going through the +process of *eliminating* dependencies on external references, as unreliable +external services have the effect of slowing down installation operations, +as well as reducing PyPI's own apparent reliability. References