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
semantic_version.validate(version)

Check whether a version string complies with the SemVer rules.

>>> semantic_version.validate('1.1.1')
True
>>> semantic_version.validate('1.2.3a4')
False
Parameters:version (str) – The version string to validate
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:

    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)
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 is False, 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 the build 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 the version_string is invalid.
Return type:

Version

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

Note

python-semanticversion also accepts "*" as a version spec, that matches all (valid) version strings.

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