iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PEP 440 updates based on user feedback

This commit is contained in:
Nick Coghlan 2015-01-03 12:28:31 +10:00
parent f76f34e7f4
commit c4904f1ae8
1 changed files with 64 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

95
pep-0440.txt
View File

@ -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 ``<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 @@ specifiers - they are always included unless explicitly excluded.
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 @@ Updating the versioning specification
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 @@ depend on updates to the installation database definition along with
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 @@ 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
==========