A library implementing the 'SemVer' scheme.
Project description
python-semanticversion
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: http://pypi.python.org/pypi/semantic_version/
- Doc on ReadTheDocs: https://python-semanticversion.readthedocs.io/
- Source on GitHub: http://github.com/rbarrois/python-semanticversion/
- Build on Travis CI: http://travis-ci.org/rbarrois/python-semanticversion/
- 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 syntax
- NpmSpec 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'
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'
It is also possible to check whether a given string is a proper semantic version string:
>>> semantic_version.validate('0.1.3') True >>> semantic_version.validate('0a2') False
Finally, one may create a Version with named components instead:
>>> 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 patch, 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')
Requirement specification
The SimpleSpec object describes a range of accepted versions:
>>> 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
Simpler test syntax is also available using the in keyword:
>>> s = SimpleSpec('==0.1.1') >>> Version('0.1.1-alpha1') in s True >>> Version('0.1.2') in s False
Combining specifications can be expressed as follows:
>>> SimpleSpec('>=0.1.1,<0.3.0')
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')
Coercing an arbitrary version string
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')
Including pre-release identifiers in specifications
When testing a Version against a SimpleSpec, comparisons are adjusted for common user expectations; thus, a pre-release version (1.0.0-alpha) will not satisfy the ==1.0.0 SimpleSpec.
Pre-release identifiers will only be compared if included in the BaseSpec definition or (for the empty pre-release number) if a single dash is appended (1.0.0-):
>>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0') # No pre-release identifier False >>> Version('0.1.0-alpha') in SimpleSpec('<0.1.0-') # Include pre-release in checks True
Including build metadata in specifications
Build metadata has no ordering; thus, the only meaningful comparison including build metadata is equality.
>>> Version('1.0.0+build2') in SimpleSpec('<=1.0.0') # Build metadata ignored True >>> Version('1.0.0+build1') in SimpleSpec('==1.0.0+build2') # Include build in checks False
NPM-based ranges
The NpmSpec class handles NPM-style ranges:
>>> Version('1.2.3') in NpmSpec('1.2.2 - 1.4') True >>> Version('1.2.3') in NpmSpec('<1.x || >=1.2.3') True
Refer to https://docs.npmjs.com/misc/semver.html for a detailed description of NPM range syntax.
Using with Django
The semantic_version.django_fields module provides django fields to store Version or BaseSpec objects.
More documentation is available in the django section.
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 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 the changelog
- 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
maxdepth: 2 reference django changelog credits
Indices and tables
- genindex
- modindex
- search
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for semantic_version-2.8.5-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 45e4b32ee9d6d70ba5f440ec8cc5221074c7f4b0e8918bdab748cc37912440a9 |
|
MD5 | dca7f8559b469b50a283180155b8381a |
|
BLAKE2-256 | a51500ef3b7888a10363b7c402350eda3acf395ff05bebae312d1296e528516a |