Using semver¶

The semver module can store a version in different types:

as a string.
as semver.VersionInfo, a dedicated class for a version type.
as a dictionary.

Each type can be converted into the other, if the minimum requirements are met.

Knowing the Implemented semver.org Version¶

The semver.org is the authorative specification of how semantical versioning is definied. To know which version of semver.org is implemented in the semver libary, use the following constant:

>>> semver.SEMVER_SPEC_VERSION
'2.0.0'

Creating a Version¶

A version can be created in different ways:

as a complete version string:

>>> semver.parse_version_info("3.4.5-pre.2+build.4")
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
>>> semver.VersionInfo.parse("3.4.5-pre.2+build.4")
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')

with individual parts:

>>> semver.format_version(3, 4, 5, 'pre.2', 'build.4')
'3.4.5-pre.2+build.4'
>>> semver.VersionInfo(3, 5)
VersionInfo(major=3, minor=5, patch=0, prerelease=None, build=None)

You can pass either an integer or a string for major, minor, or patch:

>>> semver.VersionInfo("3", "5")
VersionInfo(major=3, minor=5, patch=0, prerelease=None, build=None)

In the simplest form, prerelease and build can also be integers:

>>> semver.VersionInfo(1, 2, 3, 4, 5)
VersionInfo(major=1, minor=2, patch=3, prerelease=4, build=5)

If you pass an invalid version string you will get a ValueError:

>>> semver.parse("1.2")
Traceback (most recent call last)
...
ValueError: 1.2 is not valid SemVer string

Parsing a Version String¶

“Parsing” in this context means to identify the different parts in a string.

With semver.parse_version_info():

>>> semver.parse_version_info("3.4.5-pre.2+build.4")
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')

With semver.VersionInfo.parse() (basically the same as semver.parse_version_info()):

>>> semver.VersionInfo.parse("3.4.5-pre.2+build.4")
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')

With semver.parse():

>>> semver.parse("3.4.5-pre.2+build.4")
{'major': 3, 'minor': 4, 'patch': 5,  'prerelease': 'pre.2', 'build': 'build.4'}

Checking for a Valid Semver Version¶

If you need to check a string if it is a valid semver version, use the classmethod semver.VersionInfo.isvalid():

>>> VersionInfo.isvalid("1.0.0")
True
>>> VersionInfo.isvalid("invalid")
False

Accessing Parts of a Version¶

The semver.VersionInfo contains attributes to access the different parts of a version:

>>> v = VersionInfo.parse("3.4.5-pre.2+build.4")
>>> v.major
3
>>> v.minor
4
>>> v.patch
5
>>> v.prerelease
'pre.2'
>>> v.build
'build.4'

However, the attributes are read-only. You cannot change an attribute. If you do, you get an AttributeError:

>>> v.minor = 5
Traceback (most recent call last)
...
AttributeError: attribute 'minor' is readonly

In case you need the different parts of a version stepwise, iterate over the semver.VersionInfo instance:

>>> for item in VersionInfo.parse("3.4.5-pre.2+build.4"):
...     print(item)
3
4
5
pre.2
build.4
>>> list(VersionInfo.parse("3.4.5-pre.2+build.4"))
[3, 4, 5, 'pre.2', 'build.4']

Replacing Parts of a Version¶

If you want to replace different parts of a version, but leave other parts unmodified, use one of the functions semver.replace() or semver.VersionInfo.replace():

From a version string:

>>> semver.replace("1.4.5-pre.1+build.6", major=2)
'2.4.5-pre.1+build.6'

From a semver.VersionInfo instance:

>>> version = semver.VersionInfo.parse("1.4.5-pre.1+build.6")
>>> version.replace(major=2, minor=2)
VersionInfo(major=2, minor=2, patch=5, prerelease='pre.1', build='build.6')

If you pass invalid keys you get an exception:

>>> semver.replace("1.2.3", invalidkey=2)
Traceback (most recent call last)
...
TypeError: replace() got 1 unexpected keyword argument(s): invalidkey
>>> version = semver.VersionInfo.parse("1.4.5-pre.1+build.6")
>>> version.replace(invalidkey=2)
Traceback (most recent call last)
...
TypeError: replace() got 1 unexpected keyword argument(s): invalidkey

Converting Different Version Types¶

Depending which function you call, you get different types (as explained in the beginning of this chapter).

From a string into semver.VersionInfo:

>>> semver.VersionInfo.parse("3.4.5-pre.2+build.4")
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')

From semver.VersionInfo into a string:

>>> str(semver.VersionInfo.parse("3.4.5-pre.2+build.4"))
'3.4.5-pre.2+build.4'

From a dictionary into semver.VersionInfo:
```
>>> d = {'major': 3, 'minor': 4, 'patch': 5,  'prerelease': 'pre.2', 'build': 'build.4'}
>>> semver.VersionInfo(**d)
VersionInfo(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')
```
As a minimum requirement, your dictionary needs at least the major key, others can be omitted. You get a TypeError if your dictionary contains invalid keys. Only major, minor, patch, prerelease, and build are allowed.

