Reference

Module-level functions

semantic_version.compare(v1, v2)

Compare two version strings, and return a result similar to that of cmp():

>>> compare('0.1.1', '0.1.2')
-1
>>> compare('0.1.1', '0.1.1')
0
>>> compare('0.1.1', '0.1.1-alpha')
1
Parameters:
  • v1 (str) – The first version to compare
  • v2 (str) – The second version to compare
Raises:

ValueError, if any version string is invalid

Return type:

int, -1 / 0 / 1 as for a cmp() comparison; NotImplemented if versions only differ by build metadata

Warning

Since build metadata has no ordering, compare(Version('0.1.1'), Version('0.1.1+3')) returns NotImplemented

semantic_version.match(spec, version)

Check whether a version string matches a specification string:

>>> match('>=0.1.1', '0.1.2')
True
>>> match('>=0.1.1', '0.1.1-alpha')
False
>>> match('~0.1.1', '0.1.1-alpha')
True
Parameters:
  • spec (str) – The specification to use, as a string
  • version (str) – The version string to test against the spec
Raises:

ValueError, if the spec or the version is invalid

Return type:

bool

semantic_version.validate(version)

Check whether a version string complies with the SemVer rules.

>>> semantic_version.validate('1.1.1')
True
>>> semantic_version.validate('1.2.3a4')
False
Parameters:version (str) – The version string to validate
Return type:bool

Representing a version (the Version class)

class semantic_version.Version(version_string[, partial=False])

Object representation of a SemVer-compliant version.

Constructed from a textual version string:

>>> Version('1.1.1')
Version('1.1.1')
>>> str(Version('1.1.1'))
'1.1.1'
class semantic_version.Version(major: int, minor: int, patch: int, prereleases: tuple, build: tuple[, partial=False])

Constructed from named components:

>>> Version(major=1, minor=2, patch=3)
Version('1.2.3')

Attributes

partial

bool, whether this is a ‘partial’ or a complete version number. Partial version number may lack minor or patch version numbers.

Deprecated since version 2.7: The ability to define a partial version will be removed in version 3.0. Use SimpleSpec instead: SimpleSpec('1.x.x').

major

int, the major version number

minor

int, the minor version number.

May be None for a partial version number in a <major> format.

patch

int, the patch version number.

May be None for a partial version number in a <major> or <major>.<minor> format.

prerelease

tuple of strings, the prerelease component.

It contains the various dot-separated identifiers in the prerelease component.

May be None for a partial version number in a <major>, <major>.<minor> or <major>.<minor>.<patch> format.

build

tuple of strings, the build metadata.

It contains the various dot-separated identifiers in the build metadata.

May be None for a partial version number in a <major>, <major>.<minor>, <major>.<minor>.<patch> or <major>.<minor>.<patch>-<prerelease> format.

precedence_key

Read-only attribute; suited for use in sort(versions, key=lambda v: v.precedence_key). The actual value of the attribute is considered an implementation detail; the only guarantee is that ordering versions by their precedence_key will comply with semver precedence rules.

Note that the build isn’t included in the precedence_key computatin.

Methods

next_major(self)

Return the next major version, i.e the smallest version strictly greater than the current one with minor and patch set to 0 and no prerelease/build.

>>> Version('1.0.2').next_major()
Version('2.0.0')
>>> Version('1.0.0+b3').next_major()
Version('2.0.0')
>>> Version('1.0.0-alpha').next_major()
Version('1.0.0')
next_minor(self)

Return the next minor version, i.e the smallest version strictly greater than the current one, with a patch level of 0.

>>> Version('1.0.2').next_minor()
Version('1.1.0')
>>> Version('1.0.0+b3').next_minor()
Version('1.1.0')
>>> Version('1.1.2-alpha').next_minor()
Version('1.2.0')
>>> Version('1.1.0-alpha').next_minor()
Version('1.1.0')
next_patch(self):

Return the next patch version, i.e the smallest version strictly greater than the current one with empty prerelease and build.

>>> Version('1.0.2').next_patch()
Version('1.0.3')
>>> Version('1.0.2+b3').next_patch()
Version('1.0.3')
>>> Version('1.0.2-alpha').next_patch()
Version('1.0.2')

Warning

The next patch version of a version with a non-empty prerelease is the version without that prerelease component: it’s the smallest “pure” patch version strictly greater than that version.

truncate(self, level='patch']):

Returns a similar level, but truncated at the provided level.

>>> Version('1.0.2-rc1+b43.24').truncate()
Version('1.0.2')
>>> Version('1.0.2-rc1+b43.24').truncate('minor')
Version('1.0.0')
>>> Version('1.0.2-rc1+b43.24').truncate('prerelease')
Version('1.0.2-rc1')
__iter__(self)

