fleche.storage.destructuring

Classes

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.

Module Contents

class fleche.storage.destructuring.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.destructuring.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.destructuring.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.destructuring.DestructuringMixin

Bases: fleche.storage.base.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

>>> from fleche.storage.base import ValueMixin
>>> from fleche.storage.memory import MemoryBackend
>>> @dataclass(frozen=True)
... class MyValueStorage(ValueMixin, DestructuringMixin, MemoryBackend): ...
>>> vm = MyValueStorage(storage={})
>>> key = vm.save([1, [2, 3]])
>>> vm.load(key) == [1, [2, 3]]
True

remaining_depth: int = 0

static _is_trojan_tuple(value)

_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

count_reuses() → collections.Counter[fleche.digest.Digest]

Return a counter of how many times each stored key is referenced as a sub-component.

Scans every raw entry and tallies Digest back-references found inside DigestedIterable and DigestedDict wrappers. A count of 0 means the key is not pointed to by any other stored value (i.e. a top-level entry). A count greater than 1 indicates a sub-value shared between multiple parent containers.

Returns:

A Counter mapping each Digest key to the number of times it is referenced by other stored entries.

Example

>>> from fleche.storage.memory import ValueMemory
>>> ds = ValueMemory(storage={})
>>> shared = [2, 3]
>>> _ = ds.save([1, shared])
>>> _ = ds.save([4, shared])
>>> hits = ds.count_reuses()
>>> hits[ds.save(shared)]  # [2, 3] is referenced by both outer lists
2