python-semanticversion¶
Introduction¶
This small python library provides a few tools to handle SemVer in Python. It follows strictly the 2.0.0 version of the SemVer scheme.
Links¶
- Package on PyPI: https://pypi.org/project/semantic-version/
- Doc on ReadTheDocs: https://python-semanticversion.readthedocs.io/
- Source on GitHub: http://github.com/rbarrois/python-semanticversion/
- Build on Github Actions: https://github.com/rbarrois/python-semanticversion/actions
- Semantic Version specification: SemVer
Getting started¶
Install the package from PyPI, using pip:
pip install semantic-version
Or from GitHub:
$ git clone git://github.com/rbarrois/python-semanticversion.git
Import it in your code:
import semantic_version
This module provides classes to handle semantic versions:
Version
represents a version number (0.1.1-alpha+build.2012-05-15
)BaseSpec
-derived classes represent requirement specifications (>=0.1.1,<0.3.0
):SimpleSpec
describes a natural description syntaxNpmSpec
is used for NPM-style range descriptions.
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'
One may also create a Version
with named components:
>>> semantic_version.Version(major=0, minor=1, patch=2)
Version('0.1.2')
In that case, major
, minor
and patch
are mandatory, and must be integers.
prerelease
and build
, if provided, must be tuples of strings:
>>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2'))
Version('0.1.2-alpha.2')
Some user-supplied input might not match the semantic version scheme.
For such cases, the Version.coerce
method will try to convert any
version-like string into a valid semver version:
>>> Version.coerce('0')
Version('0.0.0')
>>> Version.coerce('0.1.2.3.4')
Version('0.1.2+3.4')
>>> Version.coerce('0.1.2a3')
Version('0.1.2-a3')
Working with versions¶
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
You can also get a new version that represents a bump in one of the version levels:
>>> v = semantic_version.Version('0.1.1+build')
>>> new_v = v.next_major()
>>> str(new_v)
'1.0.0'
>>> v = semantic_version.Version('1.1.1+build')
>>> new_v = v.next_minor()
>>> str(new_v)
'1.2.0'
>>> v = semantic_version.Version('1.1.1+build')
>>> new_v = v.next_patch()
>>> str(new_v)
'1.1.2'
Requirement specification¶
python-semanticversion provides a couple of ways to describe a range of accepted versions:
The
SimpleSpec
class provides a simple, easily understood scheme – somewhat inspired from PyPI range notations;The
NpmSpec
class supports the whole NPM range specification scheme:>>> 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
The SimpleSpec
scheme¶
Basic usage is simply a comparator and a base version:
>>> s = SimpleSpec('>=0.1.1') # At least 0.1.1
>>> s.match(Version('0.1.1'))
True
>>> s.match(Version('0.1.1-alpha1')) # pre-release doesn't satisfy version spec
False
>>> s.match(Version('0.1.0'))
False
Combining specifications can be expressed as follows:
>>> SimpleSpec('>=0.1.1,<0.3.0')
Simpler test syntax is also available using the in
keyword:
>>> s = SimpleSpec('==0.1.1')
>>> Version('0.1.1+git7ccc72') in s # build variants are equivalent to full versions
True
>>> Version('0.1.1-alpha1') in s # pre-release variants don't match the full version.
False
>>> Version('0.1.2') in s
False
Refer to the full documentation at
https://python-semanticversion.readthedocs.io/en/latest/ for more details on the
SimpleSpec
scheme.
Using a specification¶
The SimpleSpec.filter
method filters an iterable of Version
:
>>> s = SimpleSpec('>=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 = SimpleSpec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))
>>> s.select(versions)
Version('0.3.0')
Contributing¶
In order to contribute to the source code:
- Open an issue on GitHub: https://github.com/rbarrois/python-semanticversion/issues
- Fork the repository and submit a pull request on GitHub
- Or send me a patch (mailto:raphael.barrois+semver@polytechnique.org)
When submitting patches or pull requests, you should respect the following rules:
- Coding conventions are based on PEP 8
- The whole test suite must pass after adding the changes
- The test coverage for a new feature must be 100%
- New features and methods should be documented in the
reference
section and included in thechangelog
- Include your name in the
contributors
section
Note
All files should contain the following header:
# -*- encoding: utf-8 -*-
# Copyright (c) The python-semanticversion project
Contents¶
- Introduction
- Getting started
- Contributing
- Guide
- Reference
- Interaction with Django
- ChangeLog
- 2.10.1 (unreleased)
- 2.10.0 (2022-05-26)
- 2.9.0 (2022-02-06)
- 2.8.5 (2020-04-29)
- 2.8.4 (2019-12-21)
- 2.8.3 (2019-11-21)
- 2.8.2 (2019-09-06)
- 2.8.1 (2019-08-29)
- 2.8.0 (2019-08-29)
- 2.7.1 (2019-08-28)
- 2.7.0 (2019-08-28)
- 2.6.0 (2016-09-25)
- 2.5.0 (2016-02-12)
- 2.4.2 (2015-07-02)
- 2.4.1 (2015-04-01)
- 2.4.0 (2015-04-01)
- 2.3.1 (2014-09-24)
- 2.3.0 (2014-03-16)
- 2.2.2 (2013-12-23)
- 2.2.1 (2013-10-29)
- 2.2.0 (2013-03-22)
- 2.1.2 (2012-05-22)
- 2.1.1 (2012-05-22)
- 2.1.0 (2012-05-22)
- 2.0.0 (2012-05-22)
- 1.2.0 (2012-05-18)
- 1.1.0 (2012-05-18)
- 1.0.0 (2012-05-17)
- Credits