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

PEP 426: replace implied 'version starts with' with new ~= operator

This commit is contained in:
Daniel Holth 2013-02-22 22:33:09 -05:00
parent ee852b4573
commit eacfe8b2ed
1 changed files with 22 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
pep-0426.txt
View File

@ -987,40 +987,41 @@ A version specifier consists of a series of version clauses, separated by
commas. Each version clause consists of an optional comparison operator commas. Each version clause consists of an optional comparison operator
followed by a version identifier. For example:: 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 Each version identifier must be in the standard format described in
`Version scheme`_. `Version scheme`_.
The comma (",") is equivalent to a logical **and** operator. The comma (",") is equivalent to a logical **and** operator.
Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==`` Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``,
or ``!=``. ``!=`` or ``~=``.
The ``==`` and ``!=`` operators are strict - in order to match, the The ``==`` and ``!=`` operators are strict - in order to match, the
version supplied must exactly match the specified version, with no 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 The special ``~=`` operator is equivalent to using the following pair
identifier ``V``, it is equivalent to using the following pair of version of version clauses::
clauses::
>= V, < V+1 >= V, < V+1
where ``V+1`` is the next version after ``V``, as determined by where ``V+1`` is the next version after ``V``, as determined by
incrementing the last numeric component in ``V`` (for example, if incrementing the last numeric component in ``V`` (for example, if ``V ==
``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then ``V+1 ==
``V+1 == 1.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 This approach makes it easy to depend on a particular release series
simply by naming it in a version specifier, without requiring any simply by naming it in a version specifier, without requiring any
additional annotation. For example, the following pairs of version additional annotation. For example, the following pairs of version
specifiers are equivalent:: specifiers are equivalent::
2 ~= 2
>= 2, < 3 >= 2, < 3
3.3 ~= 3.3
>= 3.3, < 3.4 >= 3.3, < 3.4
Whitespace between a conditional operator and the following version Whitespace between a conditional operator and the following version
@ -1053,32 +1054,29 @@ controlled on a per-distribution basis.
Post-releases and purely numeric releases receive no special treatment - Post-releases and purely numeric releases receive no special treatment -
they are always included unless explicitly excluded. they are always included unless explicitly excluded.
Given the above rules, projects which include the ``.0`` suffix for the Given the above rules, projects which include the ``.0`` suffix for
first release in a series, such as ``2.5.0``, can easily refer specifically the first release in a series, such as ``2.5.0``, can easily refer
to that version with the clause ``2.5.0``, while the clause ``2.5`` refers specifically to that version with the clause ``==2.5.0``, while the clause
to that entire series. Projects which omit the ".0" suffix for the first ``~=2.5`` refers to that entire series.
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.
Some examples: 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. excluding pre-releases.
* ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist: * ``Requires-Dist: zope.interface (==3.1)``: equivalent to ``Requires-Dist:
zope.interface (3.1)``. 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 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". 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: 3``: Any Python 3 version, excluding pre-releases.
* ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including * ``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 post-releases (if they were used for Python). It excludes pre releases of
Python 3. 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 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. include all versions of the 2.6.2 series, excluding pre-releases.
* ``Requires-Python: 2.5``: Equivalent to ">=2.5,<2.6". * ``Requires-Python: ~=2.5``: Equivalent to ">=2.5,<2.6".
* ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts * ``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 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 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: of the 3.1 series but not 3.1.3". This is equivalent to: