python-semanticversion
======================
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://secure.travis-ci.org/rbarrois/python-semanticversion.png?branch=master
:target: http://travis-ci.org/rbarrois/python-semanticversion/
.. 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`_: http://pypi.python.org/pypi/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 `Travis CI <http://travis-ci.org/>`_: http://travis-ci.org/rbarrois/python-semanticversion/
- 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 two classes to handle semantic versions:
- ``Version`` represents a version number (``0.1.1-alpha+build.2012-05-15``)
- ``Spec`` represents a requirement specification (``>=0.1.1,<0.3.0``)
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'
In order to define "relaxed" version strings, you must pass in ``partial=True``:
.. code-block:: pycon
>>> v = semantic_version.Version('0.1', partial=True)
>>> list(v)
[0, 1, None, None, None]
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-pre+build')
>>> new_v = v.next_major()
>>> str(new_v)
'1.0.0'
>>> v = semantic_version.Version('1.1.1-pre+build')
>>> new_v = v.next_minor()
>>> str(new_v)
'1.2.0'
>>> v = semantic_version.Version('1.1.1-pre+build')
>>> new_v = v.next_patch()
>>> str(new_v)
'1.1.2'
It is also possible to check whether a given string is a proper semantic version string:
.. code-block:: pycon
>>> semantic_version.validate('0.1.3')
True
>>> semantic_version.validate('0a2')
False
Requirement specification
-------------------------
The ``Spec`` object describes a range of accepted versions:
.. code-block:: pycon
>>> s = Spec('>=0.1.1') # At least 0.1.1
>>> s.match(Version('0.1.1'))
True
>>> s.match(Version('0.1.1-alpha1')) # pre-release satisfy version spec
True
>>> s.match(Version('0.1.0'))
False
Simpler test syntax is also available using the ``in`` keyword:
.. code-block:: pycon
>>> s = Spec('==0.1.1')
>>> Version('0.1.1-alpha1') in s
True
>>> Version('0.1.2') in s
False
Combining specifications can be expressed in two ways:
- Components separated by commas in a single string:
.. code-block:: pycon
>>> Spec('>=0.1.1,<0.3.0')
- Components given as different arguments:
.. code-block:: pycon
>>> Spec('>=0.1.1', '<0.3.0')
- A mix of both versions:
.. code-block:: pycon
>>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0')
Using a specification
"""""""""""""""""""""
The ``Spec.filter`` method filters an iterable of ``Version``:
.. code-block:: pycon
>>> s = Spec('>=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 = Spec('>=0.1.0,<0.4.0')
>>> versions = (Version('0.%d.0' % i) for i in range(6))
>>> s.select(versions)
Version('0.3.0')
Coercing an arbitrary version string
""""""""""""""""""""""""""""""""""""
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')
Including pre-release identifiers in specifications
"""""""""""""""""""""""""""""""""""""""""""""""""""
When testing a ``Version`` against a ``Spec``, comparisons are only
performed for components defined in the ``Spec``; thus, a pre-release
version (``1.0.0-alpha``), while not strictly equal to the non pre-release
version (``1.0.0``), satisfies the ``==1.0.0`` ``Spec``.
Pre-release identifiers will only be compared if included in the ``Spec``
definition or (for the empty pre-release number) if a single dash is appended
(``1.0.0-``):
.. code-block:: pycon
>>> Version('0.1.0-alpha') in Spec('>=0.1.0') # No pre-release identifier
True
>>> Version('0.1.0-alpha') in Spec('>=0.1.0-') # Include pre-release in checks
False
Including build metadata in specifications
""""""""""""""""""""""""""""""""""""""""""
Build metadata has no ordering; thus, the only meaningful comparison including
build metadata is equality.
.. code-block:: pycon
>>> Version('1.0.0+build2') in Spec('<=1.0.0') # Build metadata ignored
True
>>> Version('1.0.0+build2') in Spec('==1.0.0+build2') # Include build in checks
False
Using with Django
=================
The ``semantic_version.django_fields`` module provides django fields to
store ``Version`` or ``Spec`` objects.
More documentation is available in the ``django`` section.
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 ``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
Contents
========
:maxdepth: 2
reference
django
changelog
credits
.. _SemVer: http://semver.org/
.. _PyPI: http://pypi.python.org/
Indices and tables
==================
* ``genindex``
* ``modindex``
* ``search``
Raw data
{
"_id": null,
"home_page": "https://github.com/rbarrois/python-semanticversion",
"name": "semantic-version-splunk-patch-test",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "semantic version, versioning, version",
"author": "Rapha\u00ebl Barrois",
"author_email": "raphael.barrois+semver@polytechnique.org",
"download_url": "https://files.pythonhosted.org/packages/8c/c8/f47d1ef804a9fc7e4c7c04432987ce83b15bb430c9a7dfab33b346d48b9f/semantic_version_splunk_patch_test-2.6.0.tar.gz",
"platform": null,
"description": "python-semanticversion\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://secure.travis-ci.org/rbarrois/python-semanticversion.png?branch=master\n :target: http://travis-ci.org/rbarrois/python-semanticversion/\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`_: http://pypi.python.org/pypi/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 `Travis CI <http://travis-ci.org/>`_: http://travis-ci.org/rbarrois/python-semanticversion/\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\n\nThis module provides two classes to handle semantic versions:\n\n- ``Version`` represents a version number (``0.1.1-alpha+build.2012-05-15``)\n- ``Spec`` represents a requirement specification (``>=0.1.1,<0.3.0``)\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\nIn order to define \"relaxed\" version strings, you must pass in ``partial=True``:\n\n.. code-block:: pycon\n\n >>> v = semantic_version.Version('0.1', partial=True)\n >>> list(v)\n [0, 1, None, None, None]\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-pre+build')\n >>> new_v = v.next_major()\n >>> str(new_v)\n '1.0.0'\n >>> v = semantic_version.Version('1.1.1-pre+build')\n >>> new_v = v.next_minor()\n >>> str(new_v)\n '1.2.0'\n >>> v = semantic_version.Version('1.1.1-pre+build')\n >>> new_v = v.next_patch()\n >>> str(new_v)\n '1.1.2'\n\nIt is also possible to check whether a given string is a proper semantic version string:\n\n\n.. code-block:: pycon\n\n >>> semantic_version.validate('0.1.3')\n True\n >>> semantic_version.validate('0a2')\n False\n\n\nRequirement specification\n-------------------------\n\nThe ``Spec`` object describes a range of accepted versions:\n\n\n.. code-block:: pycon\n\n >>> s = Spec('>=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 satisfy version spec\n True\n >>> s.match(Version('0.1.0'))\n False\n\nSimpler test syntax is also available using the ``in`` keyword:\n\n.. code-block:: pycon\n\n >>> s = Spec('==0.1.1')\n >>> Version('0.1.1-alpha1') in s\n True\n >>> Version('0.1.2') in s\n False\n\n\nCombining specifications can be expressed in two ways:\n\n- Components separated by commas in a single string:\n\n .. code-block:: pycon\n\n >>> Spec('>=0.1.1,<0.3.0')\n\n- Components given as different arguments:\n\n .. code-block:: pycon\n\n >>> Spec('>=0.1.1', '<0.3.0')\n\n- A mix of both versions:\n\n .. code-block:: pycon\n\n >>> Spec('>=0.1.1', '!=0.2.4-alpha,<0.3.0')\n\n\nUsing a specification\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nThe ``Spec.filter`` method filters an iterable of ``Version``:\n\n.. code-block:: pycon\n\n >>> s = Spec('>=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 = Spec('>=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\nCoercing an arbitrary version string\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\n\nIncluding pre-release identifiers in specifications\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nWhen testing a ``Version`` against a ``Spec``, comparisons are only\nperformed for components defined in the ``Spec``; thus, a pre-release\nversion (``1.0.0-alpha``), while not strictly equal to the non pre-release\nversion (``1.0.0``), satisfies the ``==1.0.0`` ``Spec``.\n\nPre-release identifiers will only be compared if included in the ``Spec``\ndefinition or (for the empty pre-release number) if a single dash is appended\n(``1.0.0-``):\n\n\n.. code-block:: pycon\n\n >>> Version('0.1.0-alpha') in Spec('>=0.1.0') # No pre-release identifier\n True\n >>> Version('0.1.0-alpha') in Spec('>=0.1.0-') # Include pre-release in checks\n False\n\n\nIncluding build metadata in specifications\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\n\nBuild metadata has no ordering; thus, the only meaningful comparison including\nbuild metadata is equality.\n\n\n.. code-block:: pycon\n\n >>> Version('1.0.0+build2') in Spec('<=1.0.0') # Build metadata ignored\n True\n >>> Version('1.0.0+build2') in Spec('==1.0.0+build2') # Include build in checks\n False\n\n\nUsing with Django\n=================\n\nThe ``semantic_version.django_fields`` module provides django fields to\nstore ``Version`` or ``Spec`` objects.\n\nMore documentation is available in the ``django`` section.\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 ``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\nContents\n========\n\n :maxdepth: 2\n\n reference\n django\n changelog\n credits\n\n\n.. _SemVer: http://semver.org/\n.. _PyPI: http://pypi.python.org/\n\nIndices and tables\n==================\n\n* ``genindex``\n* ``modindex``\n* ``search``\n\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "A library implementing the 'SemVer' scheme.",
"version": "2.6.0",
"project_urls": {
"Download": "http://pypi.python.org/pypi/semantic_version/",
"Homepage": "https://github.com/rbarrois/python-semanticversion"
},
"split_keywords": [
"semantic version",
" versioning",
" version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0affb2c636efdd62120e658afa0597bb3af7ea8ca17f9a58f8103c022fa9e53c",
"md5": "5089c0b5874f407f0c59bf0dcce3605f",
"sha256": "669796347b6a9d936cb98d2cb4af92c9c767ad3f8148da66b4cca1c86a8c1d0d"
},
"downloads": -1,
"filename": "semantic_version_splunk_patch_test-2.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5089c0b5874f407f0c59bf0dcce3605f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 11734,
"upload_time": "2024-12-02T23:10:45",
"upload_time_iso_8601": "2024-12-02T23:10:45.857081Z",
"url": "https://files.pythonhosted.org/packages/0a/ff/b2c636efdd62120e658afa0597bb3af7ea8ca17f9a58f8103c022fa9e53c/semantic_version_splunk_patch_test-2.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8cc8f47d1ef804a9fc7e4c7c04432987ce83b15bb430c9a7dfab33b346d48b9f",
"md5": "db558ccd1522cd5e3c01a30f7c79d100",
"sha256": "0861590365491511587f24b35a37beeabf4f8a1786f8cfc68a91e40029f3ed08"
},
"downloads": -1,
"filename": "semantic_version_splunk_patch_test-2.6.0.tar.gz",
"has_sig": false,
"md5_digest": "db558ccd1522cd5e3c01a30f7c79d100",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 22755,
"upload_time": "2024-12-02T23:10:47",
"upload_time_iso_8601": "2024-12-02T23:10:47.781743Z",
"url": "https://files.pythonhosted.org/packages/8c/c8/f47d1ef804a9fc7e4c7c04432987ce83b15bb430c9a7dfab33b346d48b9f/semantic_version_splunk_patch_test-2.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-02 23:10:47",
"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-splunk-patch-test"
}
JSON
