Source

packaging_cpython / Doc / packaging / developer / packaging.version.rst

Full commit

Working with versions

Packaging contains methods to work with version numbers. It's an implementation of version specifiers as defined in PEP 345 about Metadatas.

NormalizedVersion

A Normalized version is a specific version of a distribution, as described in the PEP 345. So, you can work with the NormalizedVersion like this:

>>> NormalizedVersion("1.2b1")
NormalizedVersion('1.2b1')

If you try to use irrational version specifiers, an IrrationalVersionError will be raised:

>>> NormalizedVersion("irrational_version_number")
...
IrrationalVersionError: irrational_version_number

You can compare NormalizedVersion objects, like this:

>>> NormalizedVersion("1.2b1") < NormalizedVersion("1.2")
True

NormalizedVersion is used internally by VersionPredicate to do his stuff.

Suggest a normalized version

Before this version scheme, there was existing others ones. Packaging provides a tool that suggests a normalized version: the suggest_normalized_version function:

>>> suggest_normalized_version('2.1-rc1')
2.1c1

If suggest_normalized_version can't actually suggest you a version, it will return None:

>>> print suggest_normalized_version('not a version')
None

Dealing with version predicates

VersionPredicate knows how to parse stuff like "ProjectName (>=version)", the class also provides a match method to test if a version number is the version predicate:

>>> version = VersionPredicate("ProjectName (<1.2,>1.0)")
>>> version.match("1.2.1")
False
>>> version.match("1.1.1")
True

You could test if a predicate is a valid one, using the is_valid_predicate function:

>>> is_valid_predicate('FooBar (1.1)')
True
>>> is_valid_predicate('FooBar (+1.1)')
False