API¶

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

semver.bump_build(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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.compare(*args, **kwargs)¶

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.deprecated(func=None, replace=None, version=None, category=<type 'exceptions.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(*args, **kwargs)¶

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(*args, **kwargs)¶

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.match(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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(*args, **kwargs)¶

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.replace(*args, **kwargs)¶

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'

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.createparser()¶

Create an argparse.ArgumentParser instance.

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

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

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

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

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

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

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)