API

Python helper for Semantic Versioning (http://semver.org/)

semver.SEMVER_SPEC_VERSION = '2.0.0': Contains the implemented semver.org version of the spec

class semver.VersionInfo(major, minor=0, patch=0, prerelease=None, build=None)

A semver compatible version class.

Parameters:

major (int) – version when you make incompatible API changes.
minor (int) – version when you add functionality in a backwards-compatible manner.
patch (int) – version when you make backwards-compatible bug fixes.
prerelease (str) – an optional prerelease string
build (str) – an optional build string

property build: The build part of a version (read-only).

bump_build(token='build')

Raise the build part of the version, return a new object but leave self untouched.

Parameters:: token – defaults to ‘build’
Returns:: new object with the raised build part
Return type:: VersionInfo

>>> ver = semver.VersionInfo.parse("3.4.5-rc.1+build.9")
>>> ver.bump_build()
VersionInfo(major=3, minor=4, patch=5, prerelease='rc.1', build='build.10')

bump_major()

Raise the major part of the version, return a new object but leave self untouched.

Returns:: new object with the raised major part
Return type:: VersionInfo

>>> ver = semver.VersionInfo.parse("3.4.5")
>>> ver.bump_major()
VersionInfo(major=4, minor=0, patch=0, prerelease=None, build=None)

bump_minor()

Raise the minor part of the version, return a new object but leave self untouched.

Returns:: new object with the raised minor part
Return type:: VersionInfo

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

bump_patch()

Raise the patch part of the version, return a new object but leave self untouched.

Returns:: new object with the raised patch part
Return type:: VersionInfo

>>> ver = semver.VersionInfo.parse("3.4.5")
>>> ver.bump_patch()
VersionInfo(major=3, minor=4, patch=6, prerelease=None, build=None)

bump_prerelease(token='rc')

Raise the prerelease part of the version, return a new object but leave self untouched.

Parameters:: token – defaults to ‘rc’
Returns:: new object with the raised prerelease part
Return type:: VersionInfo

>>> ver = semver.VersionInfo.parse("3.4.5-rc.1")
>>> ver.bump_prerelease()
VersionInfo(major=3, minor=4, patch=5, prerelease='rc.2', build=None)

compare(other)

Compare self with other.

Parameters:: other – the second version (can be string, a dict, tuple/list, or a VersionInfo instance)
Returns:: The return value is negative if ver1 < ver2, zero if ver1 == ver2 and strictly positive if ver1 > ver2
Return type:: int

>>> semver.VersionInfo.parse("1.0.0").compare("2.0.0")
-1
>>> semver.VersionInfo.parse("2.0.0").compare("1.0.0")
1
>>> semver.VersionInfo.parse("2.0.0").compare("2.0.0")
0
>>> semver.VersionInfo.parse("2.0.0").compare(dict(major=2, minor=0, patch=0))
0

finalize_version()

Remove any prerelease and build metadata from the version.

Returns:: a new instance with the finalized version string
Return type:: VersionInfo

>>> str(semver.VersionInfo.parse('1.2.3-rc.5').finalize_version())
'1.2.3'

classmethod isvalid(version)

Check if the string is a valid semver version.

New in version 2.9.1.

Parameters:: version (str) – the version string to check
Returns:: True if the version string is a valid semver version, False otherwise.
Return type:: bool

property major: The major part of a version (read-only).

match(match_expr)

Compare self to match a match expression.

Parameters:: match_expr (str) – operator and version; valid operators are < smaller than > greater than >= greator or equal than <= smaller or equal than == equal != not equal
Returns:: True if the expression matches the version, otherwise False
Return type:: bool

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

property minor: The minor part of a version (read-only).

next_version(part, prerelease_token='rc')

Determines next version, preserving natural order.

New in version 2.10.0.

This function is taking prereleases into account. The “major”, “minor”, and “patch” raises the respective parts like the bump_* functions. The real difference is using the “preprelease” part. It gives you the next patch version of the prerelease, for example:

>>> str(semver.VersionInfo.parse("0.1.4").next_version("prerelease"))
'0.1.5-rc.1'

Parameters:

part – One of “major”, “minor”, “patch”, or “prerelease”
prerelease_token – prefix string of prerelease, defaults to ‘rc’

Returns:

new object with the appropriate part raised

Return type:

VersionInfo

classmethod parse(version)

Parse version string to a VersionInfo instance.

Parameters:: version – version string
Returns:: a VersionInfo instance
Raises:: ValueError
Return type:: VersionInfo

Changed in version 2.11.0: Changed method from static to classmethod to allow subclasses.

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

property patch: The patch part of a version (read-only).

property prerelease: The prerelease part of a version (read-only).

replace(**parts)

Replace one or more parts of a version and return a new VersionInfo object, but leave self untouched

New in version 2.9.0: Added VersionInfo.replace()

Parameters:: parts (dict) – the parts to be updated. Valid keys are: major, minor, patch, prerelease, or build
Returns:: the new VersionInfo object with the changed parts
Raises:: TypeError, if parts contains invalid keys

to_dict()

Convert the VersionInfo object to an OrderedDict.

New in version 2.10.0: Renamed VersionInfo._asdict to VersionInfo.to_dict to make this function available in the public API.

Returns:: an OrderedDict with the keys in the order major, minor, patch, prerelease, and build.
Return type:: collections.OrderedDict

>>> semver.VersionInfo(3, 2, 1).to_dict()
OrderedDict([('major', 3), ('minor', 2), ('patch', 1), ('prerelease', None), ('build', None)])

to_tuple()

Convert the VersionInfo object to a tuple.

New in version 2.10.0: Renamed VersionInfo._astuple to VersionInfo.to_tuple to make this function available in the public API.

Returns:: a tuple with all the parts
Return type:: tuple

>>> semver.VersionInfo(5, 3, 1).to_tuple()
(5, 3, 1, None, None)

semver.bump_build(version, token='build')

Raise the build part of the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.bump_build() instead.

Parameters:

version – version string
token – defaults to ‘build’

Returns:

the raised version string

Return type:

str

>>> semver.bump_build('3.4.5-rc.1+build.9')
'3.4.5-rc.1+build.10'

semver.bump_major(version)

Raise the major part of the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.bump_major() instead.

Param:: version string
Returns:: the raised version string
Return type:: str

>>> semver.bump_major("3.4.5")
'4.0.0'

semver.bump_minor(version)

Raise the minor part of the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.bump_minor() instead.

Param:: version string
Returns:: the raised version string
Return type:: str

>>> semver.bump_minor("3.4.5")
'3.5.0'

semver.bump_patch(version)

Raise the patch part of the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.bump_patch() instead.

Param:: version string
Returns:: the raised version string
Return type:: str

>>> semver.bump_patch("3.4.5")
'3.4.6'

semver.bump_prerelease(version, token='rc')

Raise the prerelease part of the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.bump_prerelease() instead.

Parameters:

version – version string
token – defaults to ‘rc’

Returns:

the raised version string

Return type:

str

>>> semver.bump_prerelease('3.4.5', 'dev')
'3.4.5-dev.1'

semver.cmd_bump(args)

Subcommand: Bumps a version.

Synopsis: bump <PART> <VERSION> <PART> can be major, minor, patch, prerelease, or build

Parameters:: args (argparse.Namespace) – The parsed arguments
Returns:: the new, bumped version

semver.cmd_check(args)

Subcommand: Checks if a string is a valid semver version.

Synopsis: check <VERSION>

Parameters:: args (argparse.Namespace) – The parsed arguments

semver.cmd_compare(args)

Subcommand: Compare two versions

Synopsis: compare <VERSION1> <VERSION2>

Parameters:: args (argparse.Namespace) – The parsed arguments

semver.compare(ver1, ver2)

Compare two versions strings.

Parameters:

ver1 – version string 1
ver2 – version string 2

Returns:

The return value is negative if ver1 < ver2, zero if ver1 == ver2 and strictly positive if ver1 > ver2

Return type:

int

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

semver.createparser()

Create an argparse.ArgumentParser instance.

Returns:: parser instance
Return type:: argparse.ArgumentParser

semver.deprecated(func=None, replace=None, version=None, category=<class 'DeprecationWarning'>)

Decorates a function to output a deprecation warning.

Parameters:

func – the function to decorate (or None)
replace (str) – the function to replace (use the full qualified name like semver.VersionInfo.bump_major.
version (str) – the first version when this function was deprecated.
category – allow you to specify the deprecation warning class of your choice. By default, it’s DeprecationWarning, but you can choose PendingDeprecationWarning or a custom class.

semver.finalize_version(version)

Remove any prerelease and build metadata from the version string.

Deprecated since version 2.10.0: Use semver.VersionInfo.finalize_version() instead.

New in version 2.7.9: Added finalize_version()

Parameters:: version – version string
Returns:: the finalized version string
Return type:: str

>>> semver.finalize_version('1.2.3-rc.5')
'1.2.3'

semver.format_version(major, minor, patch, prerelease=None, build=None)

Format a version string according to the Semantic Versioning specification.

Deprecated since version 2.10.0: Use str(VersionInfo(VERSION) instead.

Parameters:

major (int) – the required major part of a version
minor (int) – the required minor part of a version
patch (int) – the required patch part of a version
prerelease (str) – the optional prerelease part of a version
build (str) – the optional build part of a version

Returns:

the formatted string

Return type:

str

>>> semver.format_version(3, 4, 5, 'pre.2', 'build.4')
'3.4.5-pre.2+build.4'

semver.main(cliargs=None)

Entry point for the application script.

Parameters:: cliargs (list) – Arguments to parse or None (=use sys.argv)
Returns:: error code
Return type:: int

semver.match(version, match_expr)

Compare two versions strings through a comparison.

Parameters:

version (str) – a version string
match_expr (str) – operator and version; valid operators are < smaller than > greater than >= greator or equal than <= smaller or equal than == equal != not equal

Returns:

True if the expression matches the version, otherwise False

Return type:

bool

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

semver.max_ver(ver1, ver2)

Returns the greater version of two versions strings.

Parameters:

ver1 – version string 1
ver2 – version string 2

Returns:

the greater version of the two

Return type:

VersionInfo

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

semver.min_ver(ver1, ver2)

Returns the smaller version of two versions strings.

Parameters:

ver1 – version string 1
ver2 – version string 2

Returns:

the smaller version of the two

Return type:

VersionInfo

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

semver.parse(version)

Parse version to major, minor, patch, pre-release, build parts.

Deprecated since version 2.10.0: Use semver.VersionInfo.parse() instead.

Parameters:: version – version string
Returns:: dictionary with the keys ‘build’, ‘major’, ‘minor’, ‘patch’, and ‘prerelease’. The prerelease or build keys can be None if not provided
Return type:: dict

>>> ver = semver.parse('3.4.5-pre.2+build.4')
>>> ver['major']
3
>>> ver['minor']
4
>>> ver['patch']
5
>>> ver['prerelease']
'pre.2'
>>> ver['build']
'build.4'

semver.parse_version_info(version)

Parse version string to a VersionInfo instance.

Deprecated since version 2.10.0: Use semver.VersionInfo.parse() instead.

New in version 2.7.2: Added semver.parse_version_info()

Parameters:: version – version string
Returns:: a VersionInfo instance
Return type:: VersionInfo

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

semver.process(args)

Process the input from the CLI.

Parameters:

args (argparse.Namespace) – The parsed arguments
parser (argparse.ArgumentParser) – the parser instance

Returns:

result of the selected action

Return type:

str

semver.replace(version, **parts)

Replace one or more parts of a version and return the new string.

Deprecated since version 2.10.0: Use semver.VersionInfo.replace() instead.

New in version 2.9.0: Added replace()

Parameters:

version (str) – the version string to replace
parts (dict) – the parts to be updated. Valid keys are: major, minor, patch, prerelease, or build

Returns:

the replaced version string

Raises:

TypeError, if parts contains invalid keys

Return type:

str

>>> import semver
>>> semver.replace("1.2.3", major=2, patch=10)
'2.2.10'