API Reference¶

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

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

Deprecated Functions in `semver._deprecated`¶

Contains all deprecated functions.

semver._deprecated.deprecated(func=None, replace=None, version=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.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

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

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

Version Handling `semver.version`¶

Version handling.

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.

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

__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 (str) – defaults to build
Return type: Version
Returns: new object with the raised build part

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

>>> ver = semver.parse("3.4.5")
>>> ver.bump_prerelease()
Version(major=3, minor=4, patch=5, prerelease='rc.2', build=None)

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'

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: 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 “preprelease” 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

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 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.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 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.Version(5, 3, 1).to_tuple()
(5, 3, 1, None, None)

Navigation

Related Topics

API Reference¶

Metadata `semver.about`¶

Deprecated Functions in `semver._deprecated`¶

CLI Parsing `semver.cli`¶

Entry point `semver.main`¶

Version Handling `semver.version`¶

API Reference¶

Metadata semver.__about__¶

Deprecated Functions in semver._deprecated¶

CLI Parsing semver.cli¶

Entry point semver.__main__¶

Version Handling semver.version¶

Metadata `semver.about`¶

Deprecated Functions in `semver._deprecated`¶

CLI Parsing `semver.cli`¶

Entry point `semver.main`¶

Version Handling `semver.version`¶