LookupCache

class VmaxBuilder.utils.lookup_cache.LookupCache(cache_dir: Path, namespace: str, autosave: bool = True)

Thread-safe, disk-backed key-value store for a single namespace.

Parameters:

• cache_dir – Directory where the JSON file for this namespace lives.

• namespace – Logical name of the cache (becomes the JSON filename, e.g. "ensembl_sequences" → cache_dir/ensembl_sequences.json).

• autosave – When True (the default) every set() / set_many() call flushes the updated data to disk immediately. Set to False for bulk-loading scenarios where you want to call save() once at the end.

Public Methods

clear(…)	Remove all entries and persist an empty cache file.
get(…)	Return the cached value for key, or None if absent.
hits_and_misses(…)	Split keys into (cached_keys, missing_keys).
invalidate(…)	Remove a single cached entry and persist.
keys(…)	Return a snapshot of all cache keys.
save(…)	Flush current state to disk (useful when autosave is False).
set(…)	Store value under key and write to disk if autosave is on.
set_many(…)	Store multiple key-value pairs in one operation (single disk write).
path	Absolute path to the JSON file backing this cache.

_write_to_disk() → None

Atomic write via a temp file so crashes never corrupt the cache.

get(key: str) → Any | None

Return the cached value for key, or None if absent.

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

Store value under key and write to disk if autosave is on.

set_many(items: dict[str, Any]) → None

Store multiple key-value pairs in one operation (single disk write).

save() → None

Flush current state to disk (useful when autosave is False).

invalidate(key: str) → None

Remove a single cached entry and persist.

clear() → None

Remove all entries and persist an empty cache file.

keys() → list[str]

Return a snapshot of all cache keys.

hits_and_misses(keys: list[str]) → tuple[list[str], list[str]]

Split keys into (cached_keys, missing_keys).

Use this before making API calls to determine which items can be served from cache and which need fetching:

hits, misses = cache.hits_and_misses(gene_symbols)
# only fetch 'misses', reuse 'hits' directly

property path: Path

Absolute path to the JSON file backing this cache.