spack.version package

This module implements Version and version-ish objects. These are:

StandardVersion: A single version of a package. ClosedOpenRange: A range of versions of a package. VersionList: A ordered list of Version and VersionRange elements.

The set of Version and ClosedOpenRange is totally ordered wiht < defined as Version(x) < VersionRange(Version(y), Version(x)) if Version(x) <= Version(y).

class spack.version.ClosedOpenRange(lo: StandardVersion, hi: StandardVersion)[source]

Bases: object

classmethod from_version_range(lo: StandardVersion, hi: StandardVersion)[source]: Construct ClosedOpenRange from lo:hi range.

intersection(other: ClosedOpenRange | ConcreteVersion)[source]

intersects(other: ConcreteVersion | ClosedOpenRange | VersionList)[source]

overlaps(other: ClosedOpenRange | ConcreteVersion | VersionList) → bool[source]

satisfies(other: ClosedOpenRange | ConcreteVersion | VersionList)[source]

union(other: ClosedOpenRange | ConcreteVersion | VersionList)[source]

exception spack.version.EmptyRangeError(message, long_message=None)[source]

Bases: VersionError

Raised when constructing an empty version range.

class spack.version.GitVersion(string: str)[source]

Bases: ConcreteVersion

Class to represent versions interpreted from git refs.

There are two distinct categories of git versions:

GitVersions instantiated with an associated reference version (e.g. ‘git.foo=1.2’)
GitVersions requiring commit lookups

Git ref versions that are not paired with a known version are handled separately from all other version comparisons. When Spack identifies a git ref version, it associates a CommitLookup object with the version. This object handles caching of information from the git repo. When executing comparisons with a git ref version, Spack queries the CommitLookup for the most recent version previous to this git ref, as well as the distance between them expressed as a number of commits. If the previous version is X.Y.Z and the distance is D, the git commit version is represented by the tuple (X, Y, Z, '', D). The component '' cannot be parsed as part of any valid version, but is a valid component. This allows a git ref version to be less than (older than) every Version newer than its previous version, but still newer than its previous version.

To find the previous version from a git ref version, Spack queries the git repo for its tags. Any tag that matches a version known to Spack is associated with that version, as is any tag that is a known version prepended with the character v (i.e., a tag v1.0 is associated with the known version 1.0). Additionally, any tag that represents a semver version (X.Y.Z with X, Y, Z all integers) is associated with the version it represents, even if that version is not known to Spack. Each tag is then queried in git to see whether it is an ancestor of the git ref in question, and if so the distance between the two. The previous version is the version that is an ancestor with the least distance from the git ref in question.

This procedure can be circumvented if the user supplies a known version to associate with the GitVersion (e.g. [hash]=develop). If the user prescribes the version then there is no need to do a lookup and the standard version comparison operations are sufficient.

attach_lookup(lookup: AbstractRefLookup)[source]

Use the git fetcher to look up a version for a commit.

Since we want to optimize the clone and lookup, we do the clone once and store it in the user specified git repository cache. We also need context of the package to get known versions, which could be tags if they are linked to Git Releases. If we are unable to determine the context of the version, we cannot continue. This implementation is alongside the GitFetcher because eventually the git repos cache will be one and the same with the source cache.

property dashed: StandardVersion

property dotted: StandardVersion

has_git_prefix

intersection(other)[source]

intersects(other)[source]

is_commit: bool

is_prerelease() → bool[source]

isdevelop()[source]

property joined: StandardVersion

overlaps(other) → bool[source]

ref

property ref_lookup

property ref_version: StandardVersion

satisfies(other: GitVersion | StandardVersion | ClosedOpenRange | VersionList)[source]

property underscored: StandardVersion

up_to(index) → StandardVersion[source]

class spack.version.StandardVersion(string: str | None, version: Tuple[tuple, tuple], separators: tuple)[source]

Bases: ConcreteVersion

Class to represent versions

property dashed

The dashed representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.dashed Version(‘1-2-3b’)

Returns:: The version with separator characters replaced by dashes
Return type:: Version

property dotted

The dotted representation of the version.

Example: >>> version = Version(‘1-2-3b’) >>> version.dotted Version(‘1.2.3b’)

Returns:: The version with separator characters replaced by dots
Return type:: Version

property dotted_numeric_string: str

Replaces all non-numeric components of the version with 0.

