Classes for parsing and dealing with semantic versions and ranges of versions
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
Parse a prerelease string into a type, number tuple
- prerelease (string): a prerelease string in the format specified for SemanticVersion
- tuple: (release_type, number)
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_requiresand 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.
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 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
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.