[Python-checkins] r77318 - peps/trunk/pep-0386.txt

[tarek.ziade]

Author: tarek.ziade
Date: Wed Jan  6 00:54:56 2010
New Revision: 77318

Log:
introduced rc so Python's own scheme works. Also added recent PyPI stats

Modified:
   peps/trunk/pep-0386.txt

Modified: peps/trunk/pep-0386.txt
==============================================================================
--- peps/trunk/pep-0386.txt	(original)
+++ peps/trunk/pep-0386.txt	Wed Jan  6 00:54:56 2010
@@ -292,7 +292,7 @@
 
 The pseudo-format supported is::
 
-    N.N[.N]+[{abc}N[.N]+][.postN][.devN]
+    N.N[.N]+[{a|b|c|rc}N[.N]+][.postN][.devN]
 
 The real regular expression is::
 
@@ -300,7 +300,8 @@
     (?P<version>\d+\.\d+)         # minimum 'N.N'
     (?P<extraversion>(?:\.\d+)*)  # any number of extra '.N' segments
     (?:
-        (?P<prerel>[abc])         # 'a'=alpha, 'b'=beta, 'c'=release candidate
+        (?P<prerel>[abc]|rc)         # 'a' = alpha, 'b' = beta
+                                     # 'c' or 'rc' = release candidate
         (?P<prerelversion>\d+(?:\.\d+)*)
     )?
     (?P<postdev>(\.post(?P<post>\d+))?(\.dev(?P<dev>\d+))?)?
@@ -331,10 +332,24 @@
 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
+``.post456.dev34`` indicates a dev marker for a post release, that sorts
 before a ``.post456`` marker. This can be used to do development versions
 of post releases.
 
+Pre-releases can use ``a`` for "alpha", ``b`` for "beta" and ``c`` for
+"release candidate". ``rc`` is an alternative notation for "release candidate"
+that is added to make the version scheme compatible with Python's own version
+scheme. ``rc`` sorts after ``c``::
+
+    >>> from verlib import NormalizedVersion as V
+    >>> (V('1.0a1')
+    ...  < V('1.0a2')
+    ...  < V('1.0b3')
+    ...  < V('1.0c1')
+    ...  < V('1.0rc2')
+    ...  < V('1.0')
+    True
+
 ``verlib`` provides a ``NormalizedVersion`` class and a
 ``suggest_normalized_version`` function.
 
@@ -387,12 +402,25 @@
 to get an equivalent (or close) normalized 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:
+on observation of versions currently in use on PyPI.
+
+Given a dump of those version on January 6th 2010, the function has given those
+results out of the 8821 distributions PyPI had:
 
-- 2312 (53.93%) match NormalizedVersion without change with the automatic
-  suggestion
-- 3474 (81.04%) match when using this suggestion method
+- 7822 (88.67%) already match ``NormalizedVersion`` without any change
+- 717 (8.13%) match when using this suggestion method
+- 282 (3.20%) don't match at all.
+
+The 3.20% of projects that are incompatible with ``NormalizedVersion``
+and cannot be transformed into a compatible form, are for most of them date-based
+version schemes, versions with custom markers, or dummy versions. Examples:
+
+- working proof of concept
+- 1 (first draft)
+- unreleased.unofficialdev
+- 0.1.alphadev
+- 2008-03-29_r219
+- etc.
 
 When a tool needs to work with versions, a strategy is to use
 ``suggest_normalized_version`` on the versions string. If this function returns
@@ -416,8 +444,8 @@
     ...     return NormalizedVersion(rversion)
     ...
 
-    >>> validate_version('2.4rc1')
-    __main__:8: UserWarning: "2.4rc1" is not a normalized version.
+    >>> validate_version('2.4-rc1')
+    __main__:8: UserWarning: "2.4-rc1" is not a normalized version.
     It has been transformed into "2.4c1" for interoperability.
     NormalizedVersion('2.4c1')