From 68eca6931f4750c62d57e170d2a4d1bf4a0eeb5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Wed, 30 Dec 2009 09:02:01 +0000 Subject: [PATCH] changed the range mechanism, after recent discussions in various MLs --- pep-0345.txt | 61 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 21 deletions(-) diff --git a/pep-0345.txt b/pep-0345.txt index cb26e4129..422d06f5b 100644 --- a/pep-0345.txt +++ b/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