semantic-version

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.

https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml/badge.svg

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'

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

Release files for semantic-version 2.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for semantic-version 2.10.0
File	Size	Uploaded
semantic_version-2.10.0.tar.gz	52.3 kB	May 26, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for semantic-version 2.10.0
File	Interpreter	ABI	Platform	Reset
semantic_version-2.10.0-py2.py3-none-any.whl 15.6 kB May 26, 2022	Python 2, Python 3	none	any	Details

Total release size: 67.8 kB

Release files / semantic_version-2.10.0.tar.gz

Download URL	semantic_version-2.10.0.tar.gz
Size	52.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`bdabb6d336998cbb378d4b9db3a4b56a1e3235701dc05ea2690d9a997ed5041c`
BLAKE2b-256 checksum How to use checksums	`7d31f2289ce78b9b473d582568c234e104d2a342fd658cc288a7553d83bb8595`
Upload date	May 26, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.0.0 requests-toolbelt/0.9.1 tqdm/4.58.0 CPython/3.8.13`

Release files / semantic_version-2.10.0-py2.py3-none-any.whl

Download URL	semantic_version-2.10.0-py2.py3-none-any.whl
Size	15.6 kB
Tags	Python 2 Python 3
SHA-256 checksum How to use checksums	`de78a3b8e0feda74cabc54aab2da702113e33ac9d9eb9d2389bcf1f58b7d9177`
BLAKE2b-256 checksum How to use checksums	`6a238146aad7d88f4fcb3a6218f41a60f6c2d4e3a72de72da1825dc7c8f7877c`
Upload date	May 26, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/54.0.0 requests-toolbelt/0.9.1 tqdm/4.58.0 CPython/3.8.13`