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 invalid
Return type:	`int`, -1 / 0 / 1 as for a `cmp()` comparison

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 the `spec` or the `version` is invalid
Return type:	`bool`

Representing a version¶

class semantic_version.Version¶

Object representation of a SemVer-compliant version.

Constructed from a textual version string:

>>> Version('1.1.1')
<SemVer(1, 1, 1, [], [])>
>>> str(Version('1.1.1'))
'1.1.1'

Attributes

partial¶: bool, whether this is a ‘partial’ or a complete version number. Partial version number may lack minor or patch version numbers.

major¶: int, the major version number

minor¶

int, the minor version number.

May be None for a partial version number in a <major> format.

patch¶

int, the patch version number.

May be None for a partial version number in a <major> or <major>.<minor> format.

prerelease¶

list of strings, the prerelease component.

It contains the various dot-separated identifiers in the prerelease component.

May be None for a partial version number in a <major>, <major>.<minor> or <major>.<minor>.<patch> format.

build¶

list of strings, the build component.

It contains the various dot-separated identifiers in the build component.

May be None for a partial version number in a <major>, <major>.<minor>, <major>.<minor>.<patch> or <major>.<minor>.<patch>-<prerelease> format.

Methods

__iter__(self)¶: Iterates over the version components (major, minor, patch, prerelease, build).

__cmp__(self, other)¶

Provides comparison methods with other Version objects.

The rules are:

For non-partial versions, compare using the SemVer scheme
If any compared object is partial, compare using the SemVer scheme, but stop at the first component undefined in the partial Version; that is, a component whose value is None.

__str__(self)¶

Returns the standard text representation of the version.

>>> v = Version('0.1.1-rc2+build4.4')
>>> v
<SemVer(0, 1, 1, ['rc2'], ['build4', '4'])>
>>> str(v)
'0.1.1-rc2+build4.4'

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 the `version_string` is invalid.
Return type:	(major, minor, patch, prerelease, build)

Version specifications¶

Version specifications describe a ‘range’ of accepted versions: older than, equal, similar to, …

class semantic_version.Spec¶

Stores a version specification, defined from a string:

>>> Spec('>=0.1.1')
<Spec: >= <SemVer(0, 1, 1, [], [])>>

This allows to test Version objects against the Spec:

>>> Spec('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release have lower precedence
False
>>> Version('0.1.1+build2') in Spec('>=0.1.1')   # build version have higher precedence
True

Attributes

kind¶: One of KIND_LT, KIND_LTE, KIND_EQUAL, KIND_GTE, KIND_GT, KIND_ALMOST.

spec¶

Version in the Spec description.

If kind is KIND_ALMOST, this will be a partial Version.

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 the `requirement_string` is invalid.
Return type:	(`kind`, `version`) tuple

Methods

match(self, version)¶

Test whether a given Version matches this Spec.

Parameters:	version (`Version`) – The version to test against the spec
Return type:	`bool`

__contains__(self, version)¶: Allows the use of the version in spec syntax. Simply an alias of the match() method.

Class attributes

KIND_LT¶: The kind of ‘Less than’ specifications

KIND_LTE¶: The kind of ‘Less or equal to’ specifications

KIND_EQUAL¶: The kind of ‘equal to’ specifications

KIND_GTE¶: The kind of ‘Greater or equal to’ specifications

KIND_GT¶: The kind of ‘Greater than’ specifications

KIND_ALMOST¶: The kind of ‘Almost equal to’ specifications