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"
}
JSON
