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. .. image:: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml/badge.svg :target: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml .. image:: https://img.shields.io/pypi/v/semantic_version.svg :target: https://python-semanticversion.readthedocs.io/en/latest/changelog.html :alt: Latest Version .. image:: https://img.shields.io/pypi/pyversions/semantic_version.svg :target: https://pypi.python.org/pypi/semantic_version/ :alt: Supported Python versions .. image:: https://img.shields.io/pypi/wheel/semantic_version.svg :target: https://pypi.python.org/pypi/semantic_version/ :alt: Wheel status .. image:: https://img.shields.io/pypi/l/semantic_version.svg :target: https://pypi.python.org/pypi/semantic_version/ :alt: License Links ----- - Package on `PyPI`_: https://pypi.org/project/semantic-version/ - Doc on `ReadTheDocs <http://readthedocs.org/>`_: https://python-semanticversion.readthedocs.io/ - Source on `GitHub <http://github.com/>`_: 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: .. code-block:: sh pip install semantic-version Or from GitHub: .. code-block:: sh $ git clone git://github.com/rbarrois/python-semanticversion.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. Versions -------- Defining a ``Version`` is quite simple: .. code-block:: pycon >>> 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: .. 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/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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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: .. code-block:: pycon >>> 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 spe