Abstract

Note: This PEP has been superseded by the version identification and dependency specification scheme defined inPEP 440.

This PEP proposed a new version comparison schema system in Distutils.

Motivation

In Python there are no real restrictions yet on how a project should manage its versions, and how they should be incremented.

Distutils provides aversiondistribution meta-data field but it is freeform and current users, such as PyPI usually consider the latest version pushed as the latestone, regardless of the expected semantics.

Distutils will soon extend its capabilities to allow distributions to express a dependency on other distributions through theRequires-Distmetadata field (seePEP 345) and it will optionally allow use of that field to restrict the dependency to a set of compatible versions. Notice that this field is replacingRequiresthat was expressing dependencies on modules and packages.

TheRequires-Distfield will allow a distribution 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 requireszope.interfacewith a version greater than3.5.0.

This also means that Python projects will need to follow the same convention as the tool that will be used to install them, so they are able to compare versions.

That is why this PEP proposes, for the sake of interoperability, a standard schema to express version information and its comparison semantics.

Furthermore, this will make OS packagers’ work easier when repackaging standards compliant distributions, because as of now it can be difficult to decide how two distribution versions compare.

Requisites and current status

It is not in the scope of this PEP to provide a universal versioning schema intended to support all or even most of existing versioning schemas. There will always be competing grammars, either mandated by distro or project policies or by historical reasons that we cannot expect to change.

The proposed schema should be able to express the usual versioning semantics, so it’s possible to parse any alternative versioning schema and transform it into a compliant one. This is how OS packagers usually deal with the existing version schemas and is a preferable alternative than supporting an arbitrary set of versioning schemas.

Conformance to usual practice and conventions, as well as a simplicity are a plus, to ease frictionless adoption and painless transition. Practicality beats purity, sometimes.

Projects have very different versioning needs, but the following are widely considered important semantics:

1. it should be possible to express more than one versioning level (usually this is expressed as major and minor revision and, sometimes, also a micro revision).
2. a significant number of projects need special meaning versions for “pre-releases” (such as “Alpha”, “beta”, “rc” ), and these have widely used aliases ( “a” stands for “Alpha”, “b” for “beta” and “c” for “rc” ). And these pre-release versions make it impossible to use a simple Alpha numerical ordering of the version string components. (Example: 3.1a1 < 3.1)
3. some projects also need “post-releases” of regular versions, mainly for installer work which can’t be clearly expressed otherwise.
4. development versions allow packagers of unreleased work to avoid version clash with later regular releases.

For people that want to go further and use a tool to manage their version numbers, the two major ones are:

• The current Distutils system[1]
• Setuptools[2]

Versionnumberingforanarchistsandsoftwarerealists.
Implementsthestandardinterfaceforversionnumberclassesas
describedabove.Aversionnumberconsistsofaseriesofnumbers,
separatedbyeitherperiodsorstringsofletters.Whencomparing
versionnumbers,thenumericcomponentswillbecompared
numerically,andtheAlpha beticcomponentslexically.Thefollowing
areallvalidversionnumbers,innoparticularorder:

1.5.1
1.5.2b2
161
3.10a
8.02
3.4j
1996.07.12
3.2.pl0
3.1.1.6
2g6
11g
0.960923
2.2beta29
1.13++
5.5.kw
2.0b1pl0

Infact,thereisnosuchthingasaninvalidversionnumberunder
thisscheme;therulesforcomparisonaresimpleandpredictable,
butmaynotalwaysgivetheresultsyouwant(forsomedefinition
of"want").

>>>fromdistutils.versionimportLooseVersionasV
>>>v1=V('FunkyVersion')
>>>v2=V('GroovieVersion')
>>>v1>v2
False

Versionnumberingformeticulousretentiveandsoftwareidealists.
Implementsthestandardinterfaceforversionnumberclassesas
describedabove.Aversionnumberconsistsoftwoorthree
dot-separatednumericcomponents,withanoptional"pre-release"tag
ontheend.Thepre-releasetagconsistsoftheletter'a'or'b'
followedbyanumber.Ifthenumericcomponentsoftwoversion
numbersareequal,thenonewithapre-releasetagwillalways
bedeemedearlier(lesser)thanonewithout.

Thefollowingarevalidversionnumbers(shownintheorderthat
wouldbeobtainedbysortingaccordingtothesuppliedcmpfunction):

0.40.4.0(thesetwoareequivalent)
0.4.1
0.5a1
0.5b3
0.5
0.9.6
1.0
1.0.4a3
1.0.4b1
1.0.4

Thefollowingareexamplesofinvalidversionnumbers:

1
2.7.2.2
1.3.a4
1.3pl1
1.3c4

>>>fromdistutils.versionimportStrictVersionasV
>>>v2=V('GroovieVersion')
Traceback (most recent call last):
...
ValueError:invalid version number 'GroovieVersion'
>>>v2=V('1.1')
>>>v3=V('1.3')
>>>v2<v3
True

Convertaversionstringtoachronologically-sortablekey

ThisisaroughcrossbetweenDistutils' StrictVersion and LooseVersion;
ifyougiveitversionsthatwouldworkwithStrictVersion,thenitbehaves
thesame;otherwiseitactslikeaslightly-smarterLooseVersion.Itis
*possible*tocreatepathologicalversioncodingschemesthatwillfool
thisparser,buttheyshouldbeveryrareinpractice.

