From da48d4a64190adbf2272d0f7403cf7e39b1a5abe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= <ziade.tarek@gmail.com>
Date: Tue, 24 Nov 2009 09:46:06 +0000
Subject: [PATCH] added a usage example of suggest_rational_version

---
 pep-0386.txt | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/pep-0386.txt b/pep-0386.txt
index 7ccca10a6..d3fdd7a2e 100644
--- a/pep-0386.txt
+++ b/pep-0386.txt
@@ -355,6 +355,37 @@ version during PyCon 2009, 4287 of them:
   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
 ==========