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 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'
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 argumentsparser – 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 stringbuild (
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 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: 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
- 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: 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 untouchedNew in version 2.9.0: Added
Version.replace()
- to_dict()¶
Convert the Version object to an OrderedDict.
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 OrderedDict with the keys in the order
major
,minor
,patch
,prerelease
, andbuild
.
>>> 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()
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)