changed the range mechanism, after recent discussions in various MLs

pep-0345.txt

@@ -296,7 +296,7 @@ Examples::
 Provides-Dist (multiple use)
 ::::::::::::::::::::::::::::
 
-Each entry contains a string naming a distutlis project which
+Each entry contains a string naming a Distutils project which
 is contained within this distribution.  This field *must* include
 the project identified in the ``Name`` field.
 
@@ -416,29 +416,48 @@ The comma (",") is equivalent to the **and** operator.
 
 Each version number must be in the format specified in PEP 386.
 
-The range operator ("~=") is a special operator that can be used to
-define a range of versions by describing a MAJOR or a MAJOR.MINOR
-version. All versions that starts with the definition will
-be included in the range.
+When a version is provided, it always includes all versions that
+starts with the same value. For example the "2.5" version of Python
+will include versions like "2.5.2" or "2.5.3". Pre and post releases
+in that case are excluded. So in our example, versions like "2.5a1" are
+not included when "2.5" is used. If the first version of the range is
+required, it has to be explicitly given. In our example, it will be
+"2.5.0".
 
-Examples:
+Notice that some projects might omit the ".0" prefix for the first release
+of the "2.5.x" series:
 
-- ``Requires-Python: ~=2.5`` means all versions of Python 2.5.
-- ``Requires-Python: ~=2`` means all versions of Python 2.
-- ``~=2.5.2`` is equivalent to ``==2.5.2``
+- 2.5
+- 2.5.1
+- 2.5.2
+- etc.
 
-The range operator is limited to the MAJOR and MINOR parts of
-a version string, as specified in PEP 386. Post and pre-releases
-are not included in range operators.
+In that case, "2.5.0" will have to be explicitly used to avoid any confusion
+between the "2.5" notation that represents the full range. It is a recommended
+practice to use schemes of the same length for a series to completely avoid
+this problem.
 
-The ``Requires-External`` field can use the operators described in this
-section but since the version scheme might not be compatible with PEP 386,
-the range operator might not be appliable.
-
-For each field that uses a version, if no operator is provided, the
-range operator is used by default. For example, ``Requires-Python: 2.5``
-is equivalent to ``Requires-Python: ~=2.5``.
+Some Examples:
 
+- ``Requires-Dist: zope.interface (3.1)``: any version that starts with 3.1,
+  excluding post or pre-releases.
+- ``Requires-Dist: zope.interface (3.1.0)``: any version that starts with
+  3.1.0, excluding post or 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, no matter wich one, excluding
+  post or pre-releases.
+- ``Requires-Python: >=2.6,<3``: Any version of Python 2.6 or 2.7, including
+  post releases of 2.6, pre and post releases of 2.7. It excludes pre releases
+  of Python 3.
+- ``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
+  have include all versions of the 2.6.2 series.
+- ``Requires-Python: 2.5.0``: Equivalent to ">=2.5.0,<2.5.1".
+- ``Requires-Dist: zope.interface (3.1,!=3.1.3)``: any version that starts with
+  3.1, excluding post or 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:
+  ">=3.1,!=3.1.3,<3.2".
 
 Environment markers
 ===================
@@ -449,9 +468,9 @@ environment.
 
 Here are some example of fields using such markers::
 
-   Requires-Dist: pywin32 > 1.0; sys.platform == 'win32'
+   Requires-Dist: pywin32 (>1.0); sys.platform == 'win32'
    Obsoletes-Dist: pywin31; sys.platform == 'win32'
-   Requires-Dist: foo; os.machine == 'i386'
+   Requires-Dist: foo (1,!=1.3); os.machine == 'i386'
    Requires-Dist: bar; python_version == '2.4' or python_version == '2.5'
    Requires-External: libxslt; 'linux' in sys.platform