8. API Reference

8.1. Metadata semver.__about__

Metadata about semver.

Contains information about semver’s version, the implemented version of the semver specifictation, author, maintainers, and description.

semver.__about__.__author__ = 'Kostiantyn Rybnikov'

Original semver author

semver.__about__.__description__ = 'Python helper for Semantic Versioning (https://semver.org)'

Short description about semver

semver.__about__.__maintainer__ = ['Sebastien Celles', 'Tom Schraitle']

Current maintainer

semver.__about__.__version__ = '3.0.4'

Semver version

semver.__about__.SEMVER_SPEC_VERSION = '2.0.0'

Supported semver specification

8.2. Deprecated Functions in semver._deprecated

Contains all deprecated functions.

semver._deprecated.compare(ver1, ver2)

Compare two versions strings.

Deprecated since version 3.0.0: The situation of this function is unclear and it might disappear in the future. If possible, use semver.version.Version.compare(). See #258 for details.

Parameters:

• ver1 (str) – first version string

• ver2 (str) – second version string

Return type:

int

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._deprecated.bump_build(version, token='build')

Raise the build part of the version string.

Deprecated since version 2.10.0: Use 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._deprecated.bump_major(version)

Raise the major part of the version string.

Deprecated since version 2.10.0: Use bump_major() instead.

Param:

version string

Returns:

the raised version string

Return type:

str

>>> semver.bump_major("3.4.5")
'4.0.0'

semver._deprecated.bump_minor(version)

Raise the minor part of the version string.

Deprecated since version 2.10.0: Use bump_minor() instead.

Param:

version string

Returns:

the raised version string

Return type:

str

>>> semver.bump_minor("3.4.5")
'3.5.0'

semver._deprecated.bump_patch(version)

Raise the patch part of the version string.

Deprecated since version 2.10.0: Use bump_patch() instead.

Param:

version string

Returns:

the raised version string

Return type:

str

>>> semver.bump_patch("3.4.5")
'3.4.6'

semver._deprecated.bump_prerelease(version, token='rc')

Raise the prerelease part of the version string.

Deprecated since version 2.10.0: Use 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._deprecated.deprecated(func=None, *, replace=None, version=None, remove=None, category=<class 'DeprecationWarning'>)

Decorates a function to output a deprecation warning.

Parameters:

• func (Optional[TypeVar(F, bound= Callable)]) – the function to decorate

• replace (Optional[str]) – the function to replace (use the full qualified name like semver.version.Version.bump_major.

• version (Optional[str]) – the first version when this function was deprecated.

• category (Type[Warning]) – 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[..., TypeVar(F, bound= Callable)], partial]

Returns:

decorated function which is marked as deprecated

semver._deprecated.finalize_version(version)

Remove any prerelease and build metadata from the version string.

Deprecated since version 2.10.0: Use finalize_version() instead.

