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

[tarek.ziade]

Author: tarek.ziade
Date: Tue Nov 24 10:46:06 2009
New Revision: 76478

Log:
added a usage example of suggest_rational_version

Modified:
   peps/trunk/pep-0386.txt

Modified: peps/trunk/pep-0386.txt
==============================================================================
--- peps/trunk/pep-0386.txt	(original)
+++ peps/trunk/pep-0386.txt	Tue Nov 24 10:46:06 2009
@@ -355,6 +355,37 @@
   suggestion
 - 3474 (81.04%) match when using this suggestion method
 
+When a tool needs to work with versions, the best strategy is to use
+``suggest_rational_version`` on the versions string. If this function returns
+``None``, it means that the provided version is not close enough to the
+standard scheme::
+
+    >>> from verlib import suggest_rational_version, RationalVersion
+    >>> def validate_version(version):
+    ...     rversion = suggest_rational_version(version)
+    ...     if rversion is None:
+    ...         raise ValueError('Cannot work with %s' % version)
+    ...     return RationalVersion(rversion)
+    ...
+
+    >>> validate_version('2.4rc1')
+    RationalVersion('2.4c1')
+
+    >>> validate_version('foo')
+    Traceback (most recent call last):
+    ...
+    ValueError: Cannot work with foo
+
+    >>> validate_version('1.24.33')
+    RationalVersion('1.24.33c1')
+
+    >>> validate_version('1.24.330pre1')
+    RationalVersion('1.24.330c1')
+
+    >>> validate_version('2008.12.11')
+    Traceback (most recent call last):
+    ...
+    ValueError: Cannot work with 2008.12.11
 
 References
 ==========