[Python-checkins] peps: Incorporate Vinay's direct reference feedback
nick.coghlan
python-checkins at python.org
Wed Jun 26 13:28:23 CEST 2013
http://hg.python.org/peps/rev/16d51a112841
changeset: 4963:16d51a112841
user: Nick Coghlan <ncoghlan at gmail.com>
date: Wed Jun 26 21:27:57 2013 +1000
summary:
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
files:
pep-0426.txt | 33 ++++----
pep-0440.txt | 141 +++++++++++++++++++++-----------------
2 files changed, 95 insertions(+), 79 deletions(-)
diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -636,7 +636,7 @@
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 @@
``'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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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
--- a/pep-0440.txt
+++ b/pep-0440.txt
@@ -550,7 +550,6 @@
* ``~=``: `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 @@
!= 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 @@
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,14 +835,15 @@
* 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 "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 "direct reference" clause
-
* Added the trailing wildcard syntax for prefix based version matching
and exclusion
@@ -1032,14 +1038,23 @@
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
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list