sift_client.util.cache ¶

User-facing surface for the shared on-disk cache.

This module hosts the small bag of methods exposed as client.cache, plus the :class:CacheStats snapshot type returned by :meth:CacheNamespace.stats. Both classes are public — they're re-exported from the top-level sift_client package and surfaced in the generated API docs.

The cache itself (a :class:~sift_client._internal.disk_cache.DiskCache) lives on :class:~sift_client.client.SiftClient so every resource that wants to persist results across calls can reach into one shared store. The namespace deliberately mirrors :class:DiskCache rather than the old per-resource API (client.channels.enable_data_cache_disk(...)): since the store is shared, configuration is global.

CLASS	DESCRIPTION
`CacheStats`	Snapshot of the shared on-disk cache at call time.
`CacheNamespace`	Resource-agnostic surface for the on-disk cache shared by all resources.

logger `module-attribute` ¶

logger = logging.getLogger(__name__)

CacheStats `dataclass` ¶

CacheStats(
    enabled: bool,
    path: str | None,
    max_bytes: int | None,
    size_bytes: int,
    entry_count: int,
    channel_buckets: int,
    channel_segments: int,
)

Snapshot of the shared on-disk cache at call time.

Returned by :meth:CacheNamespace.stats. Frozen dataclass so it plays well with logging, snapshot tests, and "compare two readings" diagnostics without surprise mutation.

Field semantics:

enabled — whether the disk handle is open. When False, all the size/count fields are zero regardless of on-disk state.
path — directory the cache is open against, or None when disabled. Useful for "where does this cache actually live?".
max_bytes — configured byte cap on disk usage, or None when disabled. diskcache's LRU evicts once usage approaches this.
size_bytes — current on-disk usage including SQLite overhead. Tends to trend slightly higher than the sum of per-entry size_bytes the resources hand to the store.
entry_count — total cache keys across all adapter prefixes (channel index + segment rows, plus any future foreign-adapter rows).
channel_buckets — number of distinct (channel_id, run_id) channel buckets currently cached. Counted by walking the channel adapter's index keys; one index per bucket regardless of how many segments live under it.
channel_segments — total cached segment frames across every bucket. Each put_segment call adds one; diskcache LRU evictions can drop them independently of their parent index, so this can be lower than the sum of segments the adapter has written over the session.

str(stats) prints a multi-line summary suitable for notebook/REPL display; the structured fields are available for programmatic checks.

ATTRIBUTE	DESCRIPTION
`enabled`	TYPE: `bool`
`path`	TYPE: `str \| None`
`max_bytes`	TYPE: `int \| None`
`size_bytes`	TYPE: `int`
`entry_count`	TYPE: `int`
`channel_buckets`	TYPE: `int`
`channel_segments`	TYPE: `int`

enabled `instance-attribute` ¶

enabled: bool

path `instance-attribute` ¶

path: str | None

max_bytes `instance-attribute` ¶

max_bytes: int | None

size_bytes `instance-attribute` ¶

size_bytes: int

entry_count `instance-attribute` ¶

entry_count: int

channel_buckets `instance-attribute` ¶

channel_buckets: int

channel_segments `instance-attribute` ¶

channel_segments: int

CacheNamespace ¶

CacheNamespace(client: SiftClient)

Resource-agnostic surface for the on-disk cache shared by all resources.

Exposed as client.cache. The actual handle (:class:~sift_client._internal.disk_cache.DiskCache) is constructed lazily on first use so importing :mod:sift_client doesn't pay the diskcache cost up front. Configuration changes made before that first use are recorded against the client's :class:~sift_client._internal.disk_cache_config.DiskCacheConfig and applied when the store opens; changes after first use are routed directly to the live store.

Default policy: disk caching is opt-out (the config is constructed with enabled=True). Users who don't want any state on disk call :meth:disable to silence it; users who want a custom location or byte cap call :meth:enable with arguments.

Bind this namespace to client. Constructed by :class:SiftClient.

METHOD	DESCRIPTION
`enable`	Enable (or reconfigure) on-disk caching.
`disable`	Opt out of on-disk caching (no reads or writes).
`stats`	Return a snapshot of the current cache state.
`clear`	Delete a previously-persisted on-disk cache directory.

enable ¶

enable(
    *,
    path: str | PathLike[str] | None = None,
    max_bytes: int | None = None,
) -> None

Enable (or reconfigure) on-disk caching.

Disk caching is on by default at :attr:~sift_client._internal.disk_cache.DiskCache.DEFAULT_DISK_PATH; use this method to override the path or size, or to turn the cache back on after a prior :meth:disable call.

Reconfiguring a live cache (different path or max_bytes) closes the previous handle and opens a new one. Existing entries at the new path become available as cache hits.

An explicit path that can't be opened (permission denied, read-only filesystem, ...) raises so the caller knows their request didn't take. The default-path open does not raise — see :meth:SiftClient._get_disk_cache for the silent fall-back.

PARAMETER	DESCRIPTION
`path`	Directory to persist to. `None` (the default) uses the cache's :attr:`DEFAULT_DISK_PATH`. TYPE: `str \| PathLike[str] \| None` DEFAULT: `None`
`max_bytes`	Byte cap on disk usage. `None` uses the cache's :attr:`DEFAULT_DISK_MAX_BYTES` (4 GiB). When the bound is reached, `diskcache`'s LRU eviction takes over. TYPE: `int \| None` DEFAULT: `None`

Example

client.cache.enable(path="/data/sift-cache") client.cache.enable(max_bytes=1024 ** 3) # 1 GiB

disable ¶

disable() -> None

Opt out of on-disk caching (no reads or writes).

Caching is on by default; call this when you don't want any cached data written to or read from disk. Closes any open cache file handle. The on-disk directory is NOT deleted — use :meth:clear to wipe it.

stats ¶

stats() -> CacheStats

Return a snapshot of the current cache state.

Calling this triggers the lazy disk-handle open if it hasn't happened yet (so a stats call on a fresh client doesn't mis-report as disabled just because no resource has touched the store). After the open it's read-only — no mutation or migration.

Channel-specific counts come from walking the keyspace once and counting keys under the channel adapter's namespace prefix. If a second cache-aware resource grows its own key prefix later, extend this method to surface per-adapter counts; for now there's only one adapter so the dedicated field stays flat.

Example

print(client.cache.stats()) Sift cache: path: /tmp/sift-data-cache used: 142.3 MiB / 4.0 GiB (3.5%) channels: 12 buckets, 487 segments entries: 499 total

clear ¶

clear(path: str | PathLike[str] | None = None) -> None

Delete a previously-persisted on-disk cache directory.

Drops stale caches from previous sessions, recovers from a corrupt cache, or reclaims disk space. Removes the directory entirely; if disk caching is on, the next access re-opens an empty cache at the same path.

PARAMETER	DESCRIPTION
`path`	Directory of the cache to clear. `None` (the default) targets the cache's :attr:`~sift_client._internal.disk_cache.DiskCache.DEFAULT_DISK_PATH`. TYPE: `str \| PathLike[str] \| None` DEFAULT: `None`

RAISES	DESCRIPTION
`ValueError`	If `path` exists but does not look like a sift data cache directory.

sift_client.util.cache ¶

logger module-attribute ¶

CacheStats dataclass ¶

enabled instance-attribute ¶

path instance-attribute ¶

max_bytes instance-attribute ¶

size_bytes instance-attribute ¶

entry_count instance-attribute ¶

channel_buckets instance-attribute ¶

channel_segments instance-attribute ¶