specsr.checkpoints

On-demand model weight fetching from the Hugging Face Hub.

Weights are not stored in the git repository. They live in a Hub model repo and are downloaded (and cached) the first time they are requested:

from specsr.checkpoints import get_checkpoint
path = get_checkpoint("sr1")

Set SPECSR_CHECKPOINT_DIR to load from a local directory instead — useful during training, offline runs, or CI.

Functions

archive_dir(name[, repo_id])	Return a local directory holding the named archival chain.
archive_path(name)	Where the named archive lives, or would live.
available_archives()	Archive directory names understood by archive_dir().
available_checkpoints()	Logical checkpoint names understood by get_checkpoint().
ensure_archive(path)	Materialise the archive containing path, if it is not there yet.
get_checkpoint(name[, repo_id, revision])	Return a local path to the requested checkpoint, downloading if needed.
try_archive(name[, repo_id])	archive_dir(), returning None instead of raising.

specsr.checkpoints.get_checkpoint(name, repo_id=None, revision=None)

Return a local path to the requested checkpoint, downloading if needed.

Parameters:

• name (str) – Logical name, e.g. "sr1". See available_checkpoints().

• repo_id (str | None) – Override the Hub repo. Defaults to SPECSR_CHECKPOINT_REPO or DEFAULT_REPO.

• revision (str | None) – Branch, tag or commit. Defaults to SPECSR_CHECKPOINT_REVISION or DEFAULT_REVISION.

Return type:

Path

specsr.checkpoints.available_checkpoints()

Logical checkpoint names understood by get_checkpoint().

Return type:

list[str]

specsr.checkpoints.archive_dir(name, repo_id=None)

Return a local directory holding the named archival chain.

A checkout that still has checkpoints/<name>/ gets that directory untouched, so restoring the files by hand keeps working and costs no network. Otherwise the chain is fetched from the Hub and assembled under the cache directory as symlinks into the Hub cache – the files are not copied, so a second archive sharing a blob costs nothing.

Raises KeyError for an unknown name and lets the download error propagate. Use try_archive() where a missing chain should be a skip rather than a failure.

Parameters:

• name (str)

• repo_id (str | None)

Return type:

Path

specsr.checkpoints.archive_path(name)

Where the named archive lives, or would live. Never touches the network.

Exists because the archive paths are used as default argument values – load_pipeline(sr1_ckpt=BASELINE / "best_superres_model.pth") and several argparse defaults – which are evaluated at import. Downloading there would mean import specsr.evaluation reaches for the Hub, so resolution and materialisation are kept apart: this names the location, archive_dir() fills it in, and ensure_archive() bridges the two at the point of use.

Parameters:

name (str)

Return type:

Path

specsr.checkpoints.ensure_archive(path)

Materialise the archive containing path, if it is not there yet.

Call it immediately before opening a file whose default came from archive_path(). An existing path is returned untouched, so this costs nothing in a checkout that still has the directories, and a path belonging to no known archive is returned untouched too – an explicit --sr1-ckpt /some/run/best_superres_model.pth must not be second-guessed.

Return type:

Path

specsr.checkpoints.try_archive(name, repo_id=None)

archive_dir(), returning None instead of raising.

For test guards and figure scripts, where “the weights are not reachable” means skip, not crash. Offline, unauthenticated and missing-file cases all land here.

Parameters:

• name (str)

• repo_id (str | None)

Return type:

Path | None

specsr.checkpoints.available_archives()

Archive directory names understood by archive_dir().

Return type:

list[str]