[Python-checkins] peps: PEP 426: replace implied 'version starts with' with new ~= operator
daniel.holth
python-checkins at python.org
Sat Feb 23 04:33:21 CET 2013
http://hg.python.org/peps/rev/de69fe61f300
changeset: 4764:de69fe61f300
user: Daniel Holth <dholth at fastmail.fm>
date: Fri Feb 22 22:33:09 2013 -0500
summary:
PEP 426: replace implied 'version starts with' with new ~= operator
files:
pep-0426.txt | 46 +++++++++++++++++++--------------------
1 files changed, 22 insertions(+), 24 deletions(-)
diff --git a/pep-0426.txt b/pep-0426.txt
--- a/pep-0426.txt
+++ b/pep-0426.txt
@@ -987,40 +987,41 @@
commas. Each version clause consists of an optional comparison operator
followed by a version identifier. For example::
- 0.9, >= 1.0, != 1.3.4, < 2.0
+ 0.9, >= 1.0, != 1.3.4, < 2.0, ~= 2.0
Each version identifier must be in the standard format described in
`Version scheme`_.
The comma (",") is equivalent to a logical **and** operator.
-Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
-or ``!=``.
+Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``,
+``!=`` or ``~=``.
The ``==`` and ``!=`` operators are strict - in order to match, the
version supplied must exactly match the specified version, with no
-additional trailing suffix.
+additional trailing suffix. When no comparison operator is provided,
+it is equivalent to ``==``.
-However, when no comparison operator is provided along with a version
-identifier ``V``, it is equivalent to using the following pair of version
-clauses::
+The special ``~=`` operator is equivalent to using the following pair
+of version clauses::
>= V, < V+1
where ``V+1`` is the next version after ``V``, as determined by
-incrementing the last numeric component in ``V`` (for example, if
-``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then
-``V+1 == 1.1``).
+incrementing the last numeric component in ``V`` (for example, if ``V ==
+1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then ``V+1 ==
+1.1``). In other words, this operator matches any release that starts
+with the mentioned components.
This approach makes it easy to depend on a particular release series
simply by naming it in a version specifier, without requiring any
additional annotation. For example, the following pairs of version
specifiers are equivalent::
- 2
+ ~= 2
>= 2, < 3
- 3.3
+ ~= 3.3
>= 3.3, < 3.4
Whitespace between a conditional operator and the following version
@@ -1053,32 +1054,29 @@
Post-releases and purely numeric releases receive no special treatment -
they are always included unless explicitly excluded.
-Given the above rules, projects which include the ``.0`` suffix for the
-first release in a series, such as ``2.5.0``, can easily refer specifically
-to that version with the clause ``2.5.0``, while the clause ``2.5`` refers
-to that entire series. Projects which omit the ".0" suffix for the first
-release of a series, by using a version string like ``2.5`` rather than
-``2.5.0``, will need to use an explicit clause like ``>= 2.5, < 2.5.1`` to
-refer specifically to that initial release.
+Given the above rules, projects which include the ``.0`` suffix for
+the first release in a series, such as ``2.5.0``, can easily refer
+specifically to that version with the clause ``==2.5.0``, while the clause
+``~=2.5`` refers to that entire series.
Some examples:
-* ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
+* ``Requires-Dist: zope.interface (~=3.1)``: any version that starts with 3.1,
excluding pre-releases.
* ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
zope.interface (3.1)``.
-* ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
+* ``Requires-Dist: zope.interface (~=3.1.0)``: any version that starts with
3.1.0, excluding pre-releases. Since that particular project doesn't
use more than 3 digits, it also means "only the 3.1.0 release".
* ``Requires-Python: 3``: Any Python 3 version, excluding pre-releases.
* ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
post-releases (if they were used for Python). It excludes pre releases of
Python 3.
-* ``Requires-Python: 2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes
+* ``Requires-Python: ~=2.6.2``: Equivalent to ">=2.6.2,<2.6.3". So this includes
only Python 2.6.2. Of course, if Python was numbered with 4 digits, it would
include all versions of the 2.6.2 series, excluding pre-releases.
-* ``Requires-Python: 2.5``: Equivalent to ">=2.5,<2.6".
-* ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts
+* ``Requires-Python: ~=2.5``: Equivalent to ">=2.5,<2.6".
+* ``Requires-Dist: zope.interface (~=3.1,!=3.1.3)``: any version that starts
with 3.1, excluding pre-releases of 3.1 *and* excluding any version that
starts with "3.1.3". For this particular project, this means: "any version
of the 3.1 series but not 3.1.3". This is equivalent to:
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list