testsuite.cache¶

The download and the cache of a test suite.

A test suite is an archive which is downloaded once and unpacked into the user cache, i.e. XDG_CACHE_HOME or ~/.cache, under sbmlsim/. An environment variable points at the cases when they live elsewhere, e.g. on a machine without a network. The archive is unpacked next to its target and moved into place, so an interrupted download does not leave a directory which looks like a cached suite.

A fetch holds a lock on a file in its staging directory while it runs, which the operating system releases when the process ends, also when it is killed: fcntl.flock on POSIX, msvcrt.locking on Windows. A staging directory whose lock nobody holds is what a killed fetch left behind, the next fetch or load of the target removes it.

cache_root ¶

cache_root()

Get the directory the test suites are cached in.

Returns:

Type	Description
`Path`	`sbmlsim` in the user cache, i.e. in `XDG_CACHE_HOME` or `~/.cache`.

cache_path ¶

cache_path(variable, *parts)

Get the directory a test suite is unpacked into.

Parameters:

Name	Type	Description	Default
`variable`	`str`	the environment variable which overrides the directory.	required
`*parts`	`str`	the directories below the cache of `sbmlsim`, e.g. the name of the suite and its version.	`()`

Returns:

Type	Description
`Path`	The value of the environment variable when it is set, the directory
`Path`	in the user cache otherwise.

is_overridden ¶

is_overridden(variable)

Check whether an environment variable points at the cases.

The directory of an override is not in the cache: nothing next to it was left by a fetch, see remove_stale.

Parameters:

Name	Type	Description	Default
`variable`	`str`	the environment variable which overrides the directory.	required

Returns:

Type	Description
`bool`	Whether the variable is set.

fetch ¶

fetch(url, path, select)

Download an archive and move a directory of it into place.

Every fetch unpacks into a staging directory of its own next to path, so two processes which fetch one target do not share one. The fetch holds the lock of the staging directory until it is removed, and removes the staging directories of the target nobody holds, see remove_stale. A target which is in place when the cases are moved there is the result of another fetch, and is used. The members of the archive are unpacked below the staging directory, a member with .. or an absolute path does not leave it. The suite which calls fetch logs what it downloads, fetch logs the URL at the level DEBUG.

Parameters:

Name	Type	Description	Default
`url`	`str`	the zip archive.	required
`path`	`Path`	the directory which holds the cases afterwards.	required
`select`	`Callable[[Path], Path]`	gets the directory the archive was unpacked into and returns the directory of it which becomes `path`.	required

Returns:

Type	Description
`Path`	`path`.

Raises:

Type	Description
`OSError`	if the archive cannot be downloaded or unpacked, if `select` does not find the cases, or if they cannot be moved into place.

remove_stale ¶

remove_stale(path, stale_after=STALE_AFTER)

Remove the staging directories a killed fetch of a target left behind.

A fetch which is running has a staging directory as well and holds the lock of its lock file. A staging directory with a lock file is removed when its lock can be taken, i.e. the fetch which created it has ended. A staging directory without a lock file is removed when it is older than stale_after.

Parameters:

Name	Type	Description	Default
`path`	`Path`	the target of the fetch.	required
`stale_after`	`float`	age in seconds after which a staging directory without a lock file is stale.	`STALE_AFTER`

Returns:

Type	Description
`list[Path]`	The directories which were removed.