Classes for parsing and dealing with semantic versions and ranges of versions

Module Contents

class SemanticVersion(major, minor, patch, release_type='release', prerelease_number=None)

A simple class representing a version in X.Y.Z[-prerelease] format

Only a known number of prerelease types are allowed and must be in the format: <name><integer>

where name is one of: build, alpha, beta, rc and integer is a whole number greater than 0

The sort order for prereleases is defined as build < alpha < beta < rc < release


A tuple representing the compatibility class of this semantic version

Coexistence classes are defined as a tuple containing the release version with everything except the first nonzero entry being zero. Basically, coexistence classes divide version into those that should be compatible based on semantic versioning rules


Return the X.Y.Z prefix for this version


Create a new SemanticVersion with the first nonzero value incremented

If this version is 0.0.1, then this will return 0.0.2. If this version is 0.1.0 then this version will return 0.2.0.

All prerelease information is stripped so 1.0.0-alpha2 becomes 2.0.0.


Create a new SemanticVersion with the first nonzero value decremented

If the version is 0.0.2, then this will return 0.0.1. If this version is 0.2.0, then this version will return 0.1.0.

All preprelease information is stripped so 2.0.0-alphga2 becomes 1.0.0


Create a new SemanticVersion with the patch level incremented

All prerelease information is stripped. So 0.0.1-alpha2 becomes 0.0.2

classmethod ParsePrerelease(cls, prerelease)

Parse a prerelease string into a type, number tuple

prerelease (string): a prerelease string in the format specified for SemanticVersion
tuple: (release_type, number)
classmethod FromString(cls, version)

Convert this version into a python PEP 440 compliant string.

There is a 1:1 map between versions as specified in these SemanticVersion objects and what is allowed in python packages according to PEP 440. This function does that conversion and returns a pep440 compliant string.

Released versions are identical to what is returned by str(self), however, preleases have the following mapping (assuming X.Y.Z is the public release):

str: The PEP 440 compliant version string.

Convert this version to a pep440 compatible version specifier.

The goal of this method is to generate a string that can be placed into install_requires and will select all versions compatible with this one in a semantic versioning sense.

Specifically, this translates to the following string:

== X.*, >= X.Y.Z[preX]

Note that this matching process is less restrictive than the ~= X.Y.Z[preX] operator provided for in pep440. That operator is found to be overly restrictive since it does not allow for minor version bumps in the targeted version.

str: A PEP 440 compliant version specifier.
__ne__(self, other)
__eq__(self, other)
__lt__(self, other)
__gt__(self, other)
class SemanticVersionRange(disjuncts)

Class specifying a range of SemanticVersion objects

Ranges can be used to filter a list of SemanticVersion objects into only those that satisfy the range conditions. Currently, only a minimal set of range operations is supported. Range parsing and interpretation is taken from npm semver:

Currently, the only operations that are implemented in the parser is:


The preferred way to create a SemanticVersionRange is through the classmethod FromString(“<version range spec>”).

disjuncts (list): A list of lists of 4 tuples that specify the ranges to be matched
Each tuple should (lower, upper, inclusive_lower, inclusive_upper) where lower and upper and SemanticVersions (possibly None) and inclusive_* are bools that determine whether the range condition is <= upper or < upper (>= lower, > lower). Each sublist is joined conjunctively within itself and the lists themselves are joined disjunctively.
_check_ver_range(self, version, ver_range)

Check if version is included in ver_range

_check_insersection(self, version, ranges)

Check that a version is inside all of a list of ranges

check(self, version)

Check that a version is inside this SemanticVersionRange

version (SemanticVersion): The version to check
bool: True if the version is included in the range, False if not
filter(self, versions, key=lambda x: x)

Filter all of the versions in an iterable that match this version range

versions (iterable): An iterable of SemanticVersion objects
list: A list of the SemanticVersion objects that matched this range
classmethod FromString(cls, range_string)

Parse a version range string into a SemanticVersionRange

Currently, the only possible range strings are:

^X.Y.Z - matches all versions with the same leading nonzero digit
greater than or equal the given range.
    • matches everything

=X.Y.Z - matches only the exact version given

range_string (string): A string specifying the version range
SemanticVersionRange: The resulting version range object
ArgumentError: if the range string does not define a valid range.