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 theCommitLookup
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 isX.Y.Z
and the distance isD
, 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 tagv1.0
is associated with the known version1.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
- property joined: StandardVersion
- 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:
- 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:
- 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.
- intersection(other: ClosedOpenRange | StandardVersion)[source]
- intersects(other: StandardVersion | GitVersion | ClosedOpenRange) bool [source]
- 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:
- satisfies(other: ClosedOpenRange | StandardVersion | GitVersion | VersionList) bool [source]
- separators
- string
- 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:
- 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
- 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.
- 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]
- lowest() StandardVersion | None [source]
Get the lowest version in the list.
- preferred() StandardVersion | None [source]
Get the preferred (latest) version in the list.
- 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.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.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
- 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.
spack.version.lookup module
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.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 theCommitLookup
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 isX.Y.Z
and the distance isD
, 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 tagv1.0
is associated with the known version1.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
- property joined: StandardVersion
- 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:
- 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:
- 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.
- intersection(other: ClosedOpenRange | StandardVersion)[source]
- intersects(other: StandardVersion | GitVersion | ClosedOpenRange) bool [source]
- 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:
- satisfies(other: ClosedOpenRange | StandardVersion | GitVersion | VersionList) bool [source]
- separators
- string
- 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:
- 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
- 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.
- 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]
- lowest() StandardVersion | None [source]
Get the lowest version in the list.
- preferred() StandardVersion | None [source]
Get the preferred (latest) version in the list.
- union(other: VersionList)[source]
- update(other: VersionList)[source]
- spack.version.version_types.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)[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.ver(obj) VersionList | ClosedOpenRange | StandardVersion | GitVersion [source]
Parses a Version, VersionRange, or VersionList from a string or list of strings.