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

build¶: The build part of a version.

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

>>> ver = semver.parse_version_info("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.parse_version_info("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.parse_version_info("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.parse_version_info("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:	str

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

classmethod isvalid(version)¶

Check if the string is a valid semver version.

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.

minor¶: The minor part of a version.

static parse(version)¶

Parse version string to a VersionInfo instance.

Parameters:	version – version string
Returns:	a `semver.VersionInfo` instance
Return type:	`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')

patch¶: The patch part of a version.

prerelease¶: The prerelease part of a version.

replace(**parts)¶

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

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

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

Raise the build part of the version.

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.

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.

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.

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.

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.cmp(a, b)¶

semver.comparator(operator)¶: Wrap a VersionInfo binary op method in a type-check.

semver.compare(ver1, ver2)¶

Compare two versions.

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

Remove any prerelease and build metadata from the 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 according to the Semantic Versioning specification.

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

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.

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.

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.

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

>>> version_info = semver.parse_version_info("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.

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'