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

Every public operation enters _operation_context() around the compound work it performs, so mixins can inject an operation-scoped resource (e.g. a threading lock, a SQLAlchemy session, a file handle) without overriding every method individually.

_operation_context(key: fleche.digest.Digest | str)

Context manager entered around every operation on key.

The base implementation is a no-op. Override in a mixin to inject any resource scoped to the operation — a threading lock, a SQLAlchemy session, an open file handle, a decompression stream, etc.

Receiving key lets implementations choose between a single global resource (ignore the key) or per-key resources (e.g. a striped lock table or a key-specific file handle).

Composing multiple mixins: use super() to chain so that every mixin in the MRO gets to wrap the operation:

@contextlib.contextmanager
def _operation_context(self, key):
    with self._lock:                   # this mixin's resource
        with super()._operation_context(key):
            yield

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.

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

Expand a short digest prefix to a full key, or wrap a full key as Digest.

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