Thereturnedvaluewillbeatupleofstrings.Numericportionsofthe
versionarepaddedto8digitssotheywillcomparenumerically,but
withoutrelyingonhownumberscomparerelativetostrings.Dotsare
dropped,butdashesareretained.TrailingzerosbetweenAlphasegments
ordashesaresuppressed,sothate.g."2.4.0"isconsideredthesameas
"2.4".Alphanumericpartsarelower-cased.

Thealgorithmassumesthatstringslike"-"andanyAlphastringthat
Alpha beticallyfollows"final"representsa"patch level".So,"2.4-1"
isassumedtobeabranchorpatchof"2.4",andtherefore"2.4.1"is
considerednewerthan"2.4-1",whichinturnisnewerthan"2.4".

Stringslike"a","b","c","Alpha","beta","candidate"andsoon(that
comebefore"final"Alpha betically)areassumedtobepre-releaseversions,
sothattheversion"2.4"isconsiderednewerthan"2.4a1".

Finally,tohandlemiscellaneouscases,thestrings"pre","preview",and
"rc"aretreatedasiftheywere"c",i.e.asthoughtheywererelease
candidates,andthereforearenotasnewasaversionstringthatdoesnot
containthem,and"dev"isreplacedwithan'@'sothatitsortslower
thananyotherpre-releasetag.

>>>frompkg_resourcesimportparse_versionasV
>>>V('1.2')
('00000001', '00000002', '*final')
>>>V('1.2b2')
('00000001', '00000002', '*b', '00000002', '*final')
>>>V('FunkyVersion')
('*funkyversion', '*final')

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 calledverliband a prototype lives at[10].

The pseudo-format supported is:

N.N[.N]+[{a|b|c|rc}N[.N]+][.postN][.devN]

The real regular expression is:

expr=r"""^
(?P<version>\d+\.\d+) # minimum 'N.N'
(?P<extraversion>(?:\.\d+)*) # any number of extra '.N' segments
(?:
(?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+))?)?
$ "" "

Some examples probably make it clearer:

>>>fromverlibimportNormalizedVersionasV
>>>(V('1.0a1')
...<V('1.0a2.dev456')
...<V('1.0a2')
...<V('1.0a2.1.dev456')
...<V('1.0a2.1')
...<V('1.0b1.dev456')
...<V('1.0b2')
...<V('1.0b2.post345')
...<V('1.0c1.dev456')
...<V('1.0c1')
...<V('1.0.dev456')
...<V('1.0')
...<V('1.0.post456.dev34')
...<V('1.0.post456'))
True

The trailing.dev123is for pre-releases. The.post123is for post-releases – which apparently are used by a number of projects out there (e.g. Twisted[8]). For example,aftera1.2.0release there might be a1.2.0-r678release. We usedpostinstead ofrbecause the ris ambiguous as to whether it indicates a pre- or post-release.

.post456.dev34indicates a dev marker for a post release, that sorts before a.post456marker. This can be used to do development versions of post releases.

Pre-releases can useafor “Alpha”,bfor “beta” andcfor “release candidate”.rcis an alternative notation for “release candidate” that is added to make the version scheme compatible with Python’s own version scheme.rcsorts afterc:

>>>fromverlibimportNormalizedVersionasV
>>>(V('1.0a1')
...<V('1.0a2')
...<V('1.0b3')
...<V('1.0c1')
...<V('1.0rc2')
...<V('1.0'))
True

Note thatcis the preferred marker for third party projects.

verlibprovides aNormalizedVersionclass and a suggest_normalized_versionfunction.

>>>fromverlibimportNormalizedVersion
>>>version=NormalizedVersion('1.0')

>>>str(version)
'1.0'

>>>NormalizedVersion('1.0')>NormalizedVersion('0.9')
True
>>>NormalizedVersion('1.0')<NormalizedVersion('1.1')
True

>>>version=NormalizedVersion.from_parts((1,0))
>>>str(version)
'1.0'

>>>version=NormalizedVersion.from_parts((1,0),('c',4))
>>>str(version)
'1.0c4'

>>>version=NormalizedVersion.from_parts((1,0),('c',4),('dev',34))
>>>str(version)
'1.0c4.dev34'

>>>fromverlibimportsuggest_normalized_version,NormalizedVersion
>>>importwarnings
>>>defvalidate_version(version):
...rversion=suggest_normalized_version(version)
...ifrversionisNone:
...raiseValueError('Cannot work with "%s"'%version)
...ifrversion!=version:
...warnings.warn(' "%s"is not a normalized version.\n'
...'It has been transformed into "%s"'
...'for interoperability.'%(version,rversion))
...returnNormalizedVersion(rversion)
...

>>>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')

>>>validate_version('2.4c1')
NormalizedVersion('2.4c1')

>>>validate_version('foo')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "<stdin>", line 4, in validate_version
ValueError:Cannot work with "foo"

Roadmap

Distutils will deprecate its existing versions class in favor of NormalizedVersion.Theverlibmodule presented in this PEP will be renamed toversionand placed into thedistutilspackage.

References

Acknowledgments

Trent Mick, Matthias Klose, Phillip Eby, David Lyon, and many people at Pycon and Distutils-SIG.

Copyright

This document has been placed in the public domain.