migrate_v01_checkpoint_if_needed

Note

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

migrate_v01_checkpoint_if_needed(root: str | Path, *, run_fingerprint: str | None = None, clustering_mode: str | None = None) → LegacyCheckpointMigrationReport[source]

Detect a v0.1 checkpoint under root and migrate it to v1 entries.

Safe to call on every store open: when no v0.1 markers are present this is a no-op. After a successful migration the legacy manifest.json and subjects/ tree are moved under .v01_legacy_archive/ so subsequent opens see a pure v1 layout.

Parameters:

  • root – Checkpoint directory (v0.1 and/or v1 files).

  • run_fingerprint – Current analysis fingerprint used to build v1 cache keys (habitat.units:{fp}:… / habitat.one_step:{fp}:…). When None, failure/success IDs are still archived and reported but no fingerprint-scoped v1 keys are written.

  • clustering_mode – Optional override; when omitted the value from manifest.json is used to choose key prefixes.

Returns:

A LegacyCheckpointMigrationReport describing what was done.

Raises:

CompatibilityError – When the legacy tree is present but manifest.json is corrupt/unreadable.