7. API Reference¶

7.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.0'¶: Semver version

semver.__about__.SEMVER_SPEC_VERSION = '2.0.0'¶: Supported semver specification

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

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

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

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'

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

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

7.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 = ('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: Optional[str]¶: 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 (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

>>> semver.compare("2.0.0")
-1
>>> semver.compare("1.0.0")
1
>>> semver.compare("2.0.0")
0
>>> semver.compare(dict(major=2, minor=0, patch=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.

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

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

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

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

property prerelease: Optional[str]¶: The prerelease part of a version (read-only).

replace(**parts)¶

Replace one or more parts of a version and return a new Version object, but leave self untouched

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

New 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 OrderedDict with the keys in the order major, minor, patch, prerelease, and build.

>>> semver.Version(3, 2, 1).to_dict()
OrderedDict([('major', 3), ('minor', 2), ('patch', 1), ('prerelease', None), ('build', None)])

to_tuple()¶

Convert the Version object to a tuple.

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

Navigation

Related Topics

7. API Reference¶

7.1. Metadata `semver.about`¶

7.2. Deprecated Functions in `semver._deprecated`¶

7.3. CLI Parsing `semver.cli`¶

7.4. Entry point `semver.main`¶

7.5. Version Handling `semver.version`¶

7. API Reference¶

7.1. Metadata semver.__about__¶

7.2. Deprecated Functions in semver._deprecated¶

7.3. CLI Parsing semver.cli¶

7.4. Entry point semver.__main__¶

7.5. Version Handling semver.version¶

7.1. Metadata `semver.about`¶

7.2. Deprecated Functions in `semver._deprecated`¶

7.3. CLI Parsing `semver.cli`¶

7.4. Entry point `semver.main`¶

7.5. Version Handling `semver.version`¶