Reference¶
Module-level functions¶
-
semantic_version.compare(v1, v2)[source]¶ 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 invalid- Return type
int, -1 / 0 / 1 as for acmp()comparison;NotImplementedif 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)[source]¶ 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 thespecor theversionis invalid- Return type
bool
Representing a version (the Version class)¶
-
class
semantic_version.Version(version_string[, partial=False])[source]¶ 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])[source]¶ Constructed from named components:
>>> Version(major=1, minor=2, patch=3) Version('1.2.3')
Attributes
-
partial¶ bool, whether this is a ‘partial’ or a complete version number. Partial version number may lackminororpatchversion numbers.Deprecated since version 2.7: The ability to define a partial version will be removed in version 3.0. Use
SimpleSpecinstead:SimpleSpec('1.x.x').
-
major¶ int, the major version number
-
patch¶ int, the patch version number.May be
Nonefor apartialversion number in a<major>or<major>.<minor>format.
-
prerelease¶ tupleofstrings, the prerelease component.It contains the various dot-separated identifiers in the prerelease component.
May be
Nonefor apartialversion number in a<major>,<major>.<minor>or<major>.<minor>.<patch>format.
-
build¶ tupleofstrings, the build metadata.It contains the various dot-separated identifiers in the build metadata.
May be
Nonefor apartialversion 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.Note that the
buildisn’t included in the precedence_key computatin.
Methods
-
next_major(self)[source]¶ 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)[source]¶ 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
prereleaseandbuild.>>> 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
prereleaseis the version without thatprereleasecomponent: 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)[source]¶ 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)[source]¶ Provides comparison methods with other
Versionobjects.The rules are:
- If any compared object is
partial: Begin comparison using the SemVer scheme
If a component (
minor,patch,prereleaseorbuild) was absent from thepartialVersion– 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-alphaversion or any any release differing only in build metadata”:1.0.1-alpha+build3matches,1.0.1-alpha.2doesn’t.
- If any compared object is
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)[source]¶ 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)[source]¶ Provides a hash based solely on the components.
Allows using a
Versionas a dictionary key.
Class methods
-
classmethod
parse(cls, version_string[, partial=False])[source]¶ 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
partialversion
- Raises
ValueError, if theversion_stringis invalid.- Return type
(major, minor, patch, prerelease, build)
-
classmethod
coerce(cls, version_string[, partial=False])[source]¶ Try to convert an arbitrary version string into a
Versioninstance.Rules are:
If no minor or patch component, and
partialisFalse, replace them with zeroesAny 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
buildpartAny extra
+in thebuildpart 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')
-
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://docs.npmjs.com/misc/semver.htmlMore 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
Versionagainst those clauses.Attributes
This class has no public attributes.
Methods
-
match(self, version)¶ Test whether a given
Versionmatches all includedSpecItem:>>> Spec('>=1.1.0,<1.1.2').match(Version('1.1.1')) True
- Parameters
version (
Version) – The version to test against the specs- Return type
bool
-
select(self, versions)¶ Select the highest compatible version from an iterable of
Versionobjects.>>> 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')
-
__contains__(self, version)¶ Alias of the
match()method; allows the use of theversion in speclistsyntax:>>> Version('1.1.1-alpha') in Spec('>=1.1.0,<1.1.1') True
-
__str__(self)¶ Converting a
Specreturns 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
Specas a dictionary key.
Class methods
-
classmethod
parse(self, expression, syntax='simple')¶ Retrieve a
BaseSpecobject 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_stringis invalid.- Return type
BaseSpecsubclass
Changed in version 2.7: This method used to return a tuple of
SpecItemobjects.
-
-
class
semantic_version.SimpleSpec(spec_string)[source]¶ New in version 2.7: Previously reachable through
Spec.Applies the python-semanticversion range specification:
A specification of
<1.3.4is 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
SimpleSpecsyntax 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.2will match version0.1.2and any version differing only through its build number (0.1.2+b42matches);A clause of
==0.1.2+b42will only match that specific version:0.1.2+b43and0.1.2are excluded;A clause of
==0.1.2+will only match that specific version:0.1.2+b42is excluded;A clause of
!=0.1.2will prevent all versions with the same major/minor/patch combination:0.1.2-rc.1and0.1.2+b42are excluded’A clause of
!=0.1.2-will only prevent build variations of that version:0.1.2-rc.1is included, but not0.1.2+b42;A clause of
!=0.1.2+will exclude only that exact version:0.1.2-rc.1and0.1.2+b42are included;Only a
==or!=clause may contain build-level metadata:==1.2.3+b42is valid,>=1.2.3+b42isn’t.
Comparison clauses
A clause of
<0.1.2will match versions strictly below0.1.2, excluding prereleases of0.1.2:0.1.2-rc.1is excluded;A clause of
<0.1.2-will match versions strictly below0.1.2, including prereleases of0.1.2:0.1.2-rc.1is included;A clause of
<0.1.2-rc.3will match versions strictly below0.1.2-rc.3, including prereleases:0.1.2-rc.2is included;A clause of
<=XXXwill match versions that match<XXXor==XXXA clause of
>0.1.2will match versions strictly above0.1.2, including all prereleases of0.1.3.A clause of
>0.1.2-rc.3will match versions strictly above0.1.2-rc.3, including matching prereleases of0.1.2:0.1.2-rc.10is included;A clause of
>=XXXwill match versions that match>XXXor==XXX
..rubric:: Wildcards
A clause of
==0.1.*is equivalent to>=0.1.0,<0.2.0A clause of
>=0.1.*is equivalent to>=0.1.0A clause of
==1.*or==1.*.*is equivalent to>=1.0.0,<2.0.0A clause of
>=1.*or>=1.*.*is equivalent to>=1.0.0A clause of
==*maps to>=0.0.0A clause of
>=*maps to>=0.0.0
Extensions
Additionnally, python-semanticversion supports extensions from specific packaging platforms:
PyPI-style compatible release clauses:
~=2.2means “Any release between 2.2.0 and 3.0.0”~=1.4.5means “Any release between 1.4.5 and 1.5.0”
NPM-style specs:
~1.2.3means “Any release between 1.2.3 and 1.3.0”^1.3.4means “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')]
-
class
semantic_version.NpmSpec(spec_string)[source]¶ New in version 2.7.
A NPM-compliant version matching engine, based on the https://docs.npmjs.com/misc/semver.html 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
SpectoSimpleSpecwill be removed in 3.1.Alias to
LegacySpec, for backwards compatibility.
-
class
semantic_version.LegacySpec(spec_string)¶ Deprecated since version 2.7: The
LegacySpecclass will be removed in 3.0; useSimpleSpecinstead.A
LegacySpecclass 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)>, )>
Its keeps a list of
SpecItemobjects, 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)[source]¶ 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
Versionobjects 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)[source]¶ Retrieve a
(kind, version)tuple from a string.- Parameters
requirement_string (str) – The textual description of the specification
- Raises
ValueError: if therequirement_stringis invalid.- Return type
(
kind,version) tuple
Methods
-
match(self, version)[source]¶ Test whether a given
Versionmatches 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 spec- Return type
bool
-
__str__(self)[source]¶ Converting a
SpecItemto a string returns the initial description string:>>> str(SpecItem('>=0.1.1')) '>=0.1.1'
-
__hash__(self)[source]¶ Provides a hash based solely on the current kind and the specified version.
Allows using a
SpecItemas 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
The kind of ‘Almost equal to’ specifications
-
classmethod