diff --git a/pep-0386.txt b/pep-0386.txt index 62d7a4075..c33b00ed2 100644 --- a/pep-0386.txt +++ b/pep-0386.txt @@ -292,7 +292,7 @@ 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]+[{a|b|c|rc}N[.N]+][.postN][.devN] The real regular expression is:: @@ -300,7 +300,8 @@ The real regular expression is:: (?P\d+\.\d+) # minimum 'N.N' (?P(?:\.\d+)*) # any number of extra '.N' segments (?: - (?P[abc]) # 'a'=alpha, 'b'=beta, 'c'=release candidate + (?P[abc]|rc) # 'a' = alpha, 'b' = beta + # 'c' or 'rc' = release candidate (?P\d+(?:\.\d+)*) )? (?P(\.post(?P\d+))?(\.dev(?P\d+))?)? @@ -331,10 +332,24 @@ post-releases -- which apparently are used by a number of projects out there 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 @@ normalized (i.e. ``NormalizedVersion`` doesn't like it) then you might be able 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. -- 2312 (53.93%) match NormalizedVersion without change with the automatic - suggestion -- 3474 (81.04%) match when using this suggestion method +Given a dump of those version on January 6th 2010, the function has given those +results out of the 8821 distributions PyPI had: + +- 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 @@ Here's an example of usage :: ... 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')