diff --git a/pep-0440.txt b/pep-0440.txt index f4c4b4ba1..fbbdbfa09 100644 --- a/pep-0440.txt +++ b/pep-0440.txt @@ -31,7 +31,7 @@ Provisional status of this specification ======================================== 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 @@ specifier. 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 @@ This operator MUST NOT be used with a single segment version number such as 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 @@ If a pre-release, post-release or developmental release is named in a 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 @@ The padding rules for release segment comparisons means that the assumed 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 @@ Local version identifiers are NOT permitted in this version specifier. 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 ```` -ordered comparison clauses. +added to make it possible to sensibly define compatible release clauses. Support for date based version identifiers @@ -1504,6 +1505,27 @@ reason for this is that the Wheel normalization scheme specifies that ``-`` 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 @@ justifications for needing such a standard can be found in PEP 386. .. [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 ==========