version

Version expressions

Version expressions are strings representing a software version. They are defined by this EBNF grammar:

version_expression ::=  main | main '-' prerelease | main '+' build_metadata | main '-' prerelease '+' build_metadata
main               ::=  major ('.' minor ('.' patch)?)?
major              ::=  number
minor              ::=  number
patch              ::=  number
prerelease         ::=  string | number
build_metadata     ::=  string
number             ::=  [0-9]+
string             ::=  [0-9a-zA-Z.-]+

They can be parsed into Version objects using the Version.parse() class method.

Omitted parts in an expression use these defaults:

Part Default value
minor 0
patch 0
prerelease None
build_metadata None

Examples of valid version expressions:

>>> from versions import Version
>>> v = Version.parse('1')
>>> v == '1.0'
True
>>> v == '1.0.0'
True
>>> v.major, v.minor, v.patch, v.prerelease, v.build_metadata
(1, 0, 0, None, None)

>>> v = Version.parse('1.2.3-dev+foo')
>>> v.major, v.minor, v.patch, v.prerelease, v.build_metadata
(1, 2, 3, 'dev', 'foo')

When parsing fails, an InvalidVersionExpression exception is raised:

>>> Version.parse('#@!')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "versions/version.py", line 119, in parse
    raise InvalidVersionExpression(version_string)
versions.version.InvalidVersionExpression: Invalid version expression: '#@!'

Version

class versions.version.Version(major, minor=0, patch=0, prerelease=None, build_metadata=None)[source]

A package version.

Parameters:
  • major (int) – Version major number
  • minor (int) – Version minor number
  • patch (int) – Version patch number
  • prerelease (str, int or None) – Version prerelease
  • build_metadata (None or str) – Version build metadata

This class constructor is usually not called directly. For version string parsing, see Version.parse.

major = None

Version major number

minor = None

Version minor number

prerelease = None

Version prerelease

build_metadata = None

Version build metadata

classmethod parse(version_string)[source]

Parses a version_string and returns a Version object.

Comparison

Version objects are comparable with standard operators:

>>> from versions import Version
>>> v1 = Version(1)
>>> v2 = Version(2)
>>> v1 == v2
False
>>> v1 != v2
True
>>> v1 > v2
False
>>> v1 < v2
True
>>> v1 >= v2
False
>>> v1 <= v2
True

Hint

When comparing 2 versions, only the version and the pre-release are used. The build metadata are ignored.

Errors

exception versions.version.InvalidVersionExpression(version_expression)[source]

Raised when failing to parse a version expression.

version_expression = None

The bogus version expression.

Table Of Contents

Previous topic

API

Next topic

constraint