Skip to content

Version#

Version #

This class implements an order relation between version strings. Version strings can contain the usual alphanumeric characters (A-Za-z0-9), separated into segments by dots and underscores. Empty segments (i.e. two consecutive dots, a leading/trailing underscore) are not permitted. An optional epoch number - an integer followed by '!' - can precede the actual version string (this is useful to indicate a change in the versioning scheme itself). Version comparison is case-insensitive.

epoch: Optional[str] property #

Gets the epoch of the version or None if the epoch was not defined.

Examples#
>>> v = Version('2!1.0')
>>> v.epoch
2
>>>

has_local: bool property #

Returns true if this version has a local segment defined. The local part of a version is the part behind the (optional) +.

Examples#
>>> v = Version('1.0+3.2-alpha0')
>>> v.has_local
True
>>> v2 = Version('1.0')
>>> v2.has_local
False
>>>

is_dev: bool property #

Returns true if the version contains a component name "dev", dev versions are sorted before non-dev version.

Examples#
>>> v = Version('1.0.1dev')
>>> v.is_dev
True
>>> v_non_dev = Version('1.0.1')
>>> v_non_dev >= v
True
>>>

segment_count: int property #

Returns the number of segments in the version. This does not include epoch or local segment of the version

Examples#
>>> v = Version('2!1.2.3')
>>> v.segment_count
3
>>>

__eq__(other) #

Returns True if this instance represents the same version as other.

Examples#
>>> Version("1.2.3") == Version("1.2.3")
True
>>> Version("3.2.1") == Version("1.2.3")
False
>>> Version("1") == Version("1.0.0")
True
>>>

__ge__(other) #

Returns True if this instance should be ordered after or at the same location as other.

Examples#
>>> Version("1.2.3") >= Version("1.2.3")
True
>>> Version("1.2.4") >= Version("1.2.3")
True
>>> Version("1.2.3.1") >= Version("1.2.3")
True
>>> Version("3.2.1") >= Version("1.2.3")
True
>>> Version("1.2.3") >= Version("3.2.1")
False
>>> Version("1") >= Version("1.0.0")
True
>>>

__gt__(other) #

Returns True if this instance should be ordered after other.

Examples#
>>> Version("1.2.3") > Version("1.2.3")
False
>>> Version("1.2.4") > Version("1.2.3")
True
>>> Version("1.2.3.1") > Version("1.2.3")
True
>>> Version("3.2.1") > Version("1.2.3")
True
>>> Version("1") > Version("1.0.0")
False
>>>

__hash__() #

Computes the hash of this instance.

Examples#
>>> hash(Version("1.2.3")) == hash(Version("1.2.3"))
True
>>> hash(Version("1.2.3")) == hash(Version("3.2.1"))
False
>>> hash(Version("1")) == hash(Version("1.0.0"))
True
>>>

__le__(other) #

Returns True if this instance should be ordered before or at the same location as other.

Examples#
>>> Version("1.2.3") <= Version("1.2.3")
True
>>> Version("1.2.3") <= Version("1.2.4")
True
>>> Version("1.2.3") <= Version("1.2.3.1")
True
>>> Version("3.2.1") <= Version("1.2.3")
False
>>> Version("1") <= Version("1.0.0")
True
>>>

__lt__(other) #

Returns True if this instance should be ordered before other.

Examples#
>>> Version("1.2.3") < Version("1.2.3")
False
>>> Version("1.2.3") < Version("1.2.4")
True
>>> Version("1.2.3") < Version("1.2.3.1")
True
>>> Version("3.2.1") < Version("1.2.3")
False
>>> Version("1") < Version("1.0.0")
False
>>>

__ne__(other) #

Returns False if this instance represents the same version as other.

Examples#
>>> Version("1.2.3") != Version("1.2.3")
False
>>> Version("3.2.1") != Version("1.2.3")
True
>>> Version("1") != Version("1.0.0")
False
>>>

__repr__() #

Returns a representation of the version

Examples#
>>> Version("1.2.3")
Version("1.2.3")
>>>

__str__() #

Returns the string representation of the version

Examples#
>>> str(Version("1.2.3"))
'1.2.3'
>>>

as_major_minor() #

Returns the major and minor segments from the version. Requires a minimum of 2 segments in version to be split into major and minor, returns None otherwise.

Examples#
>>> v = Version('1.0')
>>> v.as_major_minor()
(1, 0)
>>>

bump_last() #

Returns a new version where the last segment of this version has been bumped.

