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 (http://semver.org)'¶: Short description about semver

semver.__about__.__maintainer__ = ['Sebastien Celles', 'Tom Schraitle']¶: Current maintainer

semver.__about__.__version__ = '3.0.0-dev.3'¶: 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[~F]) – 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[…, ~F], 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).

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

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

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.

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

Parse version string to a Version 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

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: Optional[str]¶

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

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