Iterates over the version components (major, minor, patch, prerelease, build):

>>> list(Version('0.1.1'))
[0, 1, 1, [], []]

Note

This may pose some subtle bugs when iterating over a single version while expecting an iterable of versions – similar to:

>>> list('abc')
['a', 'b', 'c']
>>> list(('abc',))
['abc']
__cmp__(self, other)

Provides comparison methods with other Version objects.

The rules are:

  • For non-partial versions, compare using the SemVer scheme

  • If any compared object is partial:

    For instance, Version('1.0', partial=True) means “any version beginning in 1.0”.

    Version('1.0.1-alpha', partial=True) means “The 1.0.1-alpha version or any any release differing only in build metadata”: 1.0.1-alpha+build3 matches, 1.0.1-alpha.2 doesn’t.

Examples:

>>> Version('1.0', partial=True) == Version('1.0.1')
True
>>> Version('1.0.1-rc1.1') == Version('1.0.1-rc1', partial=True)
False
>>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1')
False
>>> Version('1.0.1-rc1+build345') == Version('1.0.1-rc1', partial=True)
True
__str__(self)

Returns the standard text representation of the version:

>>> v = Version('0.1.1-rc2+build4.4')
>>> v
Version('0.1.1-rc2+build4.4')
>>> str(v)
'0.1.1-rc2+build4.4'
__hash__(self)

Provides a hash based solely on the components.

Allows using a Version as a dictionary key.

Note

A fully qualified partial Version

(up to the build component) will hash the same as the equally qualified, non-partial Version:

>>> hash(Version('1.0.1+build4')) == hash(Version('1.0.1+build4', partial=True))
True

Class methods

classmethod parse(cls, version_string[, partial=False])

Parse a version string into a (major, minor, patch, prerelease, build) tuple.

Parameters:
  • version_string (str) – The version string to parse
  • partial (bool) – Whether this should be considered a partial version
Raises:

ValueError, if the version_string is invalid.

Return type:

(major, minor, patch, prerelease, build)

classmethod coerce(cls, version_string[, partial=False])

Try to convert an arbitrary version string into a Version instance.

Rules are:

  • If no minor or patch component, and partial is False, replace them with zeroes
  • Any character outside of a-zA-Z0-9.+- is replaced with a -
  • If more than 3 dot-separated numerical components, everything from the fourth component belongs to the build part
  • Any extra + in the build part will be replaced with dots

Examples:

>>> Version.coerce('02')
Version('2.0.0')
>>> Version.coerce('1.2.3.4')
Version('1.2.3+4')
>>> Version.coerce('1.2.3.4beta2')
Version('1.2.3+4beta2')
>>> Version.coerce('1.2.3.4.5_6/7+8+9+10')
Version('1.2.3+4.5-6-7.8.9.10')
Parameters:
  • version_string (str) – The version string to coerce
  • partial (bool) – Whether to allow generating a partial version
Raises:

ValueError, if the version_string is invalid.

Return type:

Version

Version specifications (the Spec class)

The SemVer specification doesn’t provide a standard description of version ranges. And simply using a naive implementation leads to unexpected situations: >=1.2.0,<1.3.0 isn’t expected to match version 1.3.0-rc.1, yet a strict application of SemVer precedence rules would include it.

In order to solve this problem, each SemVer-based package management platform has designed its own rules. python-semanticversion provides a couple of implementations of those range definition syntaxes:

Each of those Spec classes provides a shared set of methods to work with versions:

class semantic_version.BaseSpec(spec_string)

Converts an expression describing a range of versions into a set of clauses, and matches any Version against those clauses.

Attributes

This class has no public attributes.

Methods

match(self, version)

Test whether a given Version matches all included SpecItem:

>>> Spec('>=1.1.0,<1.1.2').match(Version('1.1.1'))
True
Parameters:version (Version) – The version to test against the specs
Return type:bool
filter(self, versions)

Extract all compatible versions from an iterable of Version objects.

Parameters:versions (iterable of Version) – The versions to filter
Yield:Version
select(self, versions)

Select the highest compatible version from an iterable of Version objects.

>>> s = Spec('>=0.1.0')
>>> s.select([])
None
>>> s.select([Version('0.1.0'), Version('0.1.3'), Version('0.1.1')])
Version('0.1.3')
Parameters:versions (iterable of Version) – The versions to filter
Return type:The highest compatible Version if at least one of the given versions is compatible; None otherwise.
__contains__(self, version)

Alias of the match() method; allows the use of the version in speclist syntax:

