Incorporate Vinay's direct reference feedback
* Syntax becomes "from URL" instead of "is URL" * Now a distinct alternative to version specifiers rather than a subclause of one
This commit is contained in:
Nick Coghlan
parent
c7ac54a9b9
commit
b1126e367c
33
pep-0426.txt
33
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 ``<hash-algorithm>=<expected-hash>`` as part of the URL
|
||||
including a ``<hash-algorithm>=<expected-hash>`` 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::
|
||||
|
|
|
|||
141
pep-0440.txt
141
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 ``<hash-algorithm>=<expected-hash>`` 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 ``@<tag>`` 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 ``<hash-algorithm>=<expected-hash>`` 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 ``@<tag>`` 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
|
||||
|
|
|
|||
Loading…
Reference in New Issue