Examples#
>>> v = Version('1.0')
>>> v.bump_last()
Version("1.1")
>>>

bump_major() #

Returns a new version where the major segment of this version has been bumped.

Examples#
>>> v = Version('1.0')
>>> v.bump_major()
Version("2.0")
>>> v = Version('9d')
>>> v.bump_major()
Version("10a")
>>>

bump_minor() #

Returns a new version where the minor segment of this version has been bumped.

Examples#
>>> v = Version('1.0')
>>> v.bump_minor()
Version("1.1")
>>>
>>> Version("1").bump_minor()
Version("1.1")
>>>

bump_patch() #

Returns a new version where the patch segment of this version has been bumped.

Examples#
>>> v = Version('1.0.5')
>>> v.bump_patch()
Version("1.0.6")
>>> v = Version('1.1.1e')
>>> v.bump_patch()
Version("1.1.2a")
>>>
>>> Version("1.5").bump_patch()
Version("1.5.1")
>>>

bump_segment(index) #

Returns a new version where the last segment of this version has been bumped.

Examples#
>>> v = Version('1.0')
>>> v.bump_segment(index=1)
Version("1.1")
>>>
>>> Version("1.5").bump_segment(-5) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
exceptions.VersionBumpException
>>> Version("1.5").bump_segment(5)
Version("1.5.0.0.0.1")
>>>

compatible_with(other) #

Checks if this version is compatible with other version. Minor versions changes are compatible with older versions, major version changes are breaking and will not be compatible.

Examples#
>>> v1 = Version('1.0')
>>> v2 = Version('1.2')
>>> v_major = Version('2.0')
>>> v1.compatible_with(v2)
False
>>> v2.compatible_with(v1)
True
>>> v_major.compatible_with(v2)
False
>>> v2.compatible_with(v_major)
False
>>>

extend_to_length(length) #

Returns a new version that is extended with 0s to the specified length.

Examples#
>>> v = Version('1')
>>> v.extend_to_length(3)
Version("1.0.0")
>>> v = Version('4!1.2+3.4')
>>> v.extend_to_length(4)
Version("4!1.2.0.0+3.4")
>>>

local_segments() #

Returns a list of local segments of the version. It does not contain the non-local segment of the version.

Examples#
>>> v = Version("1.2dev.3-alpha4.5+6.8")
>>> v.local_segments()
[[6], [8]]
>>>

pop_segments(n=1) #

Pops n number of segments from the version and returns the new version. Raises InvalidVersionError if version becomes invalid due to the operation.

Examples#
>>> v = Version('2!1.0.1')
>>> v.pop_segments() # `n` defaults to 1 if left empty
Version("2!1.0")
>>> v.pop_segments(2) # old version is still usable
Version("2!1")
>>> v.pop_segments(3) # doctest: +IGNORE_EXCEPTION_DETAIL
Traceback (most recent call last):
exceptions.InvalidVersionException: new Version must have atleast 1 valid
segment
>>>

remove_local() #

Returns a new version where the local segment of the version has been removed. Leaves the version unchanged if it does not have a local segment.

Examples#
>>> v = Version('1.0+3.4')
>>> v.remove_local()
Version("1.0")
>>> v = Version('1.0')
>>> v.remove_local()
Version("1.0")
>>>

segments() #

Returns a list of segments of the version. It does not contain the local segment of the version.

Examples#
>>> v = Version("1.2dev.3-alpha4.5+6.8")
>>> v.segments()
[[1], [2, 'dev'], [3], [0, 'alpha', 4], [5]]
>>>

starts_with(other) #

Checks if the version and local segment start same as other version.

Examples#
>>> v1 = Version('1.0.1')
>>> v2 = Version('1.0')
>>> v1.starts_with(v2)
True
>>>

strip_local() #

Returns a new version with local segment stripped.

Examples#
>>> v = Version('1.2.3+4.alpha-5')
>>> v.strip_local()
Version("1.2.3")
>>>

with_alpha() #

Returns a new version where the last segment of this version has been bumped with an alpha character. If the last segment contains a character, nothing is added.

Examples#
>>> v = Version('1.0')
>>> v.with_alpha()
Version("1.0.0a0")
>>> v = Version('1.0.f')
>>> v.with_alpha()
Version("1.0.f")
>>>

with_segments(start, stop) #

Returns new version with with segments ranging from start to stop. stop is exclusive. Raises InvalidVersionError if the provided range is invalid.

Examples#
>>> v = Version('2!1.2.3')
>>> v.with_segments(0, 2)
Version("2!1.2")
>>>