## Cache


## cache.Cache


A namespaced, versioned, content-keyed blob/directory cache under `cache_root`.


Usage

``` python
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: str`  

`version: int`  

`root: Path`  


#### Example

``` python
>>> cache = Cache.open("frames", version=1)
>>> path = await cache.put_bytes(cache.key("clip", 7), jpeg)
```


#### Methods

| Name | Description |
|----|----|
| [get()](#athome.cache.Cache.get) | Return the published entry path (a file or a directory), or `None` on a miss. |
| [get_bytes()](#athome.cache.Cache.get_bytes) | Read a published blob entry, or `None` on a miss. |
| [key()](#athome.cache.Cache.key) | Derive a content address from a type-tagged, length-framed encoding of `parts`. |
| [open()](#athome.cache.Cache.open) | Open (creating on first use) the cache tree for `namespace` at `version`, sweeping stale temps. |
| [put_bytes()](#athome.cache.Cache.put_bytes) | Atomically store `data` under [key](cache.md#athome.cache.Cache.key) and return the published entry path. |
| [stats()](#athome.cache.Cache.stats) | Count the published entries and total bytes in this cache's version tree. |
| [write()](#athome.cache.Cache.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

``` python
get(key)
```


##### get_bytes()


Read a published blob entry, or `None` on a miss.


Usage

``` python
get_bytes(key)
```


##### key()


Derive a content address from a type-tagged, length-framed encoding of `parts`.


Usage

``` python
key(*parts)
```


##### open()


Open (creating on first use) the cache tree for `namespace` at `version`, sweeping stale temps.


Usage

``` python
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](cache.md#athome.cache.Cache.key) and return the published entry path.


Usage

``` python
put_bytes(key, data)
```


##### stats()


Count the published entries and total bytes in this cache's version tree.


Usage

``` python
stats()
```


##### write()


Yield a staging path; publish it atomically on clean exit, discard it on error.


Usage

``` python
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

``` python
cache.CacheKey(digest)
```


#### Parameter Attributes


`digest: str`  


## cache.CacheStats


Entry and byte totals for one cache namespace.


Usage

``` python
cache.CacheStats(namespace, entries, bytes)
```


#### Parameter Attributes


`namespace: str`  

`entries: int`  

`bytes: int`  


## cache.cached()


Decorate an async function to memoize its pickled result in `Cache.open(ns, version=version)`.


Usage

``` python
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](cache.md#athome.cache.CacheKeyError) is raised.


#### Example

``` python
>>> @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

``` python
cache.stats_all()
```


## cache.CacheKeyError


Raised for an invalid cache address: a non-primitive argument, a bad namespace, or a malformed digest.


Usage

``` python
cache.CacheKeyError()
```