spack.version package

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

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: VersionType

Base type for versions that represents a single (non-range or list) version.

is_prerelease() → bool[source]
isdevelop() → bool[source]
exception spack.version.EmptyRangeError(message: str, long_message: str | None = None)[source]

Bases: VersionError

Raised when constructing an empty version range.

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

Bases: ConcreteVersion

Class to represent git refs with an optional version or version range constraint.

Git versions are of the form git.<ref>[=<version>[:<version>]]. Examples:

  1. git.foo=1.2: the ref is assigned the version 1.2, and is concrete

  2. git.foo: short for git.foo=: (unconstrained ref)

  3. 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 calling assigned with 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 VersionLookupError when the version is outside the constraint on the ref.

commit_sha: str | None
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.

is_commit: bool
is_prerelease() → bool[source]
isdevelop()[source]
property joined: StandardVersion
ref
property ref_version: StandardVersion

The Spack version assigned to this git ref, used for ordering.

Raises a VersionLookupError when 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: ConcreteVersion

Class 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:

Version

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:

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) → 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.

is_prerelease() → bool[source]
isdevelop() → bool[source]

Triggers on the special case of the @develop-like version.

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:

Version

satisfies(other: VersionType) → bool[source]

Whether self is entirely contained in other.

separators: Tuple[str, ...]
property string: str
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:

Version

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:

Version

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.

version: Tuple[Tuple[int | VersionStrComponent, ...], Tuple[int, ...]]
spack.version.Version(string: str | int) → StandardVersion | GitVersion[source]
exception spack.version.VersionChecksumError(message: str, long_message: str | None = None)[source]

Bases: VersionError

Raised for version checksum errors.

exception spack.version.VersionError(message: str, long_message: str | None = None)[source]

Bases: SpackError

This is raised when something is wrong with a version.

class spack.version.VersionList(vlist: str | VersionType | Iterable | None = None)[source]

Bases: VersionType

Sorted, 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.

to_dict() → Dict[source]

Generate human-readable dict for YAML.

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: VersionError

Raised for errors looking up git commits as versions.

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

Bases: object

Base 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 of StandardVersion for handling git repositories.

  • ClosedOpenRange: an inclusive version range, closed or open, e.g. 3.0:5.0, 3.0:, or :5.0

  • VersionList: 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_commit_sha(string: str) → bool[source]
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, or VersionList from the argument.

Submodules

spack.version.common module

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

Bases: VersionError

Raised when constructing an empty version range.

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

Bases: VersionError

Raised for version checksum errors.

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

Bases: SpackError

This is raised when something is wrong with a version.

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

Bases: VersionError

Raised for errors looking up git commits as versions.

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

git.<ref>, <sha> or <ref>=<version or range>

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: object

An object for cached lookups of git refs. GitRefLookup objects delegate to the misc cache for locking.

property cache_key
property fetcher
get(ref) → Tuple[str | None, int][source]
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.git_ref_lookup.assign_git_version(pkg_name: str, version: VersionType, *, repo: RepoPath, misc_cache: FileCache, config: Configuration) → VersionType[source]

Return version with a Spack version assigned, by looking its ref up in the git repository of package pkg_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.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.

Raises a VersionLookupError when the package has no git attribute, the ref is unknown, or the version found is outside the range the ref is constrained to.

spack.version.git_ref_lookup.assign_git_versions(spec: Spec, *, repo: RepoPath, misc_cache: FileCache, config: Configuration) → Spec[source]

Return a copy of spec in which every git ref version is assigned a Spack version, or spec itself when there are no git ref versions to assign.

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: VersionType

Base type for versions that represents a single (non-range or list) version.

is_prerelease() → bool[source]
isdevelop() → bool[source]
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: ConcreteVersion

Class to represent git refs with an optional version or version range constraint.

Git versions are of the form git.<ref>[=<version>[:<version>]]. Examples:

  1. git.foo=1.2: the ref is assigned the version 1.2, and is concrete

  2. git.foo: short for git.foo=: (unconstrained ref)

  3. 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 calling assigned with 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 VersionLookupError when the version is outside the constraint on the ref.

commit_sha: str | None
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.

is_commit: bool
is_prerelease() → bool[source]
isdevelop()[source]
property joined: StandardVersion
ref
property ref_version: StandardVersion

The Spack version assigned to this git ref, used for ordering.

Raises a VersionLookupError when 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: ConcreteVersion

Class 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:

Version

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:

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) → 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.

is_prerelease() → bool[source]
isdevelop() → bool[source]

Triggers on the special case of the @develop-like version.

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:

Version

satisfies(other: VersionType) → bool[source]

Whether self is entirely contained in other.

separators: Tuple[str, ...]
property string: str
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:

Version

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:

Version

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.

version: Tuple[Tuple[int | VersionStrComponent, ...], Tuple[int, ...]]
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: VersionType

Sorted, 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.

to_dict() → Dict[source]

Generate human-readable dict for YAML.

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: object

Internal representation of the string (non-integer) components of Spack versions.

Versions comprise string and integer components (see SEGMENT_REGEX above).

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. VersionStrComponent is designed to work as a component in these version tuples, and as such must compare directly with int or other VersionStrComponent objects.

data: int | str
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: object

Base 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 of StandardVersion for handling git repositories.

  • ClosedOpenRange: an inclusive version range, closed or open, e.g. 3.0:5.0, 3.0:, or :5.0

  • VersionList: 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 VersionTuple and SeparatorTuple.

spack.version.version_types.ver(obj: VersionType | str | list | tuple | int | float) → VersionType[source]

Returns a ClosedOpenRange, StandardVersion, GitVersion, or VersionList from the argument.