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 (SupportsInt) – version when you make incompatible API changes.
minor (SupportsInt) – version when you add functionality in a backwards-compatible manner.
patch (SupportsInt) – version when you make backwards-compatible bug fixes.
prerelease (Union[str, bytes, int, None]) – an optional prerelease string
build (Union[str, bytes, int, None]) – an optional build string

property build¶

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

Return type: Optional[str]

bump_build(token='build')¶

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

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

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

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

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

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

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

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

>>> 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 (str) – defaults to ‘rc’
Return type: VersionInfo
Returns: new object with the raised prerelease part

>>> 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 (Union[VersionInfo, Dict[str, Union[int, str, None]], Collection[Union[int, str, None]], str]) – the second version
Return type: int
Returns: The return value is negative if ver1 < ver2, zero if ver1 == ver2 and strictly positive if ver1 > ver2

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

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

>>> 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
Return type: bool
Returns: True if the version string is a valid semver version, False otherwise.

property major¶

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

Return type: int

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
Return type: bool
Returns: True if the expression matches the version, otherwise False

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

Return type: int

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 (str) – One of “major”, “minor”, “patch”, or “prerelease”
prerelease_token (str) – prefix string of prerelease, defaults to ‘rc’

Return type

VersionInfo

Returns

new object with the appropriate part raised

classmethod parse(version)¶

Parse version string to a VersionInfo instance.

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

Parameters: version (Union[str, bytes]) – version string
Return type: VersionInfo
Returns: a VersionInfo instance
Raises: ValueError – if version is invalid

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

Return type: int

property prerelease¶

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

Return type: Optional[str]

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 (Union[int, str, None]) – the parts to be updated. Valid keys are: major, minor, patch, prerelease, or build
Return type: VersionInfo
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.

Return type: Dict[str, Union[int, str, None]]
Returns: an OrderedDict with the keys in the order major, minor, patch, prerelease, and build.

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

Return type: Tuple[int, int, int, Optional[str], Optional[str]]
Returns: a tuple with all the parts

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

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

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

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

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

>>> 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 (Namespace) – The parsed arguments
Return type: str
Returns: the new, bumped version

semver.cmd_check(args)¶

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

Synopsis: check <VERSION>

Parameters: args (Namespace) – The parsed arguments
Return type: None

semver.cmd_compare(args)¶

Subcommand: Compare two versions

Synopsis: compare <VERSION1> <VERSION2>

Parameters: args (Namespace) – The parsed arguments
Return type: str

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

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

Return type: ArgumentParser
Returns: parser instance

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

Decorates a function to output a deprecation warning.

Parameters

func (Optional[~F]) – the function to decorate
replace (Optional[str]) – the function to replace (use the full qualified name like semver.VersionInfo.bump_major.
version (Optional[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.

Return type

Union[Callable[…, ~F], partial]

Returns

decorated function which is marked as deprecated

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

>>> 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 – the required major part of a version
minor – the required minor part of a version
patch – the required patch part of a version
prerelease – the optional prerelease part of a version
build – the optional build part of a version

Returns

the formatted string

>>> 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)
Return type: int
Returns: error code

semver.match(version, match_expr)¶

Compare two versions strings through a comparison.

Parameters

version – a version string
match_expr – 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

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

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

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

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

>>> 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 (Namespace) – The parsed arguments
parser – the parser instance

Return type

str

Returns

result of the selected action

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 – the version string to replace
parts – 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

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

Navigation

Related Topics

API¶