[Python-checkins] peps: PEP 440 updates based on user feedback

Sat Jan 3 03:31:39 CET 2015

https://hg.python.org/peps/rev/289dbffc16ed
changeset: 5656:289dbffc16ed
user: Nick Coghlan <ncoghlan at gmail.com>
date: Sat Jan 03 12:28:31 2015 +1000
summary:
 PEP 440 updates based on user feedback
files:
 pep-0440.txt | 95 ++++++++++++++++++++++++++-------------
 1 files changed, 64 insertions(+), 31 deletions(-)

diff --git a/pep-0440.txt b/pep-0440.txt
--- a/pep-0440.txt
+++ b/pep-0440.txt
@@ -31,7 +31,7 @@
 ========================================
 
 The version representation and comparison scheme described in this PEP is
-currently accepted on a provisional basis, as described in PEP 411.
+currently accepted on a provisional basis [9]_, as described in PEP 411.
 
 This status is based on feedback received on the initial releases of pip 6.0,
 and setuptools 8.0, which revealed some issues in the specification that
@@ -820,8 +820,7 @@
 Compatible release
 ------------------
 
-A compatible release clause consists of either a version identifier without
-any comparison operator or else the compatible release operator ``~=``
+A compatible release clause consists of the compatible release operator ``~=``
 and a version identifier. It matches any candidate version that is expected
 to be compatible with the specified version.
 
@@ -839,11 +838,9 @@
 
 For example, the following groups of version clauses are equivalent::
 
- 2.2
 ~= 2.2
 >= 2.2, == 2.*
 
- 1.4.5
 ~= 1.4.5
 >= 1.4.5, == 1.4.*
 
@@ -851,11 +848,9 @@
 compatible release clause as ``V.N.suffix``, then the suffix is ignored
 when determining the required prefix match::
 
- 2.2.post3
 ~= 2.2.post3
 >= 2.2.post3, == 2.*
 
- 1.4.5a4
 ~= 1.4.5a4
 >= 1.4.5a4, == 1.4.*
 
@@ -863,11 +858,9 @@
 degree of forward compatibility in a compatible release clause can be
 controlled by appending additional zeros to the version specifier::
 
- 2.2.0
 ~= 2.2.0
 >= 2.2.0, == 2.2.*
 
- 1.4.5.0
 ~= 1.4.5.0
 >= 1.4.5.0, == 1.4.5.*
 
@@ -989,20 +982,29 @@
 Exclusive ordered comparison
 ----------------------------
 
-Exclusive ordered comparisons are similar to inclusive ordered comparisons,
-except that the comparison operators are ``<`` and ``>`` and the clause
-MUST be effectively interpreted as implying the prefix based version
-exclusion clause ``!= V.*``.
+The exclusive ordered comparisons ``>`` and ``<`` are similar to the inclusive
+ordered comparisons in that they rely on the relative position of the candidate
+version and the specified version given the consistent ordering defined by the
+standard `Version scheme`_. However, they specifically exclude pre-releases,
+post-releases, and local versions of the specified version.
 
-The exclusive ordered comparison ``> V`` MUST NOT match a post-release
-or maintenance release of the given version. Maintenance releases can be
-permitted by using the clause ``> V.0``, while both post releases and
-maintenance releases can be permitted by using the inclusive ordered
-comparison ``>= V.post1``.
+The exclusive ordered comparison ``>V`` **MUST NOT** allow a post-release
+of the given version unless ``V`` itself is a post release. You may mandate
+that releases are later than a particular post release, including additional
+post releases, by using ``>V.postN``. For example, ``>1.7`` will allow
+``1.7.1`` but not ``1.7.0.post1`` and ``>1.7.post2`` will allow ``1.7.1``
+and ``1.7.0.post3`` but not ``1.7.0``.
 
