From 7fe3d72593837ee96f69a08e80de76b34d1f7917 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 27 Dec 2009 23:50:39 +0000 Subject: [PATCH] added the range operator, and more details on versions --- pep-0345.txt | 89 ++++++++++++++++++++++++++-------------------------- 1 file changed, 44 insertions(+), 45 deletions(-) diff --git a/pep-0345.txt b/pep-0345.txt index 99900951b..0ba1f2a92 100644 --- a/pep-0345.txt +++ b/pep-0345.txt @@ -283,15 +283,8 @@ optionally followed by a version declaration within parentheses. The distutils project names should correspond to names as found on the `Python Package Index`_. -A version declaration is a series of conditional operators and -version numbers, separated by commas. Conditional operators -must be one of "<", ">", "<=", ">=", "==", and "!=". Version -numbers must be in the format specified in `PEP 386`_. -If no operator is provided with a version, the "==" operator -is used by default. - -Any number of conditional operators can be specified, e.g. -the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +Version declarations must follow the rules described in +`Version Specifiers`_ Examples:: @@ -322,10 +315,9 @@ RDBMS bindings for use by a given ORM: each project might declare that it provides ``ORM-bindings``, allowing other projects to depend only on having at most one of them installed. -A version declaration may be supplied (without a comparison -operator); the distribution's version number will be implied if none -is specified. Version numbers must be in the format specified in -`PEP 386`_. +A version declaration may be supplied and must follow the rules described +in `Version Specifiers`_. The distribution's version number will be implied +if none is specified. Examples:: @@ -342,7 +334,7 @@ this package renders obsolete, meaning that the two packages should not be installed at the same time. Version declarations can be supplied. Version numbers must be in the -format specified in `PEP 386`_. +format specified in `Version Specifiers`_. The most common use of this field will be in case a project name changes, e.g. Gorgon 2.3 gets subsumed into Torqued Python 1.0. @@ -359,19 +351,13 @@ Requires-Python ::::::::::::::: This field specifies the Python version(s) that the package is -guaranteed to be compatible with. The format of the field is a -series of conditional operators and version numbers, separated -by commas. Conditional operators must be one of "<", ">", "<=", -">=", "==", and "!=". If no operator is provided with a version, -the "==" operator is used by default. +guaranteed to be compatible with. -Version numbers must be in the format specified in `PEP 386`_. - -Any number of conditional operators can be specified, e.g. -the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. +Version numbers must be in the format specified in `Version Specifiers`_. Examples:: + Requires-Python: 2.5 Requires-Python: >2.1 Requires-Python: >=2.3.4 Requires-Python: 2.5, 2.6 @@ -389,19 +375,13 @@ The format of a requirement string is a name of an external dependency, optionally followed by a version declaration within parentheses. -A version declaration is a series of conditional operators and -version numbers, separated by commas. Conditional operators -must be one of "<", ">", "<=", ">=", "==", and "!=". If no -operator is provided with a version, the "==" operator is used by default. +Version numbers must be in the format specified in `Version Specifiers`_. Because they refer to non-Python software releases, version numbers for this field are **not** required to conform to the format specified in `PEP 386`_: they should correspond to the version scheme used by the external dependency. -Any number of conditional operators can be specified, e.g. -the string ">1.0, !=1.3.4, <2.0" is a legal version declaration. - Notice that there's is no particular rule on the strings to be used. Examples:: @@ -426,8 +406,38 @@ The label is a free text limited to 32 signs. Version Specifiers ================== -The specification for distribution version specifiers has been moved to -`PEP 386`_. +Version specifiers are a series of conditional operators and +version numbers, separated by commas. Conditional operators +must be one of "<", ">", "<=", ">=", "==", "~=" and "!=". + +Any number of conditional operators can be specified, e.g. +the string ``>1.0, !=1.3.4, <2.0`` is a legal version declaration. +The comma (``,``) is equivalent to the **or** 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. + +Examples: + +- ``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`` + +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. + +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``. Environment markers @@ -445,17 +455,6 @@ Here are some example of fields using such markers:: Requires-Dist: bar; python_version == '2.4' or python_version == '2.5' Requires-External: libxslt; 'linux' in sys.platform -These markers are using a micro-language that can be interpreted using a -function ``interpret_marker`` provided in the ``distutils.util`` module -in the stdlib:: - - >>> from distutils.util import interpret_marker - >>> interpret_marker("sys.platform == 'win32'") - True - -Depending if the execution environment meets the requirements, the function -will return True or False. - The micro-language behind this is the simplest possible: it compares only strings, with the ``==`` and ``in`` operators (and their opposites), and with the ability to combine expressions. It makes it also easy to understand @@ -545,8 +544,8 @@ Acknowledgements Fred Drake, Anthony Baxter and Matthias Klose have all contributed to the ideas presented in this PEP. -Tres Seaver, Jim Fulton, Marc-André Lemburg, Tarek Ziadé and other people at -the Distutils-SIG have contributed to the new updated version. +Tres Seaver, Jim Fulton, Marc-André Lemburg, Martin von Löwis, Tarek Ziadé and +other people at the Distutils-SIG have contributed to the new updated version. ..