voxcity.utils.cache

On-disk cache for downloaded geospatial data.

Downloads are keyed by the wrapped function’s fully-qualified name plus ALL of its bound arguments (positional and keyword, matched against the function’s signature so equivalent calls hash the same regardless of calling convention). Parameters named output_dir or download_dir are excluded from the key, since they only control where files are staged on disk and do not affect the downloaded data itself – two calls that differ only in output_dir should hit the same cache entry. Results are stored as pickles under a per-user cache directory. The cache is best-effort: any read/write failure falls back to a fresh download. Layout:

<cache_dir>/downloads/<key>.pkl # pickled return value <cache_dir>/downloads/<key>.meta.json # source, args, created timestamp

The cache directory resolves, in order: the VOXCITY_CACHE_DIR environment variable, else ~/.voxcity/cache.

Entries never expire on their own: a cached rectangle is reused until the caller passes force_refresh=True or clear_download_cache() is run. Empty results (None or a zero-length GeoDataFrame/collection) are NOT cached, so a transient upstream outage cannot poison future runs.

Functions

get_cache_dir(→ pathlib.Path)	Return (creating if needed) the directory downloads are cached under.
cached_download(func)	Cache a downloader's return value on disk, keyed by its arguments.
clear_download_cache(→ int)	Delete all cached downloads. Returns the number of files removed.

Module Contents

voxcity.utils.cache.get_cache_dir() → pathlib.Path

Return (creating if needed) the directory downloads are cached under.

voxcity.utils.cache.cached_download(func)

Cache a downloader’s return value on disk, keyed by its arguments.

The wrapped function gains two keyword-only controls (consumed here, not forwarded to func): use_download_cache (default True) and force_refresh (default False).

voxcity.utils.cache.clear_download_cache() → int

Delete all cached downloads. Returns the number of files removed.