-The exclusive ordered comparison ``< V`` MUST NOT match a pre-release of
-the given version, even if acceptance of pre-releases is enabled as
-described in the section below.
+The exclusive ordered comparison ``>V`` **MUST NOT** match a local version of
+the specified version.
+
+The exclusive ordered comparison ``<V`` **MUST NOT** allow a pre-release of
+the specified version unless the specified version is itself a pre-release.
+Allowing pre-releases that are earlier than, but not equal to a specific
+pre-release may be accomplished by using ``<V.rc1`` or similar.
+
+As with version matching, the release segment is zero padded as necessary to
+ensure the release segments are compared with the same length.
 
 Local version identifiers are NOT permitted in this version specifier.
 
@@ -1067,14 +1069,14 @@
 Examples
 --------
 
-* ``3.1``: version 3.1 or later, but not version 4.0 or later.
-* ``3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later.
-* ``3.1a1``: version 3.1a1 or later, but not version 4.0 or later.
+* ``~=3.1``: version 3.1 or later, but not version 4.0 or later.
+* ``~=3.1.2``: version 3.1.2 or later, but not version 3.2.0 or later.
+* ``~=3.1a1``: version 3.1a1 or later, but not version 4.0 or later.
 * ``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases,
 post releases, developmental releases and any 3.1.x maintenance releases.
 * ``== 3.1.*``: any version that starts with 3.1. Equivalent to the
- ``3.1.0`` compatible release clause.
-* ``3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and
+ ``~=3.1.0`` compatible release clause.
+* ``~=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.
 
 
@@ -1182,8 +1184,9 @@
 The versioning specification may be updated with clarifications without
 requiring a new PEP or a change to the metadata version.
 
-Actually changing the version comparison semantics still requires a new
-versioning scheme and metadata version defined in new PEPs.
+Once the Provisional caveat is removed from the specification, any further
+changes to the version comparison semantics will require an updated
+versioning scheme defined in a new PEP.
 
 
 Summary of differences from pkg_resources.parse_version
@@ -1353,9 +1356,7 @@
 improved tools for dynamic path manipulation.
 
 The trailing wildcard syntax to request prefix based version matching was
-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.
+added to make it possible to sensibly define compatible release clauses.
 
 
 Support for date based version identifiers
@@ -1504,6 +1505,27 @@
 gets normalized to a ``_`` to enable easier parsing of the filename.
 
 
+Summary of changes to \PEP 440
+==============================
+
+The following changes were made to this PEP based on feedback received after
+the initial reference implementation was released in setuptools 8.0 and pip
+6.0:
+
+* The exclusive ordered comparisons were updated to no longer imply a ``!=V.*``
+ which was deemed to be surprising behavior which was too hard to accurately
+ describe. Instead the exclusive ordered comparisons will simply disallow
+ matching pre-releases, post-releases, and local versions of the specified
+ version (unless the specified version is itself a pre-release, post-release
+ or local version). For an extended discussion see the threads on
+ distutils-sig [6]_ [7]_.
+
+* The normalized form for release candidates was updated from 'c' to 'rc'.
+ This change was based on user feedback received when setuptools 8.0
+ started applying normalisation to the release metadata generated when
+ preparing packages for publication on PyPI [8]_.
+
+
 References
 ==========
 
@@ -1525,6 +1547,17 @@
 .. [5] Proof of Concept: PEP 440 within pip
 https://github.com/pypa/pip/pull/1894
 
+.. [6] PEP440: foo-X.Y.Z does not satisfy "foo>X.Y"
+ https://mail.python.org/pipermail/distutils-sig/2014-December/025451.html
+
+.. [7] PEP440: >1.7 vs >=1.7
+ https://mail.python.org/pipermail/distutils-sig/2014-December/025507.html
+
+.. [8] Amend PEP 440 with Wider Feedback on Release Candidates
+ https://mail.python.org/pipermail/distutils-sig/2014-December/025409.html
+
+.. [9] Changing the status of PEP 440 to Provisional
+ https://mail.python.org/pipermail/distutils-sig/2014-December/025412.html
 
 Appendix A
 ==========
-- 
Repository URL: https://hg.python.org/peps
