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)

Bases: VersionType

classmethod from_version_range(lo: StandardVersion, hi: StandardVersion) → ClosedOpenRange

Construct ClosedOpenRange from lo:hi range.

intersection(other: VersionType) → VersionType

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

union(other: VersionType) → VersionType

Return a VersionType containing self and other.

class spack.version.ConcreteVersion(*args, **kwargs)

Bases: VersionType

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

exception spack.version.EmptyRangeError(message, long_message=None)

Bases: VersionError

Raised when constructing an empty version range.

class spack.version.GitVersion(string: str)

Bases: ConcreteVersion

Class to represent versions interpreted from git refs.

There are two distinct categories of git versions:

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

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)

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

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

is_commit: bool

is_prerelease() → bool

isdevelop()

property joined: StandardVersion

ref

property ref_lookup

property ref_version: StandardVersion

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

property underscored: StandardVersion

up_to(index) → StandardVersion

class spack.version.StandardVersion(string: str, version: Tuple[Tuple[int | VersionStrComponent, ...], Tuple[int, ...]], separators: Tuple[str, ...])

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

intersection(other: VersionType) → VersionType

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

is_prerelease() → bool

isdevelop() → bool

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

Whether self is entirely contained in other.

separators: Tuple[str, ...]

property string: str

static typemax() → StandardVersion

static typemin() → StandardVersion

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

Return a VersionType containing self and other.

up_to(index: int) → StandardVersion

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

exception spack.version.VersionChecksumError(message, long_message=None)

Bases: VersionError

Raised for version checksum errors.

exception spack.version.VersionError(message, long_message=None)

Bases: SpackError

This is raised when something is wrong with a version.

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

Bases: VersionType

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

add(item: VersionType) → None

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

static from_dict(dictionary) → VersionList

Parse dict from to_dict.

highest() → StandardVersion | None

Get the highest version in the list.

highest_numeric() → StandardVersion | None

Get the highest numeric version in the list.

intersect(other: VersionType) → bool

Intersect this spec’s list with other.

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

intersection(other: VersionType) → VersionList

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

lowest() → StandardVersion | None

Get the lowest version in the list.

preferred() → StandardVersion | None

Get the preferred (latest) version in the list.

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

to_dict() → Dict

Generate human-readable dict for YAML.

union(other: VersionType) → VersionType

Return a VersionType containing self and other.

update(other: VersionList) → None

versions: List[VersionType]

exception spack.version.VersionLookupError(message, long_message=None)

Bases: VersionError

Raised for errors looking up git commits as versions.

spack.version.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)

class spack.version.VersionType(*args, **kwargs)

Bases: SupportsRichComparison

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

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

overlaps(other: VersionType) → bool

Whether self and other overlap (same as intersects()).

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

union(other: VersionType) → VersionType

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

Converts a string to a version object. This is private. Client code should use ver().

spack.version.is_git_version(string: str) → bool

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

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)

Bases: VersionError

Raised when constructing an empty version range.

exception spack.version.common.VersionChecksumError(message, long_message=None)

Bases: VersionError

Raised for version checksum errors.

exception spack.version.common.VersionError(message, long_message=None)

Bases: SpackError

This is raised when something is wrong with a version.

exception spack.version.common.VersionLookupError(message, long_message=None)

Bases: VersionError

Raised for errors looking up git commits as versions.

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

spack.version.git_ref_lookup module

class spack.version.git_ref_lookup.GitRefLookup(pkg_name)

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]

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()

Load data if the path already exists.

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

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()

Save the data to file

spack.version.lookup module

class spack.version.lookup.AbstractRefLookup

Bases: object

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

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)

Bases: VersionType

classmethod from_version_range(lo: StandardVersion, hi: StandardVersion) → ClosedOpenRange

Construct ClosedOpenRange from lo:hi range.

intersection(other: VersionType) → VersionType

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

union(other: VersionType) → VersionType

Return a VersionType containing self and other.

class spack.version.version_types.ConcreteVersion(*args, **kwargs)

Bases: VersionType

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

class spack.version.version_types.GitVersion(string: str)

Bases: ConcreteVersion

Class to represent versions interpreted from git refs.

There are two distinct categories of git versions:

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

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)

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

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

is_commit: bool

is_prerelease() → bool

isdevelop()

property joined: StandardVersion

ref

property ref_lookup

property ref_version: StandardVersion

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

property underscored: StandardVersion

up_to(index) → StandardVersion

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, ...])

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

intersection(other: VersionType) → VersionType

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

is_prerelease() → bool

isdevelop() → bool

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

Whether self is entirely contained in other.

separators: Tuple[str, ...]

property string: str

static typemax() → StandardVersion

static typemin() → StandardVersion

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

Return a VersionType containing self and other.

up_to(index: int) → StandardVersion

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

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)

Bases: VersionType

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

add(item: VersionType) → None

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

static from_dict(dictionary) → VersionList

Parse dict from to_dict.

highest() → StandardVersion | None

Get the highest version in the list.

highest_numeric() → StandardVersion | None

Get the highest numeric version in the list.

intersect(other: VersionType) → bool

Intersect this spec’s list with other.

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

intersection(other: VersionType) → VersionList

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

lowest() → StandardVersion | None

Get the lowest version in the list.

preferred() → StandardVersion | None

Get the preferred (latest) version in the list.

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

to_dict() → Dict

Generate human-readable dict for YAML.

union(other: VersionType) → VersionType

Return a VersionType containing self and other.

update(other: VersionList) → None

versions: List[VersionType]

spack.version.version_types.VersionRange(lo: str | StandardVersion, hi: str | StandardVersion)

class spack.version.version_types.VersionStrComponent(data: int | str)

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

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(*args, **kwargs)

Bases: SupportsRichComparison

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

Any versions contained in both self and other, or empty VersionList if no overlap.

intersects(other: VersionType) → bool

Whether self and other overlap.

overlaps(other: VersionType) → bool

Whether self and other overlap (same as intersects()).

satisfies(other: VersionType) → bool

Whether self is entirely contained in other.

union(other: VersionType) → VersionType

Return a VersionType containing self and other.

spack.version.version_types.from_string(string: str) → VersionType

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

Parse a string into a VersionTuple and SeparatorTuple.

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

Parses a Version, VersionRange, or VersionList from a string or list of strings.