This can be used to pass Spack versions to libraries that have stricter version schema.

static from_string(string: str)[source]

intersection(other: ClosedOpenRange | StandardVersion)[source]

intersects(other: StandardVersion | GitVersion | ClosedOpenRange) → bool[source]

is_prerelease() → bool[source]

isdevelop()[source]: Triggers on the special case of the @develop-like version.

property joined

The joined representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.joined Version(‘123b’)

Returns:: The version with separator characters removed
Return type:: Version

overlaps(other) → bool[source]

satisfies(other: ClosedOpenRange | StandardVersion | GitVersion | VersionList) → bool[source]

separators

string

static typemax()[source]

static typemin()[source]

property underscored

The underscored representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.underscored Version(‘1_2_3b’)

Returns:

The version with separator characters replaced by: underscores

Return type:

Version

union(other: ClosedOpenRange | StandardVersion)[source]

up_to(index)[source]

The version up to the specified component.

Examples: >>> version = Version(‘1.23-4b’) >>> version.up_to(1) Version(‘1’) >>> version.up_to(2) Version(‘1.23’) >>> version.up_to(3) Version(‘1.23-4’) >>> version.up_to(4) Version(‘1.23-4b’) >>> version.up_to(-1) Version(‘1.23-4’) >>> version.up_to(-2) Version(‘1.23’) >>> version.up_to(-3) Version(‘1’)

Returns:: The first index components of the version
Return type:: Version

version

spack.version.Version(string: str | int) → GitVersion | StandardVersion[source]

exception spack.version.VersionChecksumError(message, long_message=None)[source]

Bases: VersionError

Raised for version checksum errors.

exception spack.version.VersionError(message, long_message=None)[source]

Bases: SpackError

This is raised when something is wrong with a version.

class spack.version.VersionList(vlist=None)[source]

Bases: object

Sorted, non-redundant list of Version and ClosedOpenRange elements.

add(item: StandardVersion | GitVersion | ClosedOpenRange | VersionList)[source]

property concrete: ConcreteVersion | None

property concrete_range_as_version: ConcreteVersion | None: Like concrete, but collapses VersionRange(x, x) to Version(x). This is just for compatibility with old Spack.

copy()[source]

static from_dict(dictionary)[source]: Parse dict from to_dict.

highest() → StandardVersion | None[source]: Get the highest version in the list.

highest_numeric() → StandardVersion | None[source]: Get the highest numeric version in the list.

intersect(other) → bool[source]

Intersect this spec’s list with other.

Return True if the spec changed as a result; False otherwise

intersection(other: VersionList) → VersionList[source]

intersects(other)[source]

lowest() → StandardVersion | None[source]: Get the lowest version in the list.

overlaps(other) → bool[source]

preferred() → StandardVersion | None[source]: Get the preferred (latest) version in the list.

satisfies(other) → bool[source]

to_dict()[source]: Generate human-readable dict for YAML.

union(other: VersionList)[source]

update(other: VersionList)[source]

exception spack.version.VersionLookupError(message, long_message=None)[source]

Bases: VersionError

Raised for errors looking up git commits as versions.

spack.version.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)[source]

spack.version.any_version: VersionList = [:]: This version contains all possible versions.

spack.version.from_string(string) → VersionList | ClosedOpenRange | StandardVersion | GitVersion[source]: Converts a string to a version object. This is private. Client code should use ver().

spack.version.is_git_version(string: str) → bool[source]

spack.version.ver(obj) → VersionList | ClosedOpenRange | StandardVersion | GitVersion[source]: Parses a Version, VersionRange, or VersionList from a string or list of strings.

Submodules

spack.version.common module

exception spack.version.common.EmptyRangeError(message, long_message=None)[source]

Bases: VersionError

Raised when constructing an empty version range.

exception spack.version.common.VersionChecksumError(message, long_message=None)[source]

Bases: VersionError

Raised for version checksum errors.

exception spack.version.common.VersionError(message, long_message=None)[source]

Bases: SpackError

This is raised when something is wrong with a version.

exception spack.version.common.VersionLookupError(message, long_message=None)[source]

Bases: VersionError

Raised for errors looking up git commits as versions.

spack.version.common.is_git_version(string: str) → bool[source]

spack.version.git_ref_lookup module

class spack.version.git_ref_lookup.GitRefLookup(pkg_name)[source]

