Package: semantic-version
IntroductionThis small python library provides a few tools to handleSemVerin Python.
It follows strictly the 2.0.0 version of the SemVer scheme.LinksPackage onPyPI:https://pypi.org/project/semantic-version/Doc onReadTheDocs:https://python-semanticversion.readthedocs.io/Source onGitHub:http://github.com/rbarrois/python-semanticversion/Build on Github Actions:https://github.com/rbarrois/python-semanticversion/actionsSemantic Version specification:SemVerGetting startedInstall the package fromPyPI, using pip:pipinstallsemantic-versionOr from GitHub:$gitclonegit://github.com/rbarrois/python-semanticversion.gitImport it in your code:importsemantic_versionThis module provides classes to handle semantic versions:Versionrepresents a version number (0.1.1-alpha+build.2012-05-15)BaseSpec-derived classes represent requirement specifications (>=0.1.1,<0.3.0):SimpleSpecdescribes a natural description syntaxNpmSpecis used for NPM-style range descriptions.VersionsDefining aVersionis quite simple:>>>importsemantic_version>>>v=semantic_version.Version('0.1.1')>>>v.major0>>>v.minor1>>>v.patch1>>>v.prerelease[]>>>v.build[]>>>list(v)[0, 1, 1, [], []]If the provided version string is invalid, aValueErrorwill be raised:>>>semantic_version.Version('0.1')Traceback (most recent call last):File"<stdin>", line1, in<module>File"/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line64, in__init__major,minor,patch,prerelease,build=self.parse(version_string,partial)File"/Users/rbarrois/dev/semantic_version/src/semantic_version/base.py", line86, inparseraiseValueError('Invalid version string:%r'%version_string)ValueError:Invalid version string: '0.1'One may also create aVersionwith named components:>>>semantic_version.Version(major=0,minor=1,patch=2)Version('0.1.2')In that case,major,minorandpatchare mandatory, and must be integers.prereleaseandbuild, 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, theVersion.coercemethod 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 versionsObviously, 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')FalseYou 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 specificationpython-semanticversion provides a couple of ways to describe a range of accepted
versions:TheSimpleSpecclass provides a simple, easily understood scheme –
somewhat inspired from PyPI range notations;TheNpmSpecclass supports the whole NPM range specification scheme:>>>Version('0.1.2')inNpmSpec('0.1.0-alpha.2 .. 0.2.4')True>>>Version('0.1.2')inNpmSpec('>=0.1.1 <0.1.3 || 2.x')True>>>Version('2.3.4')inNpmSpec('>=0.1.1 <0.1.3 || 2.x')TrueTheSimpleSpecschemeBasic 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 specFalse>>>s.match(Version('0.1.0'))FalseCombining specifications can be expressed as follows:>>>SimpleSpec('>=0.1.1,<0.3.0')Simpler test syntax is also available using theinkeyword:>>>s=SimpleSpec('==0.1.1')>>>Version('0.1.1+git7ccc72')ins# build variants are equivalent to full versionsTrue>>>Version('0.1.1-alpha1')ins# pre-release variants don't match the full version.False>>>Version('0.1.2')insFalseRefer to the full documentation athttps://python-semanticversion.readthedocs.io/en/latest/for more details on theSimpleSpecscheme.Using a specificationTheSimpleSpec.filtermethod filters an iterable ofVersion:>>>s=SimpleSpec('>=0.1.0,<0.4.0')>>>versions=(Version('0.%d.0'%i)foriinrange(6))>>>forvins.filter(versions):...printv0.1.0
0.2.0
0.3.0It 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)foriinrange(6))>>>s.select(versions)Version('0.3.0')ContributingIn order to contribute to the source code:Open an issue onGitHub:https://github.com/rbarrois/python-semanticversion/issuesFork therepositoryand submit a pull request onGitHubOr 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 onPEP 8The whole test suite must pass after adding the changesThe test coverage for a new feature must be 100%New features and methods should be documented in thereferencesection
and included in thechangelogInclude your name in thecontributorssectionNoteAll files should contain the following header:# -*- encoding: utf-8 -*-
# Copyright (c) The python-semanticversion project