Reference¶
Module-level functions¶
-
semantic_version.
compare
(v1, v2)¶ Compare two version strings, and return a result similar to that of
cmp()
:>>> compare('0.1.1', '0.1.2') -1 >>> compare('0.1.1', '0.1.1') 0 >>> compare('0.1.1', '0.1.1-alpha') 1
Parameters: - v1 (str) – The first version to compare
- v2 (str) – The second version to compare
Raises: ValueError
, if any version string is invalidReturn type: int
, -1 / 0 / 1 as for acmp()
comparison;NotImplemented
if versions only differ by build metadata
Warning
Since build metadata has no ordering,
compare(Version('0.1.1'), Version('0.1.1+3'))
returns NotImplemented
-
semantic_version.
match
(spec, version)¶ Check whether a version string matches a specification string:
>>> match('>=0.1.1', '0.1.2') True >>> match('>=0.1.1', '0.1.1-alpha') False >>> match('~0.1.1', '0.1.1-alpha') True
Parameters: - spec (str) – The specification to use, as a string
- version (str) – The version string to test against the spec
Raises: ValueError
, if thespec
or theversion
is invalidReturn type: bool
Representing a version (the Version class)¶
-
class
semantic_version.
Version
(version_string[, partial=False]) Object representation of a SemVer-compliant version.
Constructed from a textual version string:
>>> Version('1.1.1') Version('1.1.1') >>> str(Version('1.1.1')) '1.1.1'
-
class
semantic_version.
Version
(major: int, minor: int, patch: int, prereleases: tuple, build: tuple[, partial=False])¶ Constructed from named components:
>>> Version(major=1, minor=2, patch=3) Version('1.2.3')
Attributes
-
major
¶ int
, the major version number
-
patch
¶ int
, the patch version number.May be
None
for apartial
version number in a<major>
or<major>.<minor>
format.
-
prerelease
¶ tuple
ofstrings
, the prerelease component.It contains the various dot-separated identifiers in the prerelease component.
May be
None
for apartial
version number in a<major>
,<major>.<minor>
or<major>.<minor>.<patch>
format.
-
build
¶ tuple
ofstrings
, the build metadata.It contains the various dot-separated identifiers in the build metadata.
May be
None
for apartial
version number in a<major>
,<major>.<minor>
,<major>.<minor>.<patch>
or<major>.<minor>.<patch>-<prerelease>
format.
-
precedence_key
¶ Read-only attribute; suited for use in
sort(versions, key=lambda v: v.precedence_key)
. The actual value of the attribute is considered an implementation detail; the only guarantee is that ordering versions by their precedence_key will comply with semver precedence rules.Warning
Changed in version 2.10.0.
The
build
is included in the precedence_key computation, but only for ordering stability. The only guarantee is that, for a given release of python-semanticversion, two versions’precedence_key
will always compare in the same direction if they include build metadata; that ordering is an implementation detail and shouldn’t be relied upon.
-
partial
¶ bool
, whether this is a ‘partial’ or a complete version number. Partial version number may lackminor
orpatch
version numbers.Deprecated since version 2.7: The ability to define a partial version will be removed in version 3.0. Use
SimpleSpec
instead:SimpleSpec('1.x.x')
.
Methods
-
next_major
(self)¶ Return the next major version, i.e the smallest version strictly greater than the current one with minor and patch set to 0 and no prerelease/build.
>>> Version('1.0.2').next_major() Version('2.0.0') >>> Version('1.0.0+b3').next_major() Version('2.0.0') >>> Version('1.0.0-alpha').next_major() Version('1.0.0')
-
next_minor
(self)¶ Return the next minor version, i.e the smallest version strictly greater than the current one, with a patch level of
0
.>>> Version('1.0.2').next_minor() Version('1.1.0') >>> Version('1.0.0+b3').next_minor() Version('1.1.0') >>> Version('1.1.2-alpha').next_minor() Version('1.2.0') >>> Version('1.1.0-alpha').next_minor() Version('1.1.0')
-
next_patch
(self)¶ Return the next patch version, i.e the smallest version strictly greater than the current one with empty
prerelease
andbuild
.>>> Version('1.0.2').next_patch() Version('1.0.3') >>> Version('1.0.2+b3').next_patch() Version('1.0.3') >>> Version('1.0.2-alpha').next_patch() Version('1.0.2')
Warning
The next patch version of a version with a non-empty
prerelease
is the version without thatprerelease
component: it’s the smallest “pure” patch version strictly greater than that version.
-
truncate(self, level='patch']):
Returns a similar level, but truncated at the provided level.
>>> Version('1.0.2-rc1+b43.24').truncate() Version('1.0.2') >>> Version('1.0.2-rc1+b43.24').truncate('minor') Version('1.0.0') >>> Version('1.0.2-rc1+b43.24').truncate('prerelease') Version('1.0.2-rc1')
-
__iter__
(self)¶ Iterates over the version components (
major
,minor
,patch
,prerelease
,build
):>>> list(Version('0.1.1')) [0, 1, 1, [], []]
Note
This may pose some subtle bugs when iterating over a single version while expecting an iterable of versions – similar to:
>>> list('abc') ['a', 'b', 'c'] >>> list(('abc',)) ['abc']
-
__cmp__
(self, other)¶ Provides comparison methods with other
Version
objects.The rules are:
If any compared object is
partial
:- Begin comparison using the SemVer scheme
- If a component (
minor
,patch
,prerelease
orbuild
) was absent from thepartial
Version
– represented withNone
–, consider both versions equal.
For instance,
Version('1.0', partial=True)
means “any version beginning in1.0
”.Version('1.0.1-alpha', partial=True)
means “The1.0.1-alpha
version or any any release differing only in build metadata”:1.0.1-alpha+build3
matches,1.0.1-alpha.2
doesn’t.
Examples:
>>> Version('1.0', partial=True) == Version('1.0.1') True >>> Version('1.0.1-rc1.1') == Version('1.0.1-rc1', partial=True) False >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1') False >>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1', partial=True) True
-
__str__
(self)¶ Returns the standard text representation of the version:
>>> v = Version('0.1.1-rc2+build4.4') >>> v Version('0.1.1-rc2+build4.4') >>> str(v) '0.1.1-rc2+build4.4'
-
__hash__
(self)¶ Provides a hash based solely on the components.
Allows using a
Version
as a dictionary key.
Class methods
-
classmethod
parse
(cls, version_string[, partial=False])¶ Parse a version string into a
(major, minor, patch, prerelease, build)
tuple.Parameters: - version_string (str) – The version string to parse
- partial (bool) – Whether this should be considered a
partial
version
Raises: ValueError
, if theversion_string
is invalid.Return type: (major, minor, patch, prerelease, build)
-
classmethod
coerce
(cls, version_string[, partial=False])¶ Try to convert an arbitrary version string into a
Version
instance.Rules are:
- If no minor or patch component, and
partial
isFalse
, replace them with zeroes - Any character outside of
a-zA-Z0-9.+-
is replaced with a-
- If more than 3 dot-separated numerical components, everything from the
fourth component belongs to the
build
part - Any extra
+
in thebuild
part will be replaced with dots
Examples:
>>> Version.coerce('02') Version('2.0.0') >>> Version.coerce('1.2.3.4') Version('1.2.3+4') >>> Version.coerce('1.2.3.4beta2') Version('1.2.3+4beta2') >>> Version.coerce('1.2.3.4.5_6/7+8+9+10') Version('1.2.3+4.5-6-7.8.9.10')
Parameters: - version_string (str) – The version string to coerce
- partial (bool) – Whether to allow generating a
partial
version
Raises: ValueError
, if theversion_string
is invalid.Return type: - If no minor or patch component, and
-
Version specifications (the Spec class)¶
The SemVer specification doesn’t provide a standard description of version ranges.
And simply using a naive implementation leads to unexpected situations: >=1.2.0,<1.3.0
isn’t expected to match
version 1.3.0-rc.1
, yet a strict application of SemVer precedence rules would include it.
In order to solve this problem, each SemVer-based package management platform has designed its own rules. python-semanticversion provides a couple of implementations of those range definition syntaxes:
'simple'
(throughSimpleSpec
): A python-semanticversion specific syntax, which supports simple / intuitive patterns, and some NPM-inspired extensions;'npm'
(throughNpmSpec
): The NPM syntax, based on https://github.com/npm/node-semver#ranges- More might be added in the future.
Each of those Spec
classes provides a shared set of methods to work with versions:
-
class
semantic_version.
BaseSpec
(spec_string)¶ Converts an expression describing a range of versions into a set of clauses, and matches any
Version
against those clauses.Attributes
This class has no public attributes.
Methods
-
match
(self, version)¶ Test whether a given
Version
matches all includedSpecItem
:>>> Spec('>=1.1.0,<1.1.2').match(Version('1.1.1')) True
Parameters: version ( Version
) – The version to test against the specsReturn type: bool
-
filter
(self, versions)¶ Extract all compatible
versions
from an iterable ofVersion
objects.Parameters: versions (iterable of Version
) – The versions to filterYield: Version
-
select
(self, versions)¶ Select the highest compatible version from an iterable of
Version
objects.>>> s = Spec('>=0.1.0') >>> s.select([]) None >>> s.select([Version('0.1.0'), Version('0.1.3'), Version('0.1.1')]) Version('0.1.3')
Parameters: versions (iterable of Version
) – The versions to filterReturn type: The highest compatible Version
if at least one of the given versions is compatible;None
otherwise.
-
__contains__
(self, version)¶ Alias of the
match()
method; allows the use of theversion in speclist
syntax:>>> Version('1.1.1-alpha') in Spec('>=1.1.0,<1.1.1') True
-
__str__
(self)¶ Converting a
Spec
returns the initial description string:>>> str(Spec('>=0.1.1,!=0.1.2')) '>=0.1.1,!=0.1.2'
-
__hash__
(self)¶ Provides a hash based solely on the hash of contained specs.
Allows using a
Spec
as a dictionary key.
Class methods
-
classmethod
parse
(self, expression, syntax='simple')¶ Retrieve a
BaseSpec
object tuple from a string.Parameters: - requirement_string (str) – The textual description of the specifications
- syntax (str) – The identifier of the syntax to use for parsing
Raises: ValueError
: if therequirement_string
is invalid.Return type: BaseSpec
subclassChanged in version 2.7: This method used to return a tuple of
SpecItem
objects.
-
-
class
semantic_version.
SimpleSpec
(spec_string)¶ New in version 2.7: Previously reachable through
Spec
.Applies the python-semanticversion range specification:
- A specification of
<1.3.4
is not expected to allow1.3.4-rc2
, but strict SemVer comparisons allow it ; - It may be necessary to exclude either all variations on a patch-level release
(
!=1.3.3
) or specifically one build-level release (1.3.3+build.434
).
Specification structure:
In order to have version specification behave naturally, the
SimpleSpec
syntax uses the following rules:- A specification expression is a list of clauses separated by a comma (
,
); - A version is matched by an expression if, and only if, it matches every clause in the expression;
- A clause of
*
matches every valid version;
Equality clauses
- A clause of
==0.1.2
will match version0.1.2
and any version differing only through its build number (0.1.2+b42
matches); - A clause of
==0.1.2+b42
will only match that specific version:0.1.2+b43
and0.1.2
are excluded; - A clause of
==0.1.2+
will only match that specific version:0.1.2+b42
is excluded; - A clause of
!=0.1.2
will prevent all versions with the same major/minor/patch combination:0.1.2-rc.1
and0.1.2+b42
are excluded’ - A clause of
!=0.1.2-
will only prevent build variations of that version:0.1.2-rc.1
is included, but not0.1.2+b42
; - A clause of
!=0.1.2+
will exclude only that exact version:0.1.2-rc.1
and0.1.2+b42
are included; - Only a
==
or!=
clause may contain build-level metadata:==1.2.3+b42
is valid,>=1.2.3+b42
isn’t.
Comparison clauses
- A clause of
<0.1.2
will match versions strictly below0.1.2
, excluding prereleases of0.1.2
:0.1.2-rc.1
is excluded; - A clause of
<0.1.2-
will match versions strictly below0.1.2
, including prereleases of0.1.2
:0.1.2-rc.1
is included; - A clause of
<0.1.2-rc.3
will match versions strictly below0.1.2-rc.3
, including prereleases:0.1.2-rc.2
is included; - A clause of
<=XXX
will match versions that match<XXX
or==XXX
- A clause of
>0.1.2
will match versions strictly above0.1.2
, including all prereleases of0.1.3
. - A clause of
>0.1.2-rc.3
will match versions strictly above0.1.2-rc.3
, including matching prereleases of0.1.2
:0.1.2-rc.10
is included; - A clause of
>=XXX
will match versions that match>XXX
or==XXX
Wildcards
- A clause of
==0.1.*
is equivalent to>=0.1.0,<0.2.0
- A clause of
>=0.1.*
is equivalent to>=0.1.0
- A clause of
==1.*
or==1.*.*
is equivalent to>=1.0.0,<2.0.0
- A clause of
>=1.*
or>=1.*.*
is equivalent to>=1.0.0
- A clause of
==*
maps to>=0.0.0
- A clause of
>=*
maps to>=0.0.0
Extensions
Additionnally, python-semanticversion supports extensions from specific packaging platforms:
PyPI-style compatible release clauses:
~=2.2
means “Any release between 2.2.0 and 3.0.0”~=1.4.5
means “Any release between 1.4.5 and 1.5.0”
NPM-style specs:
~1.2.3
means “Any release between 1.2.3 and 1.3.0”^1.3.4
means “Any release between 1.3.4 and 2.0.0”
Some examples:
>>> Version('0.1.2-rc.1') in SimpleSpec('*') True >>> SimpleSpec('<0.1.2').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')]) [Version('0.1.1')] >>> SimpleSpec('<0.1.2-').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')]) [Version('0.1.2-rc.1'), Version('0.1.1')] >>> SimpleSpec('>=0.1.2,!=0.1.3,!=0.1.4-rc.1',!=0.1.5+b42).filter([ Version('0.1.2'), Version('0.1.3'), Version('0.1.3-beta'), Version('0.1.4'), Version('0.1.5'), Version('0.1.5+b42'), Version('2.0.1-rc.1'), ]) [Version('0.1.2'), Version('0.1.4'), Version('0.1.5'), Version('2.0.1-rc.1')]
- A specification of
-
class
semantic_version.
NpmSpec
(spec_string)¶ New in version 2.7.
A NPM-compliant version matching engine, based on the https://github.com/npm/node-semver#ranges specification.
>>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4') True >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x') True >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x') True
-
class
semantic_version.
Spec
(spec_string)¶ Deprecated since version 2.7: The alias from
Spec
toSimpleSpec
will be removed in 3.1.Alias to
LegacySpec
, for backwards compatibility.
-
class
semantic_version.
LegacySpec
(spec_string)¶ Deprecated since version 2.7: The
LegacySpec
class will be removed in 3.0; useSimpleSpec
instead.A
LegacySpec
class has the exact same behaviour asSimpleSpec
, with backwards-compatible features:It accepts version specifications passed in as separated arguments:
>>> Spec('>=1.0.0', '<1.2.0', '!=1.1.4,!=1.1.13') <Spec: ( <SpecItem: >= Version('1.0.0', partial=True)>, <SpecItem: < Version('1.2.0', partial=True)>, <SpecItem: != Version('1.1.4', partial=True)>, <SpecItem: != Version('1.1.13', partial=True)>, )>
It keeps a list of
SpecItem
objects, based on the initial expression components.-
__iter__
(self)¶ Returns an iterator over the contained specs:
>>> for spec in Spec('>=0.1.1,!=0.1.2'): ... print spec >=0.1.1 !=0.1.2
Attributes
-
-
class
semantic_version.
SpecItem
(spec_string)¶ Deprecated since version 2.7: This class will be removed in 3.0.
Note
This class belong to the private python-semanticversion API.
Stores a version specification, defined from a string:
>>> SpecItem('>=0.1.1') <SpecItem: >= Version('0.1.1', partial=True)>
This allows to test
Version
objects against theSpecItem
:>>> SpecItem('>=0.1.1').match(Version('0.1.1-rc1')) # pre-release satisfy conditions True >>> Version('0.1.1+build2') in SpecItem('>=0.1.1') # build metadata is ignored when checking for precedence True >>> >>> # Use the '-' marker to include the pre-release component in checks >>> SpecItem('>=0.1.1-').match(Version('0.1.1-rc1') False >>> # Use the '+' marker to include the build metadata in checks >>> SpecItem('==0.1.1+').match(Version('0.1.1+b1234') False >>>
Attributes
Class methods
-
classmethod
parse
(cls, requirement_string)¶ Retrieve a
(kind, version)
tuple from a string.Parameters: requirement_string (str) – The textual description of the specification Raises: ValueError
: if therequirement_string
is invalid.Return type: ( kind
,version
) tuple
Methods
-
match
(self, version)¶ Test whether a given
Version
matches thisSpecItem
:>>> SpecItem('>=0.1.1').match(Version('0.1.1-alpha')) True >>> SpecItem('>=0.1.1-').match(Version('0.1.1-alpha')) False
Parameters: version ( Version
) – The version to test against the specReturn type: bool
-
__str__
(self)¶ Converting a
SpecItem
to a string returns the initial description string:>>> str(SpecItem('>=0.1.1')) '>=0.1.1'
-
__hash__
(self)¶ Provides a hash based solely on the current kind and the specified version.
Allows using a
SpecItem
as a dictionary key.
Class attributes
-
KIND_LT
¶ The kind of ‘Less than’ specifications:
>>> Version('1.0.0-alpha') in Spec('<1.0.0') False
-
KIND_LTE
¶ The kind of ‘Less or equal to’ specifications:
>>> Version('1.0.0-alpha1+build999') in Spec('<=1.0.0-alpha1') True
-
KIND_EQUAL
¶ The kind of ‘equal to’ specifications:
>>> Version('1.0.0+build3.3') in Spec('==1.0.0') True
-
KIND_GTE
¶ The kind of ‘Greater or equal to’ specifications:
>>> Version('1.0.0') in Spec('>=1.0.0') True
-
KIND_GT
¶ The kind of ‘Greater than’ specifications:
>>> Version('1.0.0+build667') in Spec('>1.0.1') False
-
KIND_NEQ
¶ The kind of ‘Not equal to’ specifications:
>>> Version('1.0.1') in Spec('!=1.0.1') False
-
KIND_COMPATIBLE
¶ The kind of compatible release clauses specifications:
>>> Version('1.1.2') in Spec('~=1.1.0') True
-
classmethod