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 choosePendingDeprecationWarning
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: >>> 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: >>> 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
instanceReturn 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
, orbuild
Returns: the replaced version string
Raises: TypeError, if
parts
contains invalid keysReturn 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 argumentsReturns: 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
- args (
-
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:
-
static
parse
(version)¶ Parse version string to a VersionInfo instance.
Parameters: version – version string Returns: a VersionInfo
instanceRaises: ValueError
Return type: 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 (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 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 partsRaises: 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)