Cache

Caching helpers and sample dataset management.

Cache helpers — on-disk caching for sample datasets used by notebooks.

The notebooks under notebooks/ deliberately do not commit spatial or large tabular fixtures to the repo. Instead, each notebook that needs a dataset calls ensure_sample_dataset(), which downloads the file on first run into a user-scoped cache directory and returns a local path on every subsequent run.

Default cache root: ~/.cache/siege_utilities/notebooks/. Override per call via the cache_dir argument or globally with the SIEGE_UTILITIES_CACHE_DIR environment variable.

The cache enforces a per-call size budget — when adding a new file would exceed the budget, oldest-access entries are evicted first (LRU by st_atime). Default budget: 5 GiB; override via the SIEGE_UTILITIES_CACHE_MAX_BYTES env var or the max_bytes kwarg.

exception siege_utilities.cache.SampleDatasetError[source]

Bases: RuntimeError

Raised when a sample dataset cannot be fetched or fails verification.

siege_utilities.cache.ensure_sample_dataset(name, url, *, cache_dir=None, sha256=None, max_bytes=None)[source]

Return a local path to name, downloading from url on first use.

Parameters:

  • name (str) – Filename to use in the cache (e.g. "tx_counties_2020.geojson"). Not treated as a directory — must be a single filename. Cache layout is flat by design; if you need hierarchy, encode it in the name.

  • url (str) – HTTPS URL to download from on cache miss.

  • cache_dir (Path | None) – Override the cache directory. Defaults to _default_cache_dir() (~/.cache/siege_utilities/notebooks or the value of SIEGE_UTILITIES_CACHE_DIR).

  • sha256 (str | None) – Optional hex digest. When provided, a freshly-downloaded file is verified against it and SampleDatasetError is raised on mismatch (the corrupt file is removed).

  • max_bytes (int | None)

Returns:

Absolute path to the cached file.

Return type:

Path

Raises: