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