Cache
cache.Cache
A namespaced, versioned, content-keyed blob/directory cache under cache_root.
Usage
cache.Cache(
namespace,
version,
root,
)Entries live at <cache_root>/<namespace>/v<version>/<digest[:2]>/<digest> — the version is part of the path, so bumping it is the only invalidation. Every write stages a temp sibling and publishes it with a single atomic os.replace(), so a reader never observes a partial entry.
Parameter Attributes
namespace: strversion: introot: Path
Example
>>> cache = Cache.open("frames", version=1)
>>> path = await cache.put_bytes(cache.key("clip", 7), jpeg)Methods
| Name | Description |
|---|---|
| get() |
Return the published entry path (a file or a directory), or None on a miss.
|
| get_bytes() |
Read a published blob entry, or None on a miss.
|
| key() |
Derive a content address from a type-tagged, length-framed encoding of parts.
|
| open() |
Open (creating on first use) the cache tree for namespace at version, sweeping stale temps.
|
| put_bytes() |
Atomically store data under key and return the published entry path.
|
| stats() | Count the published entries and total bytes in this cache’s version tree. |
| write() | Yield a staging path; publish it atomically on clean exit, discard it on error. |
get()
Return the published entry path (a file or a directory), or None on a miss.
Usage
get(key)get_bytes()
Read a published blob entry, or None on a miss.
Usage
get_bytes(key)key()
Derive a content address from a type-tagged, length-framed encoding of parts.
Usage
key(*parts)open()
Open (creating on first use) the cache tree for namespace at version, sweeping stale temps.
Usage
open(namespace, *, version, root=None)Pass root to override the settings cache_root for this cache only (a CLI --cache-dir flag, a throwaway test directory) without mutating the process-wide settings singleton.
put_bytes()
Atomically store data under key and return the published entry path.
Usage
put_bytes(key, data)stats()
Count the published entries and total bytes in this cache’s version tree.
Usage
stats()write()
Yield a staging path; publish it atomically on clean exit, discard it on error.
Usage
write(key)Write a single file at the yielded path for a blob entry, or mkdir it and fill it for a directory entry. Incremental producers append to the staging file across the block.
cache.CacheKey
A content-derived cache address (blake2b-128 hex digest).
Usage
cache.CacheKey(digest)Parameter Attributes
digest: str
cache.CacheStats
Entry and byte totals for one cache namespace.
Usage
cache.CacheStats(namespace, entries, bytes)Parameter Attributes
namespace: strentries: intbytes: int
cache.cached()
Decorate an async function to memoize its pickled result in Cache.open(ns, version=version).
Usage
cache.cached(*, ns, version)The key is the function’s qualified name plus a canonical encoding of the call arguments; arguments must be hashable primitives or tuples thereof, or CacheKeyError is raised.
Example
>>> @cached(ns="ocr", version=2)
... async def read(page: int) -> str: ...cache.stats_all()
Aggregate entry and byte totals for every namespace under cache_root (across all versions).
Usage
cache.stats_all()cache.CacheKeyError
Raised for an invalid cache address: a non-primitive argument, a bad namespace, or a malformed digest.
Usage
cache.CacheKeyError()