From a tuple into semver.VersionInfo:

>>> t = (3, 5, 6)
>>> semver.VersionInfo(*t)
VersionInfo(major=3, minor=5, patch=6, prerelease=None, build=None)

From a semver.VersionInfo into a dictionary:

>>> v = semver.VersionInfo(major=3, minor=4, patch=5)
>>> semver.parse(str(v))
{'major': 3, 'minor': 4, 'patch': 5, 'prerelease': None, 'build': None}

Increasing Parts of a Version¶

The semver module contains the following functions to raise parts of a version:

semver.bump_major(): raises the major part and set all other parts to zero. Set prerelease and build to None.
semver.bump_minor(): raises the minor part and sets patch to zero. Set prerelease and build to None.
semver.bump_patch(): raises the patch part. Set prerelease and build to None.
semver.bump_prerelease(): raises the prerelease part and set build to None.
semver.bump_build(): raises the build part.

>>> semver.bump_major("3.4.5-pre.2+build.4")
'4.0.0'
>>> semver.bump_minor("3.4.5-pre.2+build.4")
'3.5.0'
>>> semver.bump_patch("3.4.5-pre.2+build.4")
'3.4.6'
>>> semver.bump_prerelease("3.4.5-pre.2+build.4")
'3.4.5-pre.3'
>>> semver.bump_build("3.4.5-pre.2+build.4")
'3.4.5-pre.2+build.5'

Comparing Versions¶

To compare two versions depends on your type:

Two strings

Use semver.compare():
```
>>> semver.compare("1.0.0", "2.0.0")
-1
>>> semver.compare("2.0.0", "1.0.0")
1
>>> semver.compare("2.0.0", "2.0.0")
0
```
The return value is negative if version1 < version2, zero if version1 == version2 and strictly positive if version1 > version2.

Two semver.VersionInfo types

Use the specific operator. Currently, the operators <, <=, >, >=, ==, and != are supported:

>>> v1 = VersionInfo.parse("3.4.5")
>>> v2 = VersionInfo.parse("3.5.1")
>>> v1 < v2
True
>>> v1 > v2
False

A semver.VersionInfo type and a tuple

Use the operator as with two semver.VersionInfo types:

>>> v = VersionInfo.parse("3.4.5")
>>> v > (1, 0)
True
>>> v < (3, 5)
True

The opposite does also work:

>>> (1, 0) < v
True
>>> (3, 5) > v
True

Other types cannot be compared (like dictionaries, lists etc).

If you need to convert some types into other, refer to Converting Different Version Types.

Comparing Versions through an Expression¶

If you need a more fine-grained approach of comparing two versions, use the semver.match() function. It expects two arguments:

a version string
a match expression

Currently, the match expression supports the following operators:

< smaller than
> greater than
>= greater or equal than
<= smaller or equal than
== equal
!= not equal

That gives you the following possibilities to express your condition:

>>> semver.match("2.0.0", ">=1.0.0")
True
>>> semver.match("1.0.0", ">1.0.0")
False

Getting Minimum and Maximum of two Versions¶

>>> semver.max_ver("1.0.0", "2.0.0")
'2.0.0'
>>> semver.min_ver("1.0.0", "2.0.0")
'1.0.0'

Dealing with Invalid Versions¶

As semver follows the semver specification, it cannot parse version strings which are considered “invalid” by that specification. The semver library cannot know all the possible variations so you need to help the library a bit.

For example, if you have a version string v1.2 would be an invalid semver version. However, “basic” version strings consisting of major, minor, and patch part, can be easy to convert. The following function extract this information and returns a tuple with two items:

import re

BASEVERSION = re.compile(
    r"""[vV]?
        (?P<major>0|[1-9]\d*)
        (\.
        (?P<minor>0|[1-9]\d*)
        (\.
            (?P<patch>0|[1-9]\d*)
        )?
        )?
    """,
    re.VERBOSE,
)
def coerce(version):
    """
    Convert an incomplete version string into a semver-compatible VersionInfo
    object

    * Tries to detect a "basic" version string (``major.minor.patch``).
    * If not enough components can be found, missing components are
        set to zero to obtain a valid semver version.

    :param str version: the version string to convert
    :return: a tuple with a :class:`VersionInfo` instance (or ``None``
        if it's not a version) and the rest of the string which doesn't
        belong to a basic version.
    :rtype: tuple(:class:`VersionInfo` | None, str)
    """
    match = BASEVERSION.search(version)
    if not match:
        return (None, version)

    ver = {
        key: 0 if value is None else value
        for key, value in match.groupdict().items()
    }
    ver = semver.VersionInfo(**ver)
    rest = match.string[match.end() :]
    return ver, rest

The function returns a tuple, containing a VersionInfo instance or None as the first element and the rest as the second element. The second element (the rest) can be used to make further adjustments.

For example:

>>> coerce("v1.2")
(VersionInfo(major=1, minor=2, patch=0, prerelease=None, build=None), '')
>>> coerce("v2.5.2-bla")
(VersionInfo(major=2, minor=5, patch=2, prerelease=None, build=None), '-bla')