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

pep-0426.txt

@@ -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
 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 @@ controlled on a per-distribution basis.
 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: