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 (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'

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¶

tuple 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¶

tuple 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):

>>> 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:

For non-partial versions, compare using the SemVer scheme
If any compared object is partial:
- Begin comparison using the SemVer scheme
- If a component (minor, patch, prerelease or build) was absent from the partial Version – represented with None –, consider both versions equal.
For instance, Version('1.0', partial=True) means “any version beginning in 1.0”.

Version('1.0.1-alpha', partial=True) means “The 1.0.1-alpha version or any ulterior build of that same version”: 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.

Note

A fully qualified partial Version

(up to the build component) will hash the same as the equally qualified, non-partial Version:

>>> hash(Version('1.0.1+build4')) == hash(Version('1.0.1+build4', partial=True))
True

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 (the Spec class)¶

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

The main issue with representing version specifications is that the usual syntax does not map well onto SemVer precedence rules:

A specification of <1.3.4 is not expected to allow 1.3.4-rc2, but strict SemVer comparisons allow it ;
Converting the previous specification to <=1.3.3 in order to avoid 1.3.4 prereleases has the issue of excluding 1.3.3+build3 ;
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).

In order to have version specification behave naturally, the rules are the following:

If no pre-release number was included in the specification, pre-release numbers are ignored when deciding whether a version satisfies a specification.
If no build number was included in the specification, build numbers are ignored when deciding whether a version satisfies a specification.

This means that:

>>> Version('1.1.1-rc1') in Spec('<1.1.1')
False
>>> Version('1.1.1-rc1') in Spec('<1.1.1-rc4')
True
>>> Version('1.1.1-rc1+build4') in Spec('<=1.1.1-rc1')
True
>>> Version('1.1.1-rc1+build4') in Spec('<=1.1.1-rc1+build2')
False

In order to force matches to strictly compare version numbers, these additional rules apply:

Setting a pre-release separator without a pre-release identifier (<=1.1.1-) forces match to take into account pre-release version:
```
>>> Version('1.1.1-rc1') in Spec('<1.1.1')
False
>>> Version('1.1.1-rc1') in Spec('<1.1.1-')
True
```
Setting a build separator without a build identifier (>1.1.1+) forces satisfaction tests to include both prerelease and build identifiers:
```
>>> Version('1.1.1+build2') in Spec('>1.1.1')
False
>>> Version('1.1.1+build2') in Spec('>1.1.1+')
True
```

class semantic_version.Spec(spec_string[, spec_string[, ...]])¶

Stores a list of SpecItem and matches any Version against all contained specs.

It is build from a comma-separated list of version specifications:

>>> Spec('>=1.0.0,<1.2.0,!=1.1.4')
<Spec: (
    <SpecItem: >= Version('1.0.0', partial=True)>,
    <SpecItem: < Version('1.2.0', partial=True)>,
    <SpecItem: != Version('1.1.4', partial=True)>
)>

Version specifications may also be passed in 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)>,
)>

Attributes

specs¶: Tuple of SpecItem, the included specifications.

Methods

match(self, version)¶

Test whether a given Version matches all included SpecItem:

>>> 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`

filter(self, versions)¶

Extract all compatible versions from an iterable of Version objects.

Parameters:	versions (iterable of `Version`) – The versions to filter
Yield :	`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 filter
Return 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 the version 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'

__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

__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, specs_string)¶

Retrieve a (*specs) tuple from a string.

Parameters:	requirement_string (str) – The textual description of the specifications
Raises :	`ValueError`: if the `requirement_string` is invalid.
Return type:	`(*spec)` tuple

class semantic_version.SpecItem(spec_string)¶

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 the SpecItem:

>>> 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 version satisfy specifications
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 identifier in checks
>>> SpecItem('<=0.1.1-alpha+').match(Version('0.1.1-alpha+build1'))
False

Attributes

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

spec¶

Version in the SpecItem description.

It is alway 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 SpecItem:

>>> 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)¶

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

The kind of ‘Almost equal to’ specifications

Reference¶

Module-level functions¶

Representing a version (the Version class)¶

Version specifications (the Spec class)¶

Table Of Contents

Previous topic

Next topic

This Page

Navigation

Reference¶

Module-level functions¶

Representing a version (the Version class)¶

Version specifications (the Spec class)¶

Table Of Contents

Previous topic

Next topic

This Page

Quick search

Navigation