Cache#

Downloads are cached by content hash under $BOOKSHELF_CACHE_DIR. Pass a ContentCache as cache= to Bookshelf or AsyncBookshelf to move it for one client.

bookshelf.cache.ContentCache #

ContentCache(base_dir: Path | None = None, *, max_bytes: int = DEFAULT_MAX_BYTES)

A small disk cache keyed only by canonical content hash.

get #

get(content_hash: str) -> Path | None

Return the cached path, or None when the hash is absent.

fetch #

fetch(content_hash: str, download: Callable[[Path], None]) -> Path

Return the path of verified content, calling download only on a miss.

download writes the bytes to the path it is given. Concurrent fetches of one hash, across threads and processes, download it once. Bytes that do not match content_hash raise HashMismatchError and are never stored.

fetch_async `async` #

fetch_async(content_hash: str, download: Callable[[Path], Awaitable[None]]) -> Path

Return the path of verified content, awaiting download only on a miss.

The async twin of fetch, hashing and waiting on the lock off the event loop.

put #

put(content_hash: str, content: bytes) -> Path

Atomically store content under its hash and enforce the size cap.

stage #

stage(content_hash: str) -> Iterator[Path]

Yield a unique staging path and atomically commit it on success.

discard #

discard(content_hash: str) -> None

Remove one invalid cache entry if it exists.

summary #

summary() -> CacheSummary

Describe the cache: entry count, total bytes, age range and cap.

evict_lru #

evict_lru(max_bytes: int | None = None) -> int

Remove least recently used entries until the cache fits the cap.

max_bytes overrides the configured cap for this eviction only.

clear #

clear() -> int

Remove every entry and metadata record, returning the content bytes freed.