Bases: AbstractRefLookup

An object for cached lookups of git refs

GitRefLookup objects delegate to the MISC_CACHE for locking. GitRefLookup objects may be attached to a GitVersion to allow for comparisons between git refs and versions as represented by tags in the git repository.

property cache_key

property cache_path

property fetcher

get(ref) → Tuple[str | None, int][source]

Get the version string and distance for a given git ref.

Parameters:: ref (str) – git ref to lookup

Returns: optional version string and distance

load_data()[source]: Load data if the path already exists.

lookup_ref(ref) → Tuple[str | None, int][source]

Lookup the previous version and distance for a given commit.

We use git to compare the known versions from package to the git tags, as well as any git tags that are SEMVER versions, and find the latest known version prior to the commit, as well as the distance from that version to the commit in the git repo. Those values are used to compare Version objects.

property pkg

property repository_uri: Identifier for git repos used within the repo and metadata caches.

save()[source]: Save the data to file

spack.version.lookup module

class spack.version.lookup.AbstractRefLookup[source]

Bases: object

get(ref) → Tuple[str | None, int][source]

Get the version string and distance for a given git ref.

Parameters:: ref (str) – git ref to lookup

Returns: optional version string and distance

spack.version.version_types module

class spack.version.version_types.ClosedOpenRange(lo: StandardVersion, hi: StandardVersion)[source]

Bases: object

classmethod from_version_range(lo: StandardVersion, hi: StandardVersion)[source]: Construct ClosedOpenRange from lo:hi range.

intersection(other: ClosedOpenRange | ConcreteVersion)[source]

intersects(other: ConcreteVersion | ClosedOpenRange | VersionList)[source]

overlaps(other: ClosedOpenRange | ConcreteVersion | VersionList) → bool[source]

satisfies(other: ClosedOpenRange | ConcreteVersion | VersionList)[source]

union(other: ClosedOpenRange | ConcreteVersion | VersionList)[source]

class spack.version.version_types.ConcreteVersion[source]: Bases: object

class spack.version.version_types.GitVersion(string: str)[source]

Bases: ConcreteVersion

Class to represent versions interpreted from git refs.

There are two distinct categories of git versions:

GitVersions instantiated with an associated reference version (e.g. ‘git.foo=1.2’)
GitVersions requiring commit lookups

Git ref versions that are not paired with a known version are handled separately from all other version comparisons. When Spack identifies a git ref version, it associates a CommitLookup object with the version. This object handles caching of information from the git repo. When executing comparisons with a git ref version, Spack queries the CommitLookup for the most recent version previous to this git ref, as well as the distance between them expressed as a number of commits. If the previous version is X.Y.Z and the distance is D, the git commit version is represented by the tuple (X, Y, Z, '', D). The component '' cannot be parsed as part of any valid version, but is a valid component. This allows a git ref version to be less than (older than) every Version newer than its previous version, but still newer than its previous version.

To find the previous version from a git ref version, Spack queries the git repo for its tags. Any tag that matches a version known to Spack is associated with that version, as is any tag that is a known version prepended with the character v (i.e., a tag v1.0 is associated with the known version 1.0). Additionally, any tag that represents a semver version (X.Y.Z with X, Y, Z all integers) is associated with the version it represents, even if that version is not known to Spack. Each tag is then queried in git to see whether it is an ancestor of the git ref in question, and if so the distance between the two. The previous version is the version that is an ancestor with the least distance from the git ref in question.

This procedure can be circumvented if the user supplies a known version to associate with the GitVersion (e.g. [hash]=develop). If the user prescribes the version then there is no need to do a lookup and the standard version comparison operations are sufficient.

attach_lookup(lookup: AbstractRefLookup)[source]

Use the git fetcher to look up a version for a commit.

Since we want to optimize the clone and lookup, we do the clone once and store it in the user specified git repository cache. We also need context of the package to get known versions, which could be tags if they are linked to Git Releases. If we are unable to determine the context of the version, we cannot continue. This implementation is alongside the GitFetcher because eventually the git repos cache will be one and the same with the source cache.

property dashed: StandardVersion

property dotted: StandardVersion

has_git_prefix

intersection(other)[source]

intersects(other)[source]

is_commit: bool

is_prerelease() → bool[source]

isdevelop()[source]

property joined: StandardVersion

