Skip to content

Cache#

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

The members below are the promised surface. ContentCache has other public methods, such as fetch and put, which the SDK uses to fill the cache and which may change in any release. The files inside the cache directory are private, so read them only through these calls.

bookshelf.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.

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.

bookshelf.CacheSummary dataclass #

CacheSummary(path: Path, entries: int, total_bytes: int, max_bytes: int, oldest_mtime: float | None, newest_mtime: float | None)

A point-in-time description of the cache contents.