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.
- class spack.version.ClosedOpenRange(lo: StandardVersion, hi: StandardVersion)[source]¶
Bases:
VersionType- classmethod from_version_range(lo: StandardVersion, hi: StandardVersion) ClosedOpenRange[source]¶
Construct ClosedOpenRange from lo:hi range.
- hi: StandardVersion¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- lo: StandardVersion¶
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- class spack.version.ConcreteVersion[source]¶
Bases:
VersionTypeBase type for versions that represents a single (non-range or list) version.
- exception spack.version.EmptyRangeError(message: str, long_message: str | None = None)[source]¶
Bases:
VersionErrorRaised when constructing an empty version range.
- class spack.version.GitVersion(string: str)[source]¶
Bases:
ConcreteVersionClass to represent git refs with an optional version or version range constraint.
Git versions are of the form
git.<ref>[=<version>[:<version>]]. Examples:git.foo=1.2: the ref is assigned the version 1.2, and is concretegit.foo: short forgit.foo=:(unconstrained ref)git.foo=1.2:1.3: the ref is constrained to the range 1.2:1.3
Git versions of the form
git.<ref>=<version>are concrete and can be compared to other versions. Git versions with a range constraint can be made concrete by callingassignedwith a version that satisfies the constraint.- assigned(version: StandardVersion) GitVersion[source]¶
Returns a copy of this git ref with the specific version assigned. Raises a
VersionLookupErrorwhen the version is outside the constraint on the ref.
- constraint: StandardVersion | ClosedOpenRange¶
The Spack versions this ref is constrained to (
@:for unconstrained).
- property dashed: StandardVersion¶
- property dotted: StandardVersion¶
- has_git_prefix¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- property joined: StandardVersion¶
- ref¶
- property ref_version: StandardVersion¶
The Spack version assigned to this git ref, used for ordering.
Raises a
VersionLookupErrorwhen no version has been assigned yet.
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- property std_version: StandardVersion | None¶
The Spack version assigned to this ref, or None while it is only constrained.
- property underscored: StandardVersion¶
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- up_to(index) StandardVersion[source]¶
- class spack.version.StandardVersion(string: str, version: Tuple[Tuple[int | VersionStrComponent, ...], Tuple[int, ...]], separators: Tuple[str, ...])[source]¶
Bases:
ConcreteVersionClass to represent versions
- property dashed: StandardVersion¶
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: StandardVersion¶
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.
- static from_string(string: str) StandardVersion[source]¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- property joined: StandardVersion¶
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: VersionType) bool[source]¶
Whether self is entirely contained in other.
- static typemax() StandardVersion[source]¶
- static typemin() StandardVersion[source]¶
- property underscored: StandardVersion¶
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: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- up_to(index: int) StandardVersion[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:
- property up_to_1¶
The version truncated to the first component.
- property up_to_2¶
The version truncated to the first two components.
- property up_to_3¶
The version truncated to the first three components.
- spack.version.Version(string: str | int) StandardVersion | GitVersion[source]¶
- exception spack.version.VersionChecksumError(message: str, long_message: str | None = None)[source]¶
Bases:
VersionErrorRaised for version checksum errors.
- exception spack.version.VersionError(message: str, long_message: str | None = None)[source]¶
Bases:
SpackErrorThis is raised when something is wrong with a version.
- class spack.version.VersionList(vlist: str | VersionType | Iterable | None = None)[source]¶
Bases:
VersionTypeSorted, non-redundant list of Version and ClosedOpenRange elements.
- add(item: VersionType) None[source]¶
- classmethod any() VersionList[source]¶
Return a VersionList that matches any version.
- 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() VersionList[source]¶
- static from_dict(dictionary) VersionList[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: VersionType) bool[source]¶
Intersect this spec’s list with other.
Return True if the spec changed as a result; False otherwise
- intersection(other: VersionType) VersionList[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- lowest() StandardVersion | None[source]¶
Get the lowest version in the list.
- preferred() StandardVersion | None[source]¶
Get the preferred (latest) version in the list.
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- update(other: VersionList) None[source]¶
- versions: List[VersionType]¶
- exception spack.version.VersionLookupError(message: str, long_message: str | None = None)[source]¶
Bases:
VersionErrorRaised for errors looking up git commits as versions.
- spack.version.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)[source]¶
- class spack.version.VersionType[source]¶
Bases:
objectBase type for all versions in Spack (ranges, lists, regular versions, and git versions).
Versions in Spack behave like sets, and support some basic set operations. There are four subclasses of
VersionType:StandardVersion: a single, concrete version, e.g. 3.4.5 or 5.4b0.GitVersion: subclass ofStandardVersionfor handling git repositories.ClosedOpenRange: an inclusive version range, closed or open, e.g.3.0:5.0,3.0:, or:5.0VersionList: An ordered list of any of the above types.
Notably, when Spack parses a version, it’s always a range unless specified with
@=to make it concrete.- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- overlaps(other: VersionType) bool[source]¶
Whether self and other overlap (same as
intersects()).
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- spack.version.any_version: VersionList¶
This version contains all possible versions.
- spack.version.from_string(string: str) VersionType[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]¶
git.<ref>,<sha>or<ref>=<version or range>
- spack.version.ver(obj: VersionType | str | list | tuple | int | float) VersionType[source]¶
Returns a
ClosedOpenRange,StandardVersion,GitVersion, orVersionListfrom the argument.
Submodules¶
spack.version.common module¶
- exception spack.version.common.EmptyRangeError(message: str, long_message: str | None = None)[source]¶
Bases:
VersionErrorRaised when constructing an empty version range.
- exception spack.version.common.VersionChecksumError(message: str, long_message: str | None = None)[source]¶
Bases:
VersionErrorRaised for version checksum errors.
- exception spack.version.common.VersionError(message: str, long_message: str | None = None)[source]¶
Bases:
SpackErrorThis is raised when something is wrong with a version.
spack.version.git_ref_lookup module¶
- class spack.version.git_ref_lookup.GitRefLookup(pkg_name: str, *, repo: RepoPath, misc_cache: FileCache, config: Configuration)[source]¶
Bases:
objectAn object for cached lookups of git refs. GitRefLookup objects delegate to the misc cache for locking.
- property cache_key¶
- property fetcher¶
- 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.git_ref_lookup.assign_git_version(pkg_name: str, version: VersionType, *, repo: RepoPath, misc_cache: FileCache, config: Configuration) VersionType[source]¶
Return
versionwith a Spack version assigned, by looking its ref up in the git repository of packagepkg_name. This may trigger a git clone.Assignment queries the git repo 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.Zand 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.0is 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.Raises a
VersionLookupErrorwhen the package has nogitattribute, the ref is unknown, or the version found is outside the range the ref is constrained to.
spack.version.version_types module¶
- class spack.version.version_types.ClosedOpenRange(lo: StandardVersion, hi: StandardVersion)[source]¶
Bases:
VersionType- classmethod from_version_range(lo: StandardVersion, hi: StandardVersion) ClosedOpenRange[source]¶
Construct ClosedOpenRange from lo:hi range.
- hi: StandardVersion¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- lo: StandardVersion¶
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- class spack.version.version_types.ConcreteVersion[source]¶
Bases:
VersionTypeBase type for versions that represents a single (non-range or list) version.
- spack.version.version_types.GitConstraint¶
A git version can be mapped to a specific version, or be constrained by a version range
alias of
StandardVersion|ClosedOpenRange
- class spack.version.version_types.GitVersion(string: str)[source]¶
Bases:
ConcreteVersionClass to represent git refs with an optional version or version range constraint.
Git versions are of the form
git.<ref>[=<version>[:<version>]]. Examples:git.foo=1.2: the ref is assigned the version 1.2, and is concretegit.foo: short forgit.foo=:(unconstrained ref)git.foo=1.2:1.3: the ref is constrained to the range 1.2:1.3
Git versions of the form
git.<ref>=<version>are concrete and can be compared to other versions. Git versions with a range constraint can be made concrete by callingassignedwith a version that satisfies the constraint.- assigned(version: StandardVersion) GitVersion[source]¶
Returns a copy of this git ref with the specific version assigned. Raises a
VersionLookupErrorwhen the version is outside the constraint on the ref.
- constraint: StandardVersion | ClosedOpenRange¶
The Spack versions this ref is constrained to (
@:for unconstrained).
- property dashed: StandardVersion¶
- property dotted: StandardVersion¶
- has_git_prefix¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- property joined: StandardVersion¶
- ref¶
- property ref_version: StandardVersion¶
The Spack version assigned to this git ref, used for ordering.
Raises a
VersionLookupErrorwhen no version has been assigned yet.
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- property std_version: StandardVersion | None¶
The Spack version assigned to this ref, or None while it is only constrained.
- property underscored: StandardVersion¶
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- up_to(index) StandardVersion[source]¶
- spack.version.version_types.PrereleaseTuple¶
A Prerelease identifier is a constant for alpha/beta/rc/final and one optional number. Most versions will have this set to
(FINAL,). Prereleases will have some other initial constant followed by a number, e.g.(RC, 1).alias of
Tuple[int, …]
- spack.version.version_types.SeparatorTuple¶
Separators from a parsed version.
alias of
Tuple[str, …]
- class spack.version.version_types.StandardVersion(string: str, version: Tuple[Tuple[int | VersionStrComponent, ...], Tuple[int, ...]], separators: Tuple[str, ...])[source]¶
Bases:
ConcreteVersionClass to represent versions
- property dashed: StandardVersion¶
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: StandardVersion¶
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.
- static from_string(string: str) StandardVersion[source]¶
- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- property joined: StandardVersion¶
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: VersionType) bool[source]¶
Whether self is entirely contained in other.
- static typemax() StandardVersion[source]¶
- static typemin() StandardVersion[source]¶
- property underscored: StandardVersion¶
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: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- up_to(index: int) StandardVersion[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:
- property up_to_1¶
The version truncated to the first component.
- property up_to_2¶
The version truncated to the first two components.
- property up_to_3¶
The version truncated to the first three components.
- spack.version.version_types.Version(string: str | int) StandardVersion | GitVersion[source]¶
- spack.version.version_types.VersionComponentTuple¶
Version components are integers for numeric parts, VersionStrComponents for string parts.
alias of
Tuple[int|VersionStrComponent, …]
- class spack.version.version_types.VersionList(vlist: str | VersionType | Iterable | None = None)[source]¶
Bases:
VersionTypeSorted, non-redundant list of Version and ClosedOpenRange elements.
- add(item: VersionType) None[source]¶
- classmethod any() VersionList[source]¶
Return a VersionList that matches any version.
- 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() VersionList[source]¶
- static from_dict(dictionary) VersionList[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: VersionType) bool[source]¶
Intersect this spec’s list with other.
Return True if the spec changed as a result; False otherwise
- intersection(other: VersionType) VersionList[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- lowest() StandardVersion | None[source]¶
Get the lowest version in the list.
- preferred() StandardVersion | None[source]¶
Get the preferred (latest) version in the list.
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- update(other: VersionList) None[source]¶
- versions: List[VersionType]¶
- spack.version.version_types.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)[source]¶
- class spack.version.version_types.VersionStrComponent(data: int | str)[source]¶
Bases:
objectInternal representation of the string (non-integer) components of Spack versions.
Versions comprise string and integer components (see
SEGMENT_REGEXabove).This represents a string component, which is either some component consisting only of alphabetical characters, or a special “infinity version” like
main,develop,master, etc.For speed, Spack versions are designed to map to Python tuples, so that we can use Python’s fast lexicographic tuple comparison on them.
VersionStrComponentis designed to work as a component in these version tuples, and as such must compare directly withintor otherVersionStrComponentobjects.- static from_string(string: str) VersionStrComponent[source]¶
- spack.version.version_types.VersionTuple¶
Actual version tuple, including the split version number itself and the prerelease, all represented as tuples.
alias of
Tuple[Tuple[int|VersionStrComponent, …],Tuple[int, …]]
- class spack.version.version_types.VersionType[source]¶
Bases:
objectBase type for all versions in Spack (ranges, lists, regular versions, and git versions).
Versions in Spack behave like sets, and support some basic set operations. There are four subclasses of
VersionType:StandardVersion: a single, concrete version, e.g. 3.4.5 or 5.4b0.GitVersion: subclass ofStandardVersionfor handling git repositories.ClosedOpenRange: an inclusive version range, closed or open, e.g.3.0:5.0,3.0:, or:5.0VersionList: An ordered list of any of the above types.
Notably, when Spack parses a version, it’s always a range unless specified with
@=to make it concrete.- intersection(other: VersionType) VersionType[source]¶
Any versions contained in both self and other, or empty VersionList if no overlap.
- intersects(other: VersionType) bool[source]¶
Whether self and other overlap.
- overlaps(other: VersionType) bool[source]¶
Whether self and other overlap (same as
intersects()).
- satisfies(other: VersionType) bool[source]¶
Whether self is entirely contained in other.
- union(other: VersionType) VersionType[source]¶
Return a VersionType containing self and other.
- spack.version.version_types.from_string(string: str) VersionType[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[int | VersionStrComponent, ...], Tuple[int, ...]], Tuple[str, ...]][source]¶
Parse a string into a
VersionTupleandSeparatorTuple.
- spack.version.version_types.ver(obj: VersionType | str | list | tuple | int | float) VersionType[source]¶
Returns a
ClosedOpenRange,StandardVersion,GitVersion, orVersionListfrom the argument.