>>> Version('1.1.1-alpha') in Spec('>=1.1.0,<1.1.1')
True
__str__(self)

Converting a Spec returns the initial description string:

>>> str(Spec('>=0.1.1,!=0.1.2'))
'>=0.1.1,!=0.1.2'
__hash__(self)

Provides a hash based solely on the hash of contained specs.

Allows using a Spec as a dictionary key.

Class methods

classmethod parse(self, expression, syntax='simple')

Retrieve a BaseSpec object tuple from a string.

Parameters:
  • requirement_string (str) – The textual description of the specifications
  • syntax (str) – The identifier of the syntax to use for parsing
Raises:

ValueError: if the requirement_string is invalid.

Return type:

BaseSpec subclass

Changed in version 2.7: This method used to return a tuple of SpecItem objects.

class semantic_version.SimpleSpec(spec_string)

New in version 2.7: Previously reachable through Spec.

Applies the python-semanticversion range specification:

  • A specification of <1.3.4 is not expected to allow 1.3.4-rc2, but strict SemVer comparisons allow it ;
  • It may be necessary to exclude either all variations on a patch-level release (!=1.3.3) or specifically one build-level release (1.3.3+build.434).

Specification structure:

In order to have version specification behave naturally, the SimpleSpec syntax uses the following rules:

  • A specification expression is a list of clauses separated by a comma (,);
  • A version is matched by an expression if, and only if, it matches every clause in the expression;
  • A clause of * matches every valid version;

Equality clauses

  • A clause of ==0.1.2 will match version 0.1.2 and any version differing only through its build number (0.1.2+b42 matches);
  • A clause of ==0.1.2+b42 will only match that specific version: 0.1.2+b43 and 0.1.2 are excluded;
  • A clause of ==0.1.2+ will only match that specific version: 0.1.2+b42 is excluded;
  • A clause of !=0.1.2 will prevent all versions with the same major/minor/patch combination: 0.1.2-rc.1 and 0.1.2+b42 are excluded’
  • A clause of !=0.1.2- will only prevent build variations of that version: 0.1.2-rc.1 is included, but not 0.1.2+b42;
  • A clause of !=0.1.2+ will exclude only that exact version: 0.1.2-rc.1 and 0.1.2+b42 are included;
  • Only a == or != clause may contain build-level metadata: ==1.2.3+b42 is valid, >=1.2.3+b42 isn’t.

Comparison clauses

  • A clause of <0.1.2 will match versions strictly below 0.1.2, excluding prereleases of 0.1.2: 0.1.2-rc.1 is excluded;
  • A clause of <0.1.2- will match versions strictly below 0.1.2, including prereleases of 0.1.2: 0.1.2-rc.1 is included;
  • A clause of <0.1.2-rc.3 will match versions strictly below 0.1.2-rc.3, including prereleases: 0.1.2-rc.2 is included;
  • A clause of <=XXX will match versions that match <XXX or ==XXX
  • A clause of >0.1.2 will match versions strictly above 0.1.2, including all prereleases of 0.1.3.
  • A clause of >0.1.2-rc.3 will match versions strictly above 0.1.2-rc.3, including matching prereleases of 0.1.2: 0.1.2-rc.10 is included;
  • A clause of >=XXX will match versions that match >XXX or ==XXX

..rubric:: Wildcards

  • A clause of ==0.1.* is equivalent to >=0.1.0,<0.2.0
  • A clause of >=0.1.* is equivalent to >=0.1.0
  • A clause of ==1.* or ==1.*.* is equivalent to >=1.0.0,<2.0.0
  • A clause of >=1.* or >=1.*.* is equivalent to >=1.0.0
  • A clause of ==* maps to >=0.0.0
  • A clause of >=* maps to >=0.0.0

Extensions

Additionnally, python-semanticversion supports extensions from specific packaging platforms:

PyPI-style compatible release clauses:

  • ~=2.2 means “Any release between 2.2.0 and 3.0.0”
  • ~=1.4.5 means “Any release between 1.4.5 and 1.5.0”

NPM-style specs:

  • ~1.2.3 means “Any release between 1.2.3 and 1.3.0”
  • ^1.3.4 means “Any release between 1.3.4 and 2.0.0”

Some examples:

>>> Version('0.1.2-rc.1') in SimpleSpec('*')
True
>>> SimpleSpec('<0.1.2').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')])
[Version('0.1.1')]
>>> SimpleSpec('<0.1.2-').filter([Version('0.1.2-rc.1'), Version('0.1.1'), Version('0.1.2+b42')])
[Version('0.1.2-rc.1'), Version('0.1.1')]
>>> SimpleSpec('>=0.1.2,!=0.1.3,!=0.1.4-rc.1',!=0.1.5+b42).filter([
        Version('0.1.2'), Version('0.1.3'), Version('0.1.3-beta'),
        Version('0.1.4'), Version('0.1.5'), Version('0.1.5+b42'),
        Version('2.0.1-rc.1'),
    ])
