From 2b2e353c74a099993ffe4d658175aca6de03f98c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 20 Oct 2009 08:35:18 +0000 Subject: [PATCH] updated with latest feedback + PEP 345 changes --- pep-0386.txt | 69 ++++++++++++++++++++++++++++++++++------------------ 1 file changed, 46 insertions(+), 23 deletions(-) diff --git a/pep-0386.txt b/pep-0386.txt index 23d56337c..67ac04277 100644 --- a/pep-0386.txt +++ b/pep-0386.txt @@ -19,22 +19,29 @@ Distutils. 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 @@ The new versioning algorithm 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 @@ Some examples probably make it clearer:: ... < 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 @@ Each part is a tuple and there are three parts: - the main version part - the pre-release part -- the `postdev` marker part Examples :: @@ -326,10 +334,22 @@ Examples :: >>> 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 @@ References .. [#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.