CheckpointStore

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class CheckpointStore(root: str | Path, *, run_fingerprint: str | None = None, strict: bool = False, clustering_mode: str | None = None)

Bases: object

File-based persistence for subject-level results, keyed by cache key.

Each entry is one pickle file named by a digest of its key, written atomically (write-then-rename) so an interrupted run never leaves a half-written checkpoint that a resumed run would mistake for a valid result.

Parameters:

• root – Directory holding the checkpoint files. Created on first write. A v0.1 manifest.json / subjects/ tree here is migrated automatically on open.

• run_fingerprint – Optional analysis fingerprint bound to this store. When set, a mismatch with an existing fingerprint file is either raised (strict=True) or warned. Also scopes keys written during v0.1 → v1 migration.

• strict – When True, incompatible fingerprints raise CompatibilityError (v0.1 strict_checkpoint_hash). Legacy layouts are migrated rather than refused; only a corrupt v0.1 manifest raises.

__init__(root: str | Path, *, run_fingerprint: str | None = None, strict: bool = False, clustering_mode: str | None = None) → None

get(key: str) → Any | None

Return a previously stored result, or None when absent.

A corrupt entry is treated as absent (and removed) rather than failing the run: a checkpoint is a cache, never the source of truth.

Parameters:

key – Cache key produced by the operator’s cache_key.

put(key: str, value: Any) → None

Store a result under key atomically.

Storing a success clears any earlier failure record for the same key, so a retried subject that finally succeeds resumes cleanly.

Parameters:

• key – Cache key produced by the operator’s cache_key.

• value – Picklable result value.

contains(key: str) → bool

Return whether a success entry exists for key.

Parameters:

key – Cache key produced by the operator’s cache_key.

__len__() → int

Return the number of stored success entries.

put_failure(key: str, message: str) → None

Record that computing key failed, with a human-readable cause.

Only the terminal failure should be recorded (after a backend’s retry rounds are exhausted); intermediate failures of an in-flight retry never reach the store.

Parameters:

• key – Cache key produced by the operator’s cache_key.

• message – Failure description (exception type and text).

get_failure(key: str) → str | None

Return the recorded failure message for key, or None.

A corrupt failure record is treated as absent (and removed), on the same “a checkpoint is a cache” principle as success entries.

Parameters:

key – Cache key produced by the operator’s cache_key.

discard_failure(key: str) → None

Remove any failure record for key (e.g. before a forced rerun).

Parameters:

key – Cache key produced by the operator’s cache_key.

failed_keys() → Tuple[str, ...]

Return the original cache keys with a recorded failure, sorted.

Failure payloads embed the original key because the file name is a one-way digest; scanning the (small) failure set is the price of keeping file names filesystem-safe.

clear() → None

Remove every success entry, failure record, and fingerprint marker.

Examples using habit.execution.CheckpointStore

Running the same study on each backend

Running the same study on each backend