deb-python-semantic-version/doc/reference.rst

Reference

semantic_version

Module-level functions

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

param str v1

The first version to compare

param str v2

The second version to compare

raises

ValueError, if any version string is invalid

rtype

int, -1 / 0 / 1 as for a cmp comparison

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

param str spec

The specification to use, as a string

param str version

The version string to test against the spec

raises

ValueError, if the spec or the version is invalid

rtype

bool

Representing a version

Object representation of a SemVer-compliant version.

Constructed from a textual version string:

>>> Version('1.1.1')
<SemVer(1, 1, 1, [], [])>
>>> str(Version('1.1.1'))
'1.1.1'

Attributes

partial

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

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

list 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

list of strings, the build component.

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

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

Methods

__iter__(self)

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

__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, compare using the SemVer scheme, but stop at the first component undefined in the partial Version; that is, a component whose value is None.

__str__(self)

Returns the standard text representation of the version.

>>> v = Version('0.1.1-rc2+build4.4')
>>> v
<SemVer(0, 1, 1, ['rc2'], ['build4', '4'])>
>>> str(v)
'0.1.1-rc2+build4.4'

Class methods

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

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

param str version_string

The version string to parse

param bool partial

Whether this should be considered a partial version

raises

ValueError, if the version_string is invalid.

rtype

(major, minor, patch, prerelease, build)

Version specifications

Version specifications describe a 'range' of accepted versions: older than, equal, similar to, …

Stores a version specification, defined from a string:

>>> Spec('>=0.1.1')
<Spec: >= <SemVer(0, 1, 1, [], [])>>

This allows to test Version objects against the Spec:

>>> Spec('>=0.1.1').match(Version('0.1.1-rc1'))  # pre-release have lower precedence
False
>>> Version('0.1.1+build2') in Spec('>=0.1.1')   # build version have higher precedence
True

Attributes

kind

One of KIND_LT, KIND_LTE, KIND_EQUAL, KIND_GTE, KIND_GT, KIND_ALMOST.

spec

Version in the Spec description.

If kind is KIND_ALMOST, this will be a ~Version.partial Version.

Class methods

parse(cls, requirement_string)

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

param str requirement_string

The textual description of the specification

raises

ValueError: if the requirement_string is invalid.

rtype

(kind, version) tuple

Methods

match(self, version)

Test whether a given Version matches this Spec.

param version

The version to test against the spec

type version

Version

rtype

bool

__contains__(self, version)

Allows the use of the version in spec syntax. Simply an alias of the match method.

Class attributes

KIND_LT

The kind of 'Less than' specifications

KIND_LTE

The kind of 'Less or equal to' specifications

KIND_EQUAL

The kind of 'equal to' specifications

KIND_GTE

The kind of 'Greater or equal to' specifications

KIND_GT

The kind of 'Greater than' specifications

KIND_ALMOST

The kind of 'Almost equal to' specifications