Python Semanticversion Save

Semantic version comparison for Python (see

Project README


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.

.. image:: :target:

.. image:: :target: :alt: Latest Version

.. image:: :target: :alt: Supported Python versions

.. image:: :target: :alt: Wheel status

.. image:: :target: :alt: License

Getting started

Install the package from PyPI_, using pip:

.. code-block:: sh

pip install semantic-version

Or from GitHub:

.. code-block:: sh

$ git clone git://

Import it in your code:

.. code-block:: python

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.


Defining a Version is quite simple:

.. code-block:: pycon

>>> import semantic_version
>>> v = semantic_version.Version('0.1.1')
>>> v.major
>>> v.minor
>>> v.patch
>>> v.prerelease
>>> list(v)
[0, 1, 1, [], []]

If the provided version string is invalid, a ValueError will be raised:

.. code-block:: pycon

>>> 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/", line 64, in __init__
    major, minor, patch, prerelease, build = self.parse(version_string, partial)
  File "/Users/rbarrois/dev/semantic_version/src/semantic_version/", 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:

.. code-block:: pycon

>>> semantic_version.Version(major=0, minor=1, patch=2)

In that case, major, minor and patch are mandatory, and must be integers. prerelease and build, if provided, must be tuples of strings:

.. code-block:: pycon

>>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('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:

.. code-block:: pycon

>>> Version.coerce('0')
>>> Version.coerce('')
>>> Version.coerce('0.1.2a3')

Working with versions """""""""""""""""""""

Obviously, versions can be compared:

.. code-block:: pycon

>>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2')
>>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha')
>>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha')

You can also get a new version that represents a bump in one of the version levels:

.. code-block:: pycon

>>> v = semantic_version.Version('0.1.1+build')
>>> new_v = v.next_major()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1+build')
>>> new_v = v.next_minor()
>>> str(new_v)
>>> v = semantic_version.Version('1.1.1+build')
>>> new_v = v.next_patch()
>>> str(new_v)

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:

    .. code-block:: pycon

    >>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4')
    >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')
    >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')

The SimpleSpec scheme """""""""""""""""""""""""

Basic usage is simply a comparator and a base version:

.. code-block:: pycon

>>> s = SimpleSpec('>=0.1.1')  # At least 0.1.1
>>> s.match(Version('0.1.1'))
>>> s.match(Version('0.1.1-alpha1'))  # pre-release doesn't satisfy version spec
>>> s.match(Version('0.1.0'))

Combining specifications can be expressed as follows:

.. code-block:: pycon

  >>> SimpleSpec('>=0.1.1,<0.3.0')

Simpler test syntax is also available using the in keyword:

.. code-block:: pycon

>>> s = SimpleSpec('==0.1.1')
>>> Version('0.1.1+git7ccc72') in s  # build variants are equivalent to full versions
>>> Version('0.1.1-alpha1') in s     # pre-release variants don't match the full version.
>>> Version('0.1.2') in s

Refer to the full documentation at for more details on the SimpleSpec scheme.

Using a specification """""""""""""""""""""

The SimpleSpec.filter method filters an iterable of Version:

.. code-block:: pycon

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

It is also possible to select the 'best' version from such iterables:

.. code-block:: pycon

>>> s = SimpleSpec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))


In order to contribute to the source code:

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

.. _SemVer: .. _PyPI:

Open Source Agenda is not affiliated with "Python Semanticversion" Project. README Source: rbarrois/python-semanticversion
Open Issues
Last Commit
1 month ago

Open Source Agenda Badge

Open Source Agenda Rating