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:
>>> 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:
>>> 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:
>>> 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:
>>> 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:
>>> 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:
>>> 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:
- classmethod parse(version)
Parse version string to a VersionInfo instance.
- Parameters:
version – version string
- Returns:
a
VersionInfo
instance- Raises:
ValueError
- Return type:
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 untouchedNew in version 2.9.0: Added
VersionInfo.replace()
- Parameters:
parts (dict) – the parts to be updated. Valid keys are:
major
,minor
,patch
,prerelease
, orbuild
- Returns:
the new
VersionInfo
object with the changed parts- Raises:
TypeError
, ifparts
contains invalid keys
- to_dict()
Convert the VersionInfo object to an OrderedDict.
New in version 2.10.0: Renamed
VersionInfo._asdict
toVersionInfo.to_dict
to make this function available in the public API.- Returns:
an OrderedDict with the keys in the order
major
,minor
,patch
,prerelease
, andbuild
.- 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
toVersionInfo.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 choosePendingDeprecationWarning
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:
>>> 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:
>>> 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:
>>> 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 argumentsparser (
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
, orbuild
- 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'