diff --git a/pep-0386.txt b/pep-0386.txt index 50aa9ef0b..7ccca10a6 100644 --- a/pep-0386.txt +++ b/pep-0386.txt @@ -12,7 +12,7 @@ Created: 4-June-2009 Abstract ======== -This PEP proposes the inclusion of a new version comparison system in +This PEP proposes the inclusion of a new version comparison system in Distutils. @@ -25,7 +25,7 @@ other changes. This field will be called ``Requires-Dist``. These changes are located in PEP 345 [#pep345]_. -The ``Requires-Dist`` field will allow a package to define a dependency on +The ``Requires-Dist`` field will allow a package to define a dependency on another package and optionally restrict this dependency to a set of compatible versions, so one may write:: @@ -34,6 +34,10 @@ compatible versions, so one may write:: This means that the distribution requires ``zope.interface``, as long as its version is superior to ``3.5.0``. +This also means that Python projects will need to follow the same convention +than the tool that will be used to install them, so they are able to compare +versions. + That's why Distutils needs to provide a robust standard and reference version scheme, and an API to provide version comparisons. @@ -48,7 +52,7 @@ Current status In Python there are no real restriction yet on how a project should manage its versions, and how they should be incremented. They are no standard -either, even if they are a few conventions widely used, like having a major +either, even if they are a few conventions widely used, like having a major and a minor revision (1.1, 1.2, etc.). Developers are free to put in the `version` meta-data of their package any @@ -62,7 +66,7 @@ The problem with this freedom is that the package will be harder to re-package for OS packagers, that need to have stricter conventions. The worst case is when a packager is unable to easily compare the versions he needs to package. -For people that want to go further and use a tool to manage their version +For people that want to go further and use a tool to manage their version numbers, the two major ones are: - The current Distutils system [#distutils]_ @@ -71,7 +75,7 @@ numbers, the two major ones are: Distutils --------- -Distutils currently provides a `StrictVersion` and a `LooseVersion` class +Distutils currently provides a `StrictVersion` and a `LooseVersion` class that can be used to manage versions. The `LooseVersion` class is quite lax. From Distutils doc:: @@ -280,7 +284,7 @@ Some examples probably make it clearer:: The trailing ``.dev123`` is for pre-releases. The ``.post123`` is for post-releases -- which apparently is used by a number of projects out there (e.g. Twisted [#twisted]_). For example *after* a ``1.2.0`` release there might -be a ``1.2.0-r678`` release. We used ``post`` instead of ``r`` because the +be a ``1.2.0-r678`` release. We used ``post`` instead of ``r`` because the ``r`` is ambiguous as to whether it indicates a pre- or post-release. Last, ``.post456.dev34`` indicates a dev marker for a post release, that sorts @@ -344,10 +348,10 @@ rational (i.e. ``RationalVersion`` doesn't like it) then you might be able to get an equivalent (or close) rational version from this function. This does a number of simple normalizations to the given string, based -on observation of versions currently in use on PyPI. Given a dump of those +on observation of versions currently in use on PyPI. Given a dump of those version during PyCon 2009, 4287 of them: -- 2312 (53.93%) match RationalVersion without change with the automatic +- 2312 (53.93%) match RationalVersion without change with the automatic suggestion - 3474 (81.04%) match when using this suggestion method @@ -391,7 +395,7 @@ References Acknowledgments =============== -Trent Mick, Matthias Klose, Phillip Eby, and many people at Pycon and +Trent Mick, Matthias Klose, Phillip Eby, and many people at Pycon and Distutils-SIG. Copyright