spacr.example_data

Download, validate, and cache the optional example-screen data.

The example CSV files are distributed as release assets rather than package data. They are downloaded only when requested, validated against the bundled manifest, and reused from the user’s cache on subsequent runs. This module has no Qt dependency and can also be used from scripts.

Exceptions

ExampleDataError

Raised when the example data cannot be downloaded or validated.

Classes

Fetched

Paths and download status for a prepared example screen.

Functions

cache_folder(→ str)	Return the directory used to cache example-screen files.
entries_of_kind(→ List[dict])	The manifest entries for one kind, or all of them.
fetch(→ Fetched)	Prepare the example screen, downloading only missing files.
is_whole(→ bool)	Return whether a file matches one manifest entry.
missing(→ List[dict])	Return manifest entries absent or invalid in folder.
total_bytes(→ int)	Return the total expected size of the selected manifest entries.

Module Contents

exception spacr.example_data.ExampleDataError

Bases: RuntimeError

Raised when the example data cannot be downloaded or validated.

Initialize self. See help(type(self)) for accurate signature.

class spacr.example_data.Fetched

Paths and download status for a prepared example screen.

Parameters:

• counts (list of str) – Cached per-well guide-count tables.

• scores (list of str) – Cached per-cell classification-score tables.

• downloaded (list of str) – Files downloaded during this fetch; other returned files were cached.

• folder (str) – Directory containing the validated files.

note() → str

Return a concise status message describing the fetch result.

property files: List[str]

Return all validated count and score table paths.

spacr.example_data.cache_folder() → str

Return the directory used to cache example-screen files.

SPACR_EXAMPLE_DATA overrides the location. Otherwise the function uses XDG_CACHE_HOME or the platform-neutral ~/.cache fallback.

spacr.example_data.entries_of_kind(kind: str | None = None) → List[dict]

The manifest entries for one kind, or all of them.

Parameters:

kind – "counts", "scores", or None for everything.

Raises:

ValueError – for a kind the manifest does not contain, rather than returning an empty list – a typo would otherwise download nothing and report success.

spacr.example_data.fetch(folder=None, *, progress: Callable | None = None, cancelled: Callable | None = None, download: bool = True, kind: str | None = None) → Fetched

Prepare the example screen, downloading only missing files.

Parameters:

• folder (path-like, optional) – Cache directory. The standard example cache is used when omitted.

• progress (callable, optional) – Called as progress(name, received_bytes, total_bytes) while each file downloads.

• cancelled (callable, optional) – Zero-argument callback. A true result cancels the active download.

• download (bool, default=True) – If false, require every file to be present in the cache and do not use the network.

Returns:

Fetched – Validated count and score paths plus download status.

Raises:

ExampleDataError – If a file cannot be downloaded, validation fails, the operation is cancelled, or downloading is disabled while files are missing.

spacr.example_data.is_whole(path, entry) → bool

Return whether a file matches one manifest entry.

Parameters:

• path – file whose size and SHA-256 digest are to be checked.

• entry – manifest mapping containing the expected bytes and sha256 values.

The inexpensive size check runs before the SHA-256 digest is calculated.

spacr.example_data.missing(folder=None, kind: str | None = None) → List[dict]

Return manifest entries absent or invalid in folder.

Parameters:

kind – restrict to one kind. Regression can fetch its counts and its scores separately, because a user checking one of them should not wait for the other.

spacr.example_data.total_bytes(entries: Sequence[dict] | None = None) → int

Return the total expected size of the selected manifest entries.