fleche.storage.base

Attributes

logger

Exceptions

SaveError	Common base class for all non-exit exceptions.
AmbiguousDigestError	Inappropriate argument value (of correct type).

Classes

KeyManagement	Abstract base providing key-management helpers for any keyed storage.
StorageBackend	Primitive backend interface for key-value storage.
ValueStorage	Abstract domain interface for value storage.
ValueMixin	Bridges ValueStorage with StorageBackend primitives.
Digested	Helper class that provides a standard way to create an ABC using
DigestedIterable	Helper class that provides a standard way to create an ABC using
DigestedDict	Helper class that provides a standard way to create an ABC using
DestructuringMixin	Mixin that recursively destructures collections on save/load.
CallStorage	Abstract domain interface for call storage.
CallMixin	Bridges CallStorage with StorageBackend primitives.

Module Contents

fleche.storage.base.logger

exception fleche.storage.base.SaveError

Bases: Exception

Common base class for all non-exit exceptions.

exception fleche.storage.base.AmbiguousDigestError

Bases: ValueError

Inappropriate argument value (of correct type).

class fleche.storage.base.KeyManagement

Bases: abc.ABC

Abstract base providing key-management helpers for any keyed storage.

Subclasses must implement list, _evict, and _contains. The concrete helpers evict, contains, expand, and shrink are implemented here once and inherited by all storage classes.

abstractmethod list() → Iterable[fleche.digest.Digest]

abstractmethod _evict(key: fleche.digest.Digest) → None

abstractmethod _contains(key: fleche.digest.Digest) → bool

evict(key: fleche.digest.Digest | str) → None

Removes the entry corresponding to the key from the storage.

contains(key: fleche.digest.Digest | str) → bool

expand(key: fleche.digest.Digest | str) → fleche.digest.Digest

Expands a short-hand digest to the full length one.

shrink(key: fleche.digest.Digest | str) → fleche.digest.Digest

Find the shortest substring that is still an unambiguous reference to the same value.

class fleche.storage.base.StorageBackend

Bases: KeyManagement

Primitive backend interface for key-value storage.

Backends implement the low-level put/get/_evict/list operations. Higher-level classes (ValueMixin, CallMixin) add domain-specific logic on top.

abstractmethod put(value: Any, key: fleche.digest.Digest) → fleche.digest.Digest

abstractmethod get(key: fleche.digest.Digest) → Any

_contains(key: fleche.digest.Digest) → bool

class fleche.storage.base.ValueStorage

Bases: KeyManagement

Abstract domain interface for value storage.

abstractmethod save(value: Any, key: fleche.digest.Digest | None = None) → fleche.digest.Digest

abstractmethod load(key: fleche.digest.Digest | str) → Any

class fleche.storage.base.ValueMixin

Bases: ValueStorage, StorageBackend

Bridges ValueStorage with StorageBackend primitives.

Implements save and load using put and get. Concrete classes inherit from this and a StorageBackend implementation to get a fully functional value storage.

save(value: Any, key: fleche.digest.Digest | None = None) → fleche.digest.Digest

load(key: fleche.digest.Digest | str) → Any

class fleche.storage.base.Digested

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstractmethod underlying()

Return plain underlying value, ie. list/dict/etc of nested values or their partial digests

__digest__()

abstractmethod mend(storage: DestructuringMixin)

classmethod sunder(intern: Callable[[Any], tuple[Any, int | float]], value: Any)

Abstractmethod:

static get(storage, key)

class fleche.storage.base.DigestedIterable

Bases: Digested

Helper class that provides a standard way to create an ABC using inheritance.

items: list | tuple

underlying()

Return plain underlying value, ie. list/dict/etc of nested values or their partial digests

mend(storage: DestructuringMixin) → list | tuple

classmethod sunder(intern: Callable[[Any], tuple[Any, int | float]], value: list | tuple)

class fleche.storage.base.DigestedDict

Bases: Digested

Helper class that provides a standard way to create an ABC using inheritance.

items: dict

underlying()

Return plain underlying value, ie. list/dict/etc of nested values or their partial digests

mend(storage: DestructuringMixin) → dict

classmethod sunder(intern: Callable[[Any], tuple[Any, int | float]], value: dict)

class fleche.storage.base.DestructuringMixin

Bases: StorageBackend

Mixin that recursively destructures collections on save/load.

Place before a concrete StorageBackend in the MRO to add destructuring behavior. Lists, tuples, and dicts are broken apart so each element is stored independently; on load the original structure is reassembled.

Example:

class DestructuringMemory(ValueMixin, DestructuringMixin, Memory):
    pass

dm = DestructuringMemory(storage={})
key = dm.save([1, [2, 3]])
assert dm.load(key) == [1, [2, 3]]

remaining_depth: int = 0

_intern_rec(value: Any, key: fleche.digest.Digest | None = None) → tuple[Any, int | float]

Post-order traversal: recurse to leaves, decide inline-vs-store on the way back up.

Returns (result, depth) where result is the plain value when depth < remaining_depth (the element is inlined in its parent’s Digested wrapper) or a Digest when the element was written to storage separately. Every node in the structure is visited exactly once (O(n)), unlike a separate depth-counting pass.

put(value: Any, key: fleche.digest.Digest) → fleche.digest.Digest

get(key: fleche.digest.Digest | Any) → Any

class fleche.storage.base.CallStorage

Bases: KeyManagement

Abstract domain interface for call storage.

abstractmethod save(call: fleche.call.Call) → fleche.digest.Digest

abstractmethod load(key: fleche.digest.Digest | str) → fleche.call.Call

abstractmethod query(template: fleche.call.QueryCall) → Iterable[fleche.call.Call]

transform(func: Callable[[fleche.call.Call], fleche.call.Call] | None = None) → None

Applies a transformation function to all Call objects in the storage.

Parameters:

func (Callable[[Call], Call] | None) – A function that takes a Call and returns a transformed Call. If None, the identity function is used (useful for re-calculating keys).

class fleche.storage.base.CallMixin

Bases: CallStorage, StorageBackend

Bridges CallStorage with StorageBackend primitives.

Implements save, load, and query using put and get, deriving the storage key from the call’s lookup key. transform is inherited from CallStorage.

Concrete classes inherit from this and a StorageBackend implementation to get a fully functional call storage.

save(call: fleche.call.Call) → fleche.digest.Digest

load(key: fleche.digest.Digest | str) → fleche.call.Call

query(template: fleche.call.QueryCall) → Iterable[fleche.call.Call]

Find cached calls that ‘match’ the template.

Returns all calls where the given arguments, results or metadata match exactly the stored ones. Values may be given either as they are or as Digest.

Parameters:

template (Call) – specification for calls to return; use None as wildcard.

Returns:

an iterable over all matching call objects

Return type:

Iterable[Call]