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.2'¶
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 stringver2 (
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 decoratereplace (
Optional
[str
]) – the function to replace (use the full qualified name likesemver.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’sDeprecationWarning
, but you can choosePendingDeprecationWarning
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
, orbuild
- 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 argumentsparser – 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 stringbuild (
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 aslice()
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).
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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 stringoptional_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: str | None¶
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()
- to_dict()¶
Convert the Version object to an dict.
New in version 2.10.0: Renamed
Version._asdict()
toVersion.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
, andbuild
.
>>> 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.
New in version 2.10.0: Renamed
Version._astuple()
toVersion.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)