rez.vendor.version.version#

Implements a well defined versioning schema.

There are three class types - VersionToken, Version and VersionRange. A Version is a set of zero or more VersionTokens, separate by ‘.’s or ‘-‘s (eg “1.2-3”). A VersionToken is a string containing alphanumerics, and default implemenations ‘NumericToken’ and ‘AlphanumericVersionToken’ are supplied. You can implement your own if you want stricter tokens or different sorting behaviour.

A VersionRange is a set of one or more contiguous version ranges - for example, “3+<5” contains any version >=3 but less than 5. Version ranges can be used to define dependency requirements between objects. They can be OR’d together, AND’d and inverted.

The empty version ‘’, and empty version range ‘’, are also handled. The empty version is used to denote unversioned objects. The empty version range, also known as the ‘any’ range, is used to refer to any version of an object.

class rez.vendor.version.version.VersionToken#

Token within a version number.

A version token is that part of a version number that appears between a delimiter, typically ‘.’ or ‘-’. For example, the version number ‘2.3.07b’ contains the tokens ‘2’, ‘3’ and ‘07b’ respectively.

Version tokens are only allowed to contain alphanumerics (any case) and underscores.

__init__(token)#

Create a VersionToken.

Parameters:: token – Token string, eg “rc02”

classmethod create_random_token_string()#: Create a random token string. For testing purposes only.

less_than(other)#

Compare to another VersionToken.

Parameters:: other – The VersionToken object to compare against.
Returns:: True if this token is less than other, False otherwise.

next()#: Returns the next largest token.

class rez.vendor.version.version.NumericToken#

Numeric version token.

Version token supporting numbers only. Padding is ignored.

__init__(token)#

Create a VersionToken.

Parameters:: token – Token string, eg “rc02”

classmethod create_random_token_string()#: Create a random token string. For testing purposes only.

less_than(other)#

Compare to another VersionToken.

Parameters:: other – The VersionToken object to compare against.
Returns:: True if this token is less than other, False otherwise.

next()#: Returns the next largest token.

class rez.vendor.version.version.AlphanumericVersionToken#

Alphanumeric version token.

These tokens compare as follows: - each token is split into alpha and numeric groups (subtokens); - the resulting subtoken list is compared. - alpha comparison is case-sensitive, numeric comparison is padding-sensitive.

Subtokens compare as follows: - alphas come before numbers; - alphas are compared alphabetically (_, then A-Z, then a-z); - numbers are compared numerically. If numbers are equivalent but zero-

padded differently, they are then compared alphabetically. Thus “01” < “1”.

Some example comparisons that equate to true: - “3” < “4” - “01” < “1” - “beta” < “1” - “alpha3” < “alpha4” - “alpha” < “alpha3” - “gamma33” < “33gamma”

__init__(token)#

Create a VersionToken.

Parameters:: token – Token string, eg “rc02”

classmethod create_random_token_string()#: Create a random token string. For testing purposes only.

less_than(other)#

Compare to another VersionToken.

Parameters:: other – The VersionToken object to compare against.
Returns:: True if this token is less than other, False otherwise.

next()#: Returns the next largest token.

rez.vendor.version.version.reverse_sort_key(comparable)#

Key that gives reverse sort order on versions and version ranges.

Example

>>> Version("1.0") < Version("2.0")
True
>>> reverse_sort_key(Version("1.0")) < reverse_sort_key(Version("2.0"))
False

Parameters:: comparable (Version or VesionRange) – Object to wrap.
Returns:: Wrapper object that reverses comparisons.
Return type:: _ReversedComparable

class rez.vendor.version.version.Version#

Version object.

A Version is a sequence of zero or more version tokens, separated by either a dot ‘.’ or hyphen ‘-’ delimiters. Note that separators only affect Version objects cosmetically - in other words, the version ‘1.0.0’ is equivalent to ‘1-0-0’.

The empty version ‘’ is the smallest possible version, and can be used to represent an unversioned resource.

__init__(ver_str='', make_token=<class 'rez.vendor.version.version.AlphanumericVersionToken'>)#

Create a Version object.

Parameters:

ver_str – Version string.
make_token – Callable that creates a VersionToken subclass from a string.

copy()#: Returns a copy of the version.

trim(len_)#

Return a copy of the version, possibly with less tokens.

Parameters:: len (int) – New version length. If >= current length, an unchanged copy of the version is returned.

property major#: Semantic versioning major version.

property minor#: Semantic versioning minor version.

property patch#: Semantic versioning patch version.

as_tuple()#

Convert to a tuple of strings.

Example

>>> print Version("1.2.12").as_tuple()
('1', '2', '12')

class rez.vendor.version.version.VersionRange#

Version range.

A version range is a set of one or more contiguous ranges of versions. For example, “3.0 or greater, but less than 4” is a contiguous range that contains versions such as “3.0”, “3.1.0”, “3.99” etc. Version ranges behave something like sets - they can be intersected, added and subtracted, but can also be inverted. You can test to see if a Version is contained within a VersionRange.

A VersionRange “3” (for example) is the superset of any version “3[.X.X…]”. The version “3” itself is also within this range, and is smaller than “3.0” - any version with common leading tokens, but with a larger token count, is the larger version of the two.

VersionRange objects have a flexible syntax that let you describe any combination of contiguous ranges, including inclusive and exclusive upper and lower bounds. This is best explained by example (those listed on the same line are equivalent):

“3”: ‘superset’ syntax, contains “3”, “3.0”, “3.1.4” etc; “2+”, “>=2”: inclusive lower bound syntax, contains “2”, “2.1”, “5.0.0” etc; “>2”: exclusive lower bound; “<5”: exclusive upper bound; “<=5”: inclusive upper bound; “==2”: a range that contains only the exact single version “2”.