overlaps(other) → bool[source]

ref

property ref_lookup

property ref_version: StandardVersion

satisfies(other: GitVersion | StandardVersion | ClosedOpenRange | VersionList)[source]

property underscored: StandardVersion

up_to(index) → StandardVersion[source]

class spack.version.version_types.StandardVersion(string: str | None, version: Tuple[tuple, tuple], separators: tuple)[source]

Bases: ConcreteVersion

Class to represent versions

property dashed

The dashed representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.dashed Version(‘1-2-3b’)

Returns:: The version with separator characters replaced by dashes
Return type:: Version

property dotted

The dotted representation of the version.

Example: >>> version = Version(‘1-2-3b’) >>> version.dotted Version(‘1.2.3b’)

Returns:: The version with separator characters replaced by dots
Return type:: Version

property dotted_numeric_string: str

Replaces all non-numeric components of the version with 0.

This can be used to pass Spack versions to libraries that have stricter version schema.

static from_string(string: str)[source]

intersection(other: ClosedOpenRange | StandardVersion)[source]

intersects(other: StandardVersion | GitVersion | ClosedOpenRange) → bool[source]

is_prerelease() → bool[source]

isdevelop()[source]: Triggers on the special case of the @develop-like version.

property joined

The joined representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.joined Version(‘123b’)

Returns:: The version with separator characters removed
Return type:: Version

overlaps(other) → bool[source]

satisfies(other: ClosedOpenRange | StandardVersion | GitVersion | VersionList) → bool[source]

separators

string

static typemax()[source]

static typemin()[source]

property underscored

The underscored representation of the version.

Example: >>> version = Version(‘1.2.3b’) >>> version.underscored Version(‘1_2_3b’)

Returns:

The version with separator characters replaced by: underscores

Return type:

Version

union(other: ClosedOpenRange | StandardVersion)[source]

up_to(index)[source]

The version up to the specified component.

Examples: >>> version = Version(‘1.23-4b’) >>> version.up_to(1) Version(‘1’) >>> version.up_to(2) Version(‘1.23’) >>> version.up_to(3) Version(‘1.23-4’) >>> version.up_to(4) Version(‘1.23-4b’) >>> version.up_to(-1) Version(‘1.23-4’) >>> version.up_to(-2) Version(‘1.23’) >>> version.up_to(-3) Version(‘1’)

Returns:: The first index components of the version
Return type:: Version

version

spack.version.version_types.Version(string: str | int) → GitVersion | StandardVersion[source]

class spack.version.version_types.VersionList(vlist=None)[source]

Bases: object

Sorted, non-redundant list of Version and ClosedOpenRange elements.

add(item: StandardVersion | GitVersion | ClosedOpenRange | VersionList)[source]

property concrete: ConcreteVersion | None

property concrete_range_as_version: ConcreteVersion | None: Like concrete, but collapses VersionRange(x, x) to Version(x). This is just for compatibility with old Spack.

copy()[source]

static from_dict(dictionary)[source]: Parse dict from to_dict.

highest() → StandardVersion | None[source]: Get the highest version in the list.

highest_numeric() → StandardVersion | None[source]: Get the highest numeric version in the list.

intersect(other) → bool[source]

Intersect this spec’s list with other.

Return True if the spec changed as a result; False otherwise

intersection(other: VersionList) → VersionList[source]

intersects(other)[source]

lowest() → StandardVersion | None[source]: Get the lowest version in the list.

overlaps(other) → bool[source]

preferred() → StandardVersion | None[source]: Get the preferred (latest) version in the list.

satisfies(other) → bool[source]

to_dict()[source]: Generate human-readable dict for YAML.

union(other: VersionList)[source]

update(other: VersionList)[source]

spack.version.version_types.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)[source]

class spack.version.version_types.VersionStrComponent(data)[source]

Bases: object

data: int | str

static from_string(string)[source]

spack.version.version_types.from_string(string) → VersionList | ClosedOpenRange | StandardVersion | GitVersion[source]: Converts a string to a version object. This is private. Client code should use ver().

spack.version.version_types.parse_string_components(string: str) → Tuple[tuple, tuple][source]

spack.version.version_types.ver(obj) → VersionList | ClosedOpenRange | StandardVersion | GitVersion[source]: Parses a Version, VersionRange, or VersionList from a string or list of strings.