semantic-version


Namesemantic-version JSON
Version 2.10.0 PyPI version JSON
download
home_pagehttps://github.com/rbarrois/python-semanticversion
SummaryA library implementing the 'SemVer' scheme.
upload_time2022-05-26 13:35:23
maintainer
docs_urlhttps://pythonhosted.org/semantic-version/
authorRaphaël Barrois
requires_python>=2.7
licenseBSD
keywords semantic version versioning version
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            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 specification scheme:

  .. code-block:: pycon

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

.. code-block:: pycon

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

  .. 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
    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``:

.. 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
    0.1.0
    0.2.0
    0.3.0

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))
    >>> 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 <https://github.com/rbarrois/python-semanticversion>`_
  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

.. _SemVer: http://semver.org/
.. _PyPI: http://pypi.python.org/



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/rbarrois/python-semanticversion",
    "name": "semantic-version",
    "maintainer": "",
    "docs_url": "https://pythonhosted.org/semantic-version/",
    "requires_python": ">=2.7",
    "maintainer_email": "",
    "keywords": "semantic version,versioning,version",
    "author": "Rapha\u00ebl Barrois",
    "author_email": "raphael.barrois+semver@polytechnique.org",
    "download_url": "https://files.pythonhosted.org/packages/7d/31/f2289ce78b9b473d582568c234e104d2a342fd658cc288a7553d83bb8595/semantic_version-2.10.0.tar.gz",
    "platform": null,
    "description": "Introduction\n============\n\nThis small python library provides a few tools to handle `SemVer`_ in Python.\nIt follows strictly the 2.0.0 version of the SemVer scheme.\n\n.. image:: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml/badge.svg\n    :target: https://github.com/rbarrois/python-semanticversion/actions/workflows/test.yml\n\n.. image:: https://img.shields.io/pypi/v/semantic_version.svg\n    :target: https://python-semanticversion.readthedocs.io/en/latest/changelog.html\n    :alt: Latest Version\n\n.. image:: https://img.shields.io/pypi/pyversions/semantic_version.svg\n    :target: https://pypi.python.org/pypi/semantic_version/\n    :alt: Supported Python versions\n\n.. image:: https://img.shields.io/pypi/wheel/semantic_version.svg\n    :target: https://pypi.python.org/pypi/semantic_version/\n    :alt: Wheel status\n\n.. image:: https://img.shields.io/pypi/l/semantic_version.svg\n    :target: https://pypi.python.org/pypi/semantic_version/\n    :alt: License\n\nLinks\n-----\n\n- Package on `PyPI`_: https://pypi.org/project/semantic-version/\n- Doc on `ReadTheDocs <http://readthedocs.org/>`_: https://python-semanticversion.readthedocs.io/\n- Source on `GitHub <http://github.com/>`_: http://github.com/rbarrois/python-semanticversion/\n- Build on Github Actions: https://github.com/rbarrois/python-semanticversion/actions\n- Semantic Version specification: `SemVer`_\n\n\nGetting started\n===============\n\nInstall the package from `PyPI`_, using pip:\n\n.. code-block:: sh\n\n    pip install semantic-version\n\nOr from GitHub:\n\n.. code-block:: sh\n\n    $ git clone git://github.com/rbarrois/python-semanticversion.git\n\n\nImport it in your code:\n\n\n.. code-block:: python\n\n    import semantic_version\n\n\nThis module provides classes to handle semantic versions:\n\n- ``Version`` represents a version number (``0.1.1-alpha+build.2012-05-15``)\n- ``BaseSpec``-derived classes represent requirement specifications (``>=0.1.1,<0.3.0``):\n\n  - ``SimpleSpec`` describes a natural description syntax\n  - ``NpmSpec`` is used for NPM-style range descriptions.\n\nVersions\n--------\n\nDefining a ``Version`` is quite simple:\n\n\n.. code-block:: pycon\n\n    >>> import semantic_version\n    >>> v = semantic_version.Version('0.1.1')\n    >>> v.major\n    0\n    >>> v.minor\n    1\n    >>> v.patch\n    1\n    >>> v.prerelease\n    []\n    >>> v.build\n    []\n    >>> list(v)\n    [0, 1, 1, [], []]\n\nIf the provided version string is invalid, a ``ValueError`` will be raised:\n\n.. code-block:: pycon\n\n    >>> semantic_version.Version('0.1')\n    Traceback (most recent call last):\n      File \"<stdin>\", line 1, in <module>\n      File \"/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py\", line 64, in __init__\n        major, minor, patch, prerelease, build = self.parse(version_string, partial)\n      File \"/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py\", line 86, in parse\n        raise ValueError('Invalid version string: %r' % version_string)\n    ValueError: Invalid version string: '0.1'\n\n\nOne may also create a ``Version`` with named components:\n\n.. code-block:: pycon\n\n    >>> semantic_version.Version(major=0, minor=1, patch=2)\n    Version('0.1.2')\n\nIn that case, ``major``, ``minor`` and ``patch`` are mandatory, and must be integers.\n``prerelease`` and ``build``, if provided, must be tuples of strings:\n\n.. code-block:: pycon\n\n    >>> semantic_version.Version(major=0, minor=1, patch=2, prerelease=('alpha', '2'))\n    Version('0.1.2-alpha.2')\n\n\nSome user-supplied input might not match the semantic version scheme.\nFor such cases, the ``Version.coerce`` method will try to convert any\nversion-like string into a valid semver version:\n\n.. code-block:: pycon\n\n    >>> Version.coerce('0')\n    Version('0.0.0')\n    >>> Version.coerce('0.1.2.3.4')\n    Version('0.1.2+3.4')\n    >>> Version.coerce('0.1.2a3')\n    Version('0.1.2-a3')\n\nWorking with versions\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nObviously, versions can be compared:\n\n\n.. code-block:: pycon\n\n    >>> semantic_version.Version('0.1.1') < semantic_version.Version('0.1.2')\n    True\n    >>> semantic_version.Version('0.1.1') > semantic_version.Version('0.1.1-alpha')\n    True\n    >>> semantic_version.Version('0.1.1') <= semantic_version.Version('0.1.1-alpha')\n    False\n\nYou can also get a new version that represents a bump in one of the version levels:\n\n.. code-block:: pycon\n\n    >>> v = semantic_version.Version('0.1.1+build')\n    >>> new_v = v.next_major()\n    >>> str(new_v)\n    '1.0.0'\n    >>> v = semantic_version.Version('1.1.1+build')\n    >>> new_v = v.next_minor()\n    >>> str(new_v)\n    '1.2.0'\n    >>> v = semantic_version.Version('1.1.1+build')\n    >>> new_v = v.next_patch()\n    >>> str(new_v)\n    '1.1.2'\n\n\n\nRequirement specification\n-------------------------\n\npython-semanticversion provides a couple of ways to describe a range of accepted\nversions:\n\n- The ``SimpleSpec`` class provides a simple, easily understood scheme --\n  somewhat inspired from PyPI range notations;\n- The ``NpmSpec`` class supports the whole NPM range specification scheme:\n\n  .. code-block:: pycon\n\n      >>> Version('0.1.2') in NpmSpec('0.1.0-alpha.2 .. 0.2.4')\n      True\n      >>> Version('0.1.2') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')\n      True\n      >>> Version('2.3.4') in NpmSpec('>=0.1.1 <0.1.3 || 2.x')\n      True\n\nThe ``SimpleSpec`` scheme\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nBasic usage is simply a comparator and a base version:\n\n.. code-block:: pycon\n\n    >>> s = SimpleSpec('>=0.1.1')  # At least 0.1.1\n    >>> s.match(Version('0.1.1'))\n    True\n    >>> s.match(Version('0.1.1-alpha1'))  # pre-release doesn't satisfy version spec\n    False\n    >>> s.match(Version('0.1.0'))\n    False\n\nCombining specifications can be expressed as follows:\n\n  .. code-block:: pycon\n\n      >>> SimpleSpec('>=0.1.1,<0.3.0')\n\nSimpler test syntax is also available using the ``in`` keyword:\n\n.. code-block:: pycon\n\n    >>> s = SimpleSpec('==0.1.1')\n    >>> Version('0.1.1+git7ccc72') in s  # build variants are equivalent to full versions\n    True\n    >>> Version('0.1.1-alpha1') in s     # pre-release variants don't match the full version.\n    False\n    >>> Version('0.1.2') in s\n    False\n\n\nRefer to the full documentation at\nhttps://python-semanticversion.readthedocs.io/en/latest/ for more details on the\n``SimpleSpec`` scheme.\n\n\n\nUsing a specification\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nThe ``SimpleSpec.filter`` method filters an iterable of ``Version``:\n\n.. code-block:: pycon\n\n    >>> s = SimpleSpec('>=0.1.0,<0.4.0')\n    >>> versions = (Version('0.%d.0' % i) for i in range(6))\n    >>> for v in s.filter(versions):\n    ...     print v\n    0.1.0\n    0.2.0\n    0.3.0\n\nIt is also possible to select the 'best' version from such iterables:\n\n\n.. code-block:: pycon\n\n    >>> s = SimpleSpec('>=0.1.0,<0.4.0')\n    >>> versions = (Version('0.%d.0' % i) for i in range(6))\n    >>> s.select(versions)\n    Version('0.3.0')\n\n\n\nContributing\n============\n\nIn order to contribute to the source code:\n\n- Open an issue on `GitHub`_: https://github.com/rbarrois/python-semanticversion/issues\n- Fork the `repository <https://github.com/rbarrois/python-semanticversion>`_\n  and submit a pull request on `GitHub`_\n- Or send me a patch (mailto:raphael.barrois+semver@polytechnique.org)\n\nWhen submitting patches or pull requests, you should respect the following rules:\n\n- Coding conventions are based on :pep:`8`\n- The whole test suite must pass after adding the changes\n- The test coverage for a new feature must be 100%\n- New features and methods should be documented in the ``reference`` section\n  and included in the ``changelog``\n- Include your name in the ``contributors`` section\n\n.. note:: All files should contain the following header::\n\n          # -*- encoding: utf-8 -*-\n          # Copyright (c) The python-semanticversion project\n\n.. _SemVer: http://semver.org/\n.. _PyPI: http://pypi.python.org/\n\n\n",
    "bugtrack_url": null,
    "license": "BSD",
    "summary": "A library implementing the 'SemVer' scheme.",
    "version": "2.10.0",
    "project_urls": {
        "Homepage": "https://github.com/rbarrois/python-semanticversion"
    },
    "split_keywords": [
        "semantic version",
        "versioning",
        "version"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "6a238146aad7d88f4fcb3a6218f41a60f6c2d4e3a72de72da1825dc7c8f7877c",
                "md5": "5447b980c8f1463ccb8ac20f99d5eb46",
                "sha256": "de78a3b8e0feda74cabc54aab2da702113e33ac9d9eb9d2389bcf1f58b7d9177"
            },
            "downloads": -1,
            "filename": "semantic_version-2.10.0-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "5447b980c8f1463ccb8ac20f99d5eb46",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": ">=2.7",
            "size": 15552,
            "upload_time": "2022-05-26T13:35:21",
            "upload_time_iso_8601": "2022-05-26T13:35:21.206388Z",
            "url": "https://files.pythonhosted.org/packages/6a/23/8146aad7d88f4fcb3a6218f41a60f6c2d4e3a72de72da1825dc7c8f7877c/semantic_version-2.10.0-py2.py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "7d31f2289ce78b9b473d582568c234e104d2a342fd658cc288a7553d83bb8595",
                "md5": "e48abef93ba69abcd4eaf4640edfc38b",
                "sha256": "bdabb6d336998cbb378d4b9db3a4b56a1e3235701dc05ea2690d9a997ed5041c"
            },
            "downloads": -1,
            "filename": "semantic_version-2.10.0.tar.gz",
            "has_sig": false,
            "md5_digest": "e48abef93ba69abcd4eaf4640edfc38b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=2.7",
            "size": 52289,
            "upload_time": "2022-05-26T13:35:23",
            "upload_time_iso_8601": "2022-05-26T13:35:23.454764Z",
            "url": "https://files.pythonhosted.org/packages/7d/31/f2289ce78b9b473d582568c234e104d2a342fd658cc288a7553d83bb8595/semantic_version-2.10.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-05-26 13:35:23",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "rbarrois",
    "github_project": "python-semanticversion",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "tox": true,
    "lcname": "semantic-version"
}
        
Elapsed time: 0.28040s