This small python library provides a few tools to handle SemVer in Python.
It follows strictly the 2.0.0-rc1 version of the SemVer scheme.
Intall the package from PyPI, using pip:
pip install python-semanticversion
Import it in your code:
import semantic_version
This module provides two classes to handle semantic versions:
Defining a Version is quite simple:
>>> import semantic_version
>>> v = semantic_version.Version('0.1.1')
>>> v.major
0
>>> v.minor
1
>>> v.patch
1
>>> v.prerelease
[]
>>> v.build
[]
>>> list(v)
[0, 1, 1, [], []]
If the provided version string is invalid, a ValueError will be raised:
>>> semantic_version.Version('0.1')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 64, in __init__
major, minor, patch, prerelease, build = self.parse(version_string, partial)
File "/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line 86, in parse
raise ValueError('Invalid version string: %r' % version_string)
ValueError: Invalid version string: '0.1'
In order to define “relaxed” version strings, you must pass in partial=True:
>>> v = semantic_version.Version('0.1', partial=True)
>>> list(v)
[0, 1, None, None, None]
Obviously, Versions can be compared:
>>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2')
True
>>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha')
True
>>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha')
False
The Spec object describes a range of accepted versions:
>>> s = Spec('>=0.1.1') # At least 0.1.1
>>> s.match(Version('0.1.1'))
True
>>> s.match(Version('0.1.1-alpha1')) # pre-release satisfy version spec
True
>>> s.match(Version('0.1.0'))
False
Simpler test syntax is also available using the in keyword:
>>> s = Spec('==0.1.1')
>>> Version('0.1.1-alpha1') in s
True
>>> Version('0.1.2') in s
False
Combining specifications can be expressed in two ways:
Components separated by commas in a single string:
>>> Spec('>=0.1.1,<0.3.0')
Components given as different arguments:
>>> Spec('>=0.1.1', '<0.3.0')
A mix of both versions:
>>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0')
The Spec.filter() method filters an iterable of Version:
>>> s = Spec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))
>>> for v in s.filter(versions):
... print v
0.1.0
0.2.0
0.3.0
It is also possible to select the ‘best’ version from such iterables:
>>> s = Spec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))
>>> s.select(versions)
Version('0.3.0')
When testing a Version against a Spec, comparisons are only performed for components defined in the Spec; thus, a pre-release version (1.0.0-alpha), while not strictly equal to the non pre-release version (1.0.0), satisfies the ==1.0.0 Spec.
Pre-release identifiers will only be compared if included in the Spec definition or (for the empty pre-release number) if a single dash is appended (1.0.0-):
>>> Version('0.1.0-alpha') in Spec('>=0.1.0') # No pre-release identifier
True
>>> Version('0.1.0-alpha') in Spec('>=0.1.0-') # Include pre-release in checks
False
The same rule applies for the build identifier: comparisons will include it only if it was included in the Spec definition, or - for the unnumbered build version - if a single + is appended to the definition(1.0.0+, 1.0.0-alpha+):
>>> Version('1.0.0+build2') in Spec('<=1.0.0') # Build identifier ignored
True
>>> Version('1.0.0+build2') in Spec('<=1.0.0+') # Include build in checks
False
The semantic_version.django_fields module provides django fields to store Version or Spec objects.
More documentation is available in the Interaction with Django section.
In order to contribute to the source code:
When submitting patches or pull requests, you should respect the following rules:
Note
‘raw’ patches / pull requests will be accepted too, but will require more cooperative work to bring them to the expected standard.