semantic-version

A library implementing the 'SemVer' scheme.

These details have not been verified by PyPI

Project links

Homepage

Project description

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

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

This version

2.10.0

May 26, 2022

2.9.0

Feb 6, 2022

2.8.5

Apr 29, 2020

2.8.4

Dec 21, 2019

2.8.3

Nov 21, 2019

2.8.2

Sep 6, 2019

2.8.1

Aug 29, 2019

2.8.0

Aug 29, 2019

2.7.1

Aug 28, 2019

2.7.0

Aug 28, 2019

2.6.0

Sep 25, 2016

2.5.0

Feb 12, 2016

2.4.2

Jul 2, 2015

2.4.1

Mar 31, 2015

2.4.0

Mar 31, 2015

2.3.1

Sep 23, 2014

2.3.0

Mar 16, 2014

2.2.2

Dec 23, 2013

2.2.1

Oct 29, 2013

2.2.0

Mar 22, 2013

2.1.2

May 22, 2012

2.1.1

May 22, 2012

2.1.0

May 22, 2012

2.0.0

May 21, 2012

1.2.0

May 17, 2012

1.0.0

May 17, 2012

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

semantic_version-2.10.0.tar.gz (52.3 kB view details)

Uploaded May 26, 2022 Source

Built Distribution

semantic_version-2.10.0-py2.py3-none-any.whl (15.6 kB view details)

Uploaded May 26, 2022 Python 2 Python 3

File details

Details for the file semantic_version-2.10.0.tar.gz.

File metadata

Download URL: semantic_version-2.10.0.tar.gz
Upload date: May 26, 2022
Size: 52.3 kB
Tags: Source
Uploaded using 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

File hashes

Hashes for semantic_version-2.10.0.tar.gz
Algorithm	Hash digest
SHA256	`bdabb6d336998cbb378d4b9db3a4b56a1e3235701dc05ea2690d9a997ed5041c`
MD5	`e48abef93ba69abcd4eaf4640edfc38b`
BLAKE2b-256	`7d31f2289ce78b9b473d582568c234e104d2a342fd658cc288a7553d83bb8595`

See more details on using hashes here.

File details

Details for the file semantic_version-2.10.0-py2.py3-none-any.whl.

File metadata

Download URL: semantic_version-2.10.0-py2.py3-none-any.whl
Upload date: May 26, 2022
Size: 15.6 kB
Tags: Python 2, Python 3
Uploaded using 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

File hashes

Hashes for semantic_version-2.10.0-py2.py3-none-any.whl
Algorithm	Hash digest
SHA256	`de78a3b8e0feda74cabc54aab2da702113e33ac9d9eb9d2389bcf1f58b7d9177`
MD5	`5447b980c8f1463ccb8ac20f99d5eb46`
BLAKE2b-256	`6a238146aad7d88f4fcb3a6218f41a60f6c2d4e3a72de72da1825dc7c8f7877c`