Added 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._deprecated.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(Version(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._deprecated.match(version, match_expr)

Compare two versions strings through a comparison.

Deprecated since version 2.10.0: Use match() instead.

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._deprecated.max_ver(ver1, ver2)

Returns the greater version of two versions strings.

Deprecated since version 2.10.2: Use max() instead.

Parameters:

• ver1 – version string 1

• ver2 – version string 2

Returns:

the greater version of the two

Return type:

Version

>>> semver.max_ver("1.0.0", "2.0.0")
'2.0.0'

semver._deprecated.min_ver(ver1, ver2)

Returns the smaller version of two versions strings.

Deprecated since version 2.10.2: Use Use min() instead.

Parameters:

• ver1 – version string 1

• ver2 – version string 2

Returns:

the smaller version of the two

Return type:

Version

>>> semver.min_ver("1.0.0", "2.0.0")
'1.0.0'

semver._deprecated.parse(version)

Parse version to major, minor, patch, pre-release, build parts.

Deprecated since version 2.10.0: Use 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._deprecated.parse_version_info(version)

Parse version string to a Version instance.

Deprecated since version 2.10.0: Use parse() instead.

Added in version 2.7.2: Added semver.parse_version_info()

Parameters:

version – version string

Returns:

a VersionInfo instance

>>> version_info = semver.Version.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._deprecated.replace(version, **parts)

Replace one or more parts of a version and return the new string.

Deprecated since version 2.10.0: Use replace() instead.

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

8.3. CLI Parsing semver.cli

CLI parsing for pysemver command.

Each command in pysemver is mapped to a cmd_ function. The main function calls createparser and process to parse and process all the commandline options.

The result of each command is printed on stdout.

semver.cli.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.cli.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.cli.cmd_compare(args)

Subcommand: Compare two versions.

Synopsis: compare <VERSION1> <VERSION2>

Parameters:

args (Namespace) – The parsed arguments

Return type:

str

semver.cli.createparser()

Create an argparse.ArgumentParser instance.

Return type:

ArgumentParser

Returns:

parser instance

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

8.4. Entry point semver.__main__

Module to support call with __main__.py. Used to support the following call:

$ python3 -m semver ...

This makes it also possible to “run” a wheel like in this command:

$ python3 semver-3*-py3-none-any.whl/semver -h

8.5. Version Handling semver.version

Version handling by a semver compatible version class.

semver.version.VersionInfo

Keep the VersionInfo name for compatibility

class semver.version.Version(major, minor=0, patch=0, prerelease=None, build=None)

A semver compatible version class.

See specification at https://semver.org.

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

NAMES: ClassVar[Tuple[str, ...]] = ('major', 'minor', 'patch', 'prerelease', 'build')

The names of the different parts of a version

__eq__(other)

Return self==value.

Return type:

bool

__ge__(other)

Return self>=value.

Return type:

bool

__getitem__(index)

self.__getitem__(index) <==> self[index] Implement getitem.

If the part requested is undefined, or a part of the range requested is undefined, it will throw an index error. Negative indices are not supported.

Parameters:

index (Union[int, slice]) – a positive integer indicating the offset or a slice() object

Raises:

IndexError – if index is beyond the range or a part is None

Return type:

Union[int, str, None, Tuple[Union[int, str], ...]]

Returns:

the requested part of the version at position index

>>> ver = semver.Version.parse("3.4.5")
>>> ver[0], ver[1], ver[2]
(3, 4, 5)

__gt__(other)

Return self>value.

Return type:

bool

__hash__()

Return hash(self).

Return type:

int

__iter__()

Return iter(self).

Return type:

Iterable[Union[int, str, None]]

__le__(other)

Return self<=value.

Return type:

bool

__lt__(other)

Return self<value.

Return type:

bool

__ne__(other)

Return self!=value.

Return type:

bool

__repr__()

Return repr(self).

Return type:

str

__str__()

Return str(self).

Return type:

str

property build: str | None

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 (Optional[str]) – defaults to 'build'

Return type:

Version

Returns:

new Version object with the raised build part. The original object is not modified.

>>> ver = semver.parse("3.4.5-rc.1+build.9")
>>> ver.bump_build()
Version(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:

Version

Returns:

new object with the raised major part

>>> ver = semver.parse("3.4.5")
>>> ver.bump_major()
Version(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:

Version

Returns:

new object with the raised minor part

>>> ver = semver.parse("3.4.5")
>>> ver.bump_minor()
Version(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:

Version

Returns:

new object with the raised patch part

>>> ver = semver.parse("3.4.5")
>>> ver.bump_patch()
Version(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 (Optional[str]) – defaults to 'rc'

Return type:

Version

Returns:

new Version object with the raised prerelease part. The original object is not modified.

>>> ver = semver.parse("3.4.5")
>>> ver.bump_prerelease().prerelease
'rc.2'
>>> ver.bump_prerelease('').prerelease
'1'
>>> ver.bump_prerelease(None).prerelease
'rc.1'

compare(other)

Compare self with other.

Parameters:

other (Union[Version, 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

>>> Version.parse("1.0.0").compare("2.0.0")
-1
>>> Version.parse("2.0.0").compare("1.0.0")
1
>>> Version.parse("2.0.0").compare("2.0.0")
0

finalize_version()

Remove any prerelease and build metadata from the version.

Return type:

Version

Returns:

a new instance with the finalized version string

>>> str(semver.Version.parse('1.2.3-rc.5').finalize_version())
'1.2.3'

is_compatible(other)

Check if current version is compatible with other version.

The result is True, if either of the following is true:

• both versions are equal, or

• both majors are equal and higher than 0. Same for both minors. Both pre-releases are equal, or

• both majors are equal and higher than 0. The minor of b’s minor version is higher then a’s. Both pre-releases are equal.

The algorithm does not check patches.

Added in version 3.0.0.

Parameters:

other (Version) – the version to check for compatibility

Return type:

bool

Returns:

True, if other is compatible with the old version, otherwise False

>>> Version(1, 1, 0).is_compatible(Version(1, 0, 0))
False
>>> Version(1, 0, 0).is_compatible(Version(1, 1, 0))
True

classmethod is_valid(version)

Check if the string is a valid semver version.

Added in version 2.9.1.

Changed in version 3.0.0: Renamed from isvalid()

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

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) – optional 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.Version.parse("2.0.0").match(">=1.0.0")
True
>>> semver.Version.parse("1.0.0").match(">1.0.0")
False
>>> semver.Version.parse("4.0.4").match("4.0.4")
True

property minor: int

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

Return type:

int

next_version(part, prerelease_token='rc')

Determines next version, preserving natural order.

Added 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 “prerelease” part. It gives you the next patch version of the prerelease, for example:

>>> str(semver.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:

Version

Returns:

new object with the appropriate part raised

classmethod parse(version, optional_minor_and_patch=False)

Parse version string to a Version instance.

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

Changed in version 3.0.0: Added optional parameter optional_minor_and_patch to allow optional minor and patch parts.

Parameters:

• version (Union[str, bytes]) – version string

• optional_minor_and_patch (bool) – if set to true, the version string to parse can contain optional minor and patch parts. Optional parts are set to zero. By default (False), the version string to parse has to follow the semver specification.

Return type:

TypeVar(T, bound= Version)

Returns:

a new Version instance

Raises:

• ValueError – if version is invalid

• TypeError – if version contains the wrong type

>>> semver.Version.parse('3.4.5-pre.2+build.4')
Version(major=3, minor=4, patch=5, prerelease='pre.2', build='build.4')

property patch: int

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

Return type:

int

property prerelease: str | None

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 Version object, but leave self untouched.

Added in version 2.9.0: Added Version.replace()

Parameters:

parts (Union[int, str, None]) – the parts to be updated. Valid keys are: major, minor, patch, prerelease, or build

Return type:

Version

Returns:

the new Version object with the changed parts

Raises:

TypeError – if parts contain invalid keys

to_dict()

Convert the Version object to an dict.

Added in version 2.10.0: Renamed Version._asdict() to Version.to_dict() to make this function available in the public API.

Return type:

Dict[str, Union[int, str, None]]

Returns:

an dict with the keys in the order major, minor, patch, prerelease, and build.

>>> semver.Version(3, 2, 1).to_dict()
{'major': 3, 'minor': 2, 'patch': 1, 'prerelease': None, 'build': None}

to_tuple()

Convert the Version object to a tuple.

Added in version 2.10.0: Renamed Version._astuple() to Version.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.Version(5, 3, 1).to_tuple()
(5, 3, 1, None, None)