“1+<5”, “>=1<5”: inclusive lower, exclusive upper. The most common form of
a ‘bounded’ version range (ie, one with a lower and upper bound);

“>1<5”: exclusive lower, exclusive upper; “>1<=5”: exclusive lower, inclusive upper; “1+<=5”, “1..5”: inclusive lower, inclusive upper;

“<=4,>2”, “<4,>2”, “<4,>=2”: Reverse pip syntax (note comma)

To help with readability, bounded ranges can also have their bounds separated with a comma, eg “>=2,<=6”. The comma is purely cosmetic and is dropped in the string representation.

To describe more than one contiguous range, seperate ranges with the or ‘|’ symbol. For example, the version range “4|6+” contains versions such as “4”, “4.0”, “4.3.1”, “6”, “6.1”, “10.0.0”, but does not contain any version “5[.X.X…X]”. If you provide multiple ranges that overlap, they will be automatically optimised - for example, the version range “3+<6|4+<8” becomes “3+<8”.

Note that the empty string version range represents the superset of all possible versions - this is called the “any” range. The empty version can also be used as an upper or lower bound, leading to some odd but perfectly valid version range syntax. For example, “>” is a valid range - read like “>’’”, it means “any version greater than the empty version”.

__init__(range_str='', make_token=<class 'rez.vendor.version.version.AlphanumericVersionToken'>, invalid_bound_error=True)#

Create a VersionRange object.

Parameters:

range_str – Range string, such as “3”, “3+<4.5”, “2|6+”. The range will be optimised, so the string representation of this instance may not match range_str. For example, “3+<6|4+<8” == “3+<8”.
make_token – Version token class to use.
invalid_bound_error (bool) – If True, raise an exception if an impossible range is given, such as ‘3+<2’.

is_any()#: Returns True if this is the “any” range, ie the empty string range that contains all versions.

lower_bounded()#: Returns True if the range has a lower bound (that is not the empty version).

upper_bounded()#: Returns True if the range has an upper bound.

bounded()#: Returns True if the range has a lower and upper bound.

issuperset(range)#: Returns True if the VersionRange is contained within this range.

issubset(range)#: Returns True if we are contained within the version range.

union(other)#

OR together version ranges.

Calculates the union of this range with one or more other ranges.

Parameters:: other – VersionRange object (or list of) to OR with.
Returns:: New VersionRange object representing the union.

intersection(other)#

AND together version ranges.

Calculates the intersection of this range with one or more other ranges.

Parameters:: other – VersionRange object (or list of) to AND with.
Returns:: New VersionRange object representing the intersection, or None if no ranges intersect.

inverse()#

Calculate the inverse of the range.

Returns:: New VersionRange object representing the inverse of this range, or None if there is no inverse (ie, this range is the any range).

intersects(other)#

Determine if we intersect with another range.

Parameters:: other – VersionRange object.
Returns:: True if the ranges intersect, False otherwise.

split()#

Split into separate contiguous ranges.

Returns:: A list of VersionRange objects. For example, the range “3|5+” will be split into [“3”, “5+”].

classmethod as_span(lower_version=None, upper_version=None, lower_inclusive=True, upper_inclusive=True)#

Create a range from lower_version..upper_version.

Parameters:

lower_version – Version object representing lower bound of the range.
upper_version – Version object representing upper bound of the range.

Returns:

VersionRange object.

classmethod from_version(version, op=None)#

Create a range from a version.

Parameters:

version – Version object. This is used as the upper/lower bound of the range.
op – Operation as a string. One of ‘gt’/’>’, ‘gte’/’>=’, lt’/’<’, ‘lte’/’<=’, ‘eq’/’==’. If None, a bounded range will be created that contains the version superset.

Returns:

VersionRange object.

classmethod from_versions(versions)#

Create a range from a list of versions.

This method creates a range that contains only the given versions and no other. Typically the range looks like (for eg) “==3|==4|==5.1”.

Parameters:: versions – List of Version objects.
Returns:: VersionRange object.

to_versions()#: Returns exact version ranges as Version objects, or None if there are no exact version ranges present.

contains_version(version)#: Returns True if version is contained in this range.

iter_intersect_test(iterable, key=None, descending=False)#

Performs containment tests on a sorted list of versions.

This is more optimal than performing separate containment tests on a list of sorted versions.

Parameters:

iterable – An ordered sequence of versioned objects. If the list is not sorted by version, behaviour is undefined.
key (callable) – Function that returns a Version given an object from iterable. If None, the identity function is used.
descending (bool) – Set to True if iterable is in descending version order.

Returns:

An iterator that returns (bool, object) tuples, where ‘object’ is the original object in iterable, and the bool indicates whether that version is contained in this range.

iter_intersecting(iterable, key=None, descending=False)#

Like iter_intersect_test, but returns intersections only.

Returns:: An iterator that returns items from iterable that intersect.

iter_non_intersecting(iterable, key=None, descending=False)#

Like iter_intersect_test, but returns non-intersections only.

Returns:: An iterator that returns items from iterable that don’t intersect.

span()#

Return a contiguous range that is a superset of this range.

Returns:: A VersionRange object representing the span of this range. For example, the span of “2+<4|6+<8” would be “2+<8”.

visit_versions(func)#

Visit each version in the range, and apply a function to each.

This is for advanced usage only.

If func returns a Version, this call will change the versions in place.

It is possible to change versions in a way that is nonsensical - for example setting an upper bound to a smaller version than the lower bound. Use at your own risk.

Parameters:: func (callable) – Takes a Version instance arg, and is applied to every version in the range. If func returns a Version, it will replace the existing version, updating this VersionRange instance in place.