[Version('0.1.2'), Version('0.1.4'), Version('0.1.5'), Version('2.0.1-rc.1')]
class semantic_version.NpmSpec(spec_string)

New in version 2.7.

A NPM-compliant version matching engine, based on the https://docs.npmjs.com/misc/semver.html specification.

>>> 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
class semantic_version.Spec(spec_string)

Deprecated since version 2.7: The alias from Spec to SimpleSpec will be removed in 3.1.

Alias to LegacySpec, for backwards compatibility.

class semantic_version.LegacySpec(spec_string)

Deprecated since version 2.7: The LegacySpec class will be removed in 3.0; use SimpleSpec instead.

A LegacySpec class has the exact same behaviour as SimpleSpec, with backwards-compatible features:

It accepts version specifications passed in as separated arguments:

>>> Spec('>=1.0.0', '<1.2.0', '!=1.1.4,!=1.1.13')
<Spec: (
    <SpecItem: >= Version('1.0.0', partial=True)>,
    <SpecItem: < Version('1.2.0', partial=True)>,
    <SpecItem: != Version('1.1.4', partial=True)>,
    <SpecItem: != Version('1.1.13', partial=True)>,
)>

Its keeps a list of SpecItem objects, based on the initial expression components.

__iter__(self)

Returns an iterator over the contained specs:

>>> for spec in Spec('>=0.1.1,!=0.1.2'):
...     print spec
>=0.1.1
!=0.1.2

Attributes

specs

Tuple of SpecItem, the included specifications.

class semantic_version.SpecItem(spec_string)

Deprecated since version 2.7: This class will be removed in 3.0.

Note

This class belong to the private python-semanticversion API.

Stores a version specification, defined from a string:

>>> SpecItem('>=0.1.1')
<SpecItem: >= Version('0.1.1', partial=True)>

This allows to test Version objects against the SpecItem:

>>> SpecItem('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release satisfy conditions
True
>>> Version('0.1.1+build2') in SpecItem('>=0.1.1')   # build metadata is ignored when checking for precedence
True
>>>
>>> # Use the '-' marker to include the pre-release component in checks
>>> SpecItem('>=0.1.1-').match(Version('0.1.1-rc1')
False
>>> # Use the '+' marker to include the build metadata in checks
>>> SpecItem('==0.1.1+').match(Version('0.1.1+b1234')
False
>>>

Attributes

kind

One of KIND_LT, KIND_LTE, KIND_EQUAL, KIND_GTE, KIND_GT and KIND_NEQ.

spec

Version in the SpecItem description.

It is alway a partial Version.

Class methods

classmethod parse(cls, requirement_string)

Retrieve a (kind, version) tuple from a string.

Parameters:requirement_string (str) – The textual description of the specification
Raises:ValueError: if the requirement_string is invalid.
Return type:(kind, version) tuple

Methods

match(self, version)

Test whether a given Version matches this SpecItem:

>>> SpecItem('>=0.1.1').match(Version('0.1.1-alpha'))
True
>>> SpecItem('>=0.1.1-').match(Version('0.1.1-alpha'))
False
Parameters:version (Version) – The version to test against the spec
Return type:bool
__str__(self)

Converting a SpecItem to a string returns the initial description string:

>>> str(SpecItem('>=0.1.1'))
'>=0.1.1'
__hash__(self)

Provides a hash based solely on the current kind and the specified version.

Allows using a SpecItem as a dictionary key.

Class attributes

KIND_LT

The kind of ‘Less than’ specifications:

>>> Version('1.0.0-alpha') in Spec('<1.0.0')
False
KIND_LTE

The kind of ‘Less or equal to’ specifications:

>>> Version('1.0.0-alpha1+build999') in Spec('<=1.0.0-alpha1')
True
KIND_EQUAL

The kind of ‘equal to’ specifications:

>>> Version('1.0.0+build3.3') in Spec('==1.0.0')
True
KIND_GTE

The kind of ‘Greater or equal to’ specifications:

>>> Version('1.0.0') in Spec('>=1.0.0')
True
KIND_GT

The kind of ‘Greater than’ specifications:

>>> Version('1.0.0+build667') in Spec('>1.0.1')
False
KIND_NEQ

The kind of ‘Not equal to’ specifications:

>>> Version('1.0.1') in Spec('!=1.0.1')
False

The kind of ‘Almost equal to’ specifications