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:

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

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:

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')
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 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)
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 choose PendingDeprecationWarning 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:

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

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

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'