[Python-checkins] r75554 - peps/trunk/pep-0386.txt
tarek.ziade
python-checkins at python.org
Tue Oct 20 10:35:19 CEST 2009
Author: tarek.ziade
Date: Tue Oct 20 10:35:18 2009
New Revision: 75554
Log:
updated with latest feedback + PEP 345 changes
Modified:
peps/trunk/pep-0386.txt
Modified: peps/trunk/pep-0386.txt
==============================================================================
--- peps/trunk/pep-0386.txt (original)
+++ peps/trunk/pep-0386.txt Tue Oct 20 10:35:18 2009
@@ -19,22 +19,29 @@
Motivation
==========
-Distutils will soon extend the metadata standard, by including the
-`install_requires` field from Setuptools [#requires]_ among other changes.
+Distutils will soon extend the metadata standard, by including an
+``install_requires``-like field from Setuptools [#requires]_ among
+other changes. This field will be called ``Requires-Dist``.
-These changes are a work in progress in PEP 345 [#pep345]_, but validating
-the current PEP is mandatory to continue the work.
+These changes are located in PEP 345 [#pep345]_.
-The `install_requires` field will allow a package to define a dependency on
-another package and optionally restrict this dependency to a set of
-compatible versions.
+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::
+
+ Requires-Dist: zope.interface (>3.5.0)
+
+This means that the distribution requires ``zope.interface``, as long as its
+version is superior to ``3.5.0``.
That's why Distutils needs to provide a robust standard and reference
-implementation to compare versions numbers.
+version scheme, and an API to provide version comparisons.
-This will also provide to the community a convention for their package
-versioning needs.
+This PEP describes a new version scheme that will be added in Distutils.
+Of course developers are **not** required to conform to this scheme, but
+it is suggested to use it as a standard for interoperability between the
+existing Python distributions installers.
Current status
==============
@@ -246,12 +253,11 @@
During Pycon, members of the Python, Ubuntu and Fedora community worked on
a version standard that would be acceptable for everyone.
-It's currently called `verlib` and a prototype lives here :
-http://bitbucket.org/tarek/distutilsversion/src/
+It's currently called `verlib` and a prototype lives at [#prototype]_.
The pseudo-format supported is::
- N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
+ N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
Some examples probably make it clearer::
@@ -267,16 +273,19 @@
... < V('1.0c1')
... < V('1.0.dev456')
... < V('1.0')
- ... < V('1.0.post623.dev456')
+ ... < V('1.0.post456.dev34')
... < V('1.0.post456'))
True
-The trailing ".dev123" is for pre-releases. The ".post123" is for
+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 "r" is
-ambiguous as to whether it indicates a pre- or post-release.
-Last ".post623.dev456" is a development version of a post-release.
+(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
+``r`` is ambiguous as to whether it indicates a pre- or post-release.
+
+Last, ``.post456.dev34`` indicates a dev parker for a post release, that sorts
+before a ``.post345`` marker. This can be used to do development versions
+of post releases.
``verlib`` provides a ``RationalVersion`` class and a
``suggest_rational_version`` function.
@@ -310,7 +319,6 @@
- the main version part
- the pre-release part
-- the `postdev` marker part
Examples ::
@@ -326,10 +334,22 @@
>>> str(version)
'1.0c4.dev34'
+
suggest_rational_version
------------------------
-XXX explain here suggest_rational_version
+``suggest_rational_version`` is a function that suggests a rational version
+close to the given version string. If you have a version string that isn't
+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
+version during PyCon 2009, 4287 of them:
+
+- 2312 (53.93%) match RationalVersion without change with the automatic
+ suggestion
+- 3474 (81.04%) match when using this suggestion method
References
@@ -365,8 +385,11 @@
.. [#pep345]
http://svn.python.org/projects/peps/branches/jim-update-345/pep-0345.txt
-Aknowledgments
-==============
+.. [#prototype]
+ http://bitbucket.org/tarek/distutilsversion/
+
+Acknowledgments
+===============
Trent Mick, Matthias Klose, Phillip Eby, and many people at Pycon and
Distutils-SIG.
More information about the Python-checkins
mailing list