fleche.storage.base =================== .. py:module:: fleche.storage.base Attributes ---------- .. autoapisummary:: fleche.storage.base.logger Exceptions ---------- .. autoapisummary:: fleche.storage.base.SaveError fleche.storage.base.AmbiguousDigestError Classes ------- .. autoapisummary:: fleche.storage.base.StorageBase fleche.storage.base.Storage fleche.storage.base.Digested fleche.storage.base.DigestedIterable fleche.storage.base.DigestedDict fleche.storage.base.DestructuringMixin fleche.storage.base._DelegatingStorage fleche.storage.base.DestructuringStorage fleche.storage.base.CallStorage fleche.storage.base.CallStorageAdapter Module Contents --------------- .. py:data:: logger .. py:exception:: SaveError Bases: :py:obj:`Exception` Common base class for all non-exit exceptions. .. py:exception:: AmbiguousDigestError Bases: :py:obj:`ValueError` Inappropriate argument value (of correct type). .. py:class:: StorageBase Bases: :py:obj:`abc.ABC` Shared functionality between value and call storages. .. py:method:: list() -> Iterable[fleche.digest.Digest] :abstractmethod: .. py:method:: evict(key: fleche.digest.Digest | str) -> None Removes the entry corresponding to the key from the storage. .. py:method:: _evict(key: fleche.digest.Digest) -> None :abstractmethod: .. py:method:: expand(key: fleche.digest.Digest | str) -> fleche.digest.Digest Expands a short-hand digest to the full length one. .. py:method:: shrink(key: fleche.digest.Digest | str) -> fleche.digest.Digest Find the shortest substring that is still an unambigious reference to the same value. .. py:method:: contains(key: fleche.digest.Digest | str) -> bool .. py:method:: _contains(key: fleche.digest.Digest) -> bool :abstractmethod: .. py:class:: Storage Bases: :py:obj:`StorageBase` Abstract base class for defining storage mechanisms. .. py:method:: save(value: Any, key: fleche.digest.Digest | None = None) -> fleche.digest.Digest .. py:method:: _save(value: Any, key: fleche.digest.Digest) -> fleche.digest.Digest :abstractmethod: .. py:method:: load(key: fleche.digest.Digest | str) -> Any .. py:method:: _load(key: fleche.digest.Digest) -> Any :abstractmethod: .. py:method:: _contains(key: fleche.digest.Digest) -> bool .. py:class:: Digested Bases: :py:obj:`abc.ABC` Helper class that provides a standard way to create an ABC using inheritance. .. py:method:: underlying() :abstractmethod: Return plain underlying value, ie. list/dict/etc of nested values or their partial digests .. py:method:: __digest__() .. py:method:: mend(storage: DestructuringMixin) :abstractmethod: .. py:method:: sunder(intern: Callable[[Any], tuple[Any, int | float]], value: Any) :classmethod: :abstractmethod: .. py:class:: DigestedIterable Bases: :py:obj:`Digested` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: items :type: list | tuple .. py:method:: underlying() Return plain underlying value, ie. list/dict/etc of nested values or their partial digests .. py:method:: mend(storage: DestructuringMixin) -> list | tuple .. py:method:: sunder(intern: Callable[[Any], tuple[Any, int | float]], value: list | tuple) :classmethod: .. py:class:: DigestedDict Bases: :py:obj:`Digested` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: items :type: dict .. py:method:: underlying() Return plain underlying value, ie. list/dict/etc of nested values or their partial digests .. py:method:: mend(storage: DestructuringMixin) -> dict .. py:method:: sunder(intern: Callable[[Any], tuple[Any, int | float]], value: dict) :classmethod: .. py:class:: DestructuringMixin Bases: :py:obj:`Storage` Mixin that recursively destructures collections on save/load. Place before a concrete :class:`Storage` 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(DestructuringMixin, Memory): pass # ``storage`` here is the backing dict required by ``Memory``, not a # Storage instance. dm = DestructuringMemory(storage={}) key = dm.save([1, [2, 3]]) assert dm.load(key) == [1, [2, 3]] .. py:attribute:: remaining_depth :type: int :value: 0 .. py:method:: _intern_rec(value: Any) -> 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 :class:`Digested` wrapper) or a :class:`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. .. py:method:: _save(value: Any, key: fleche.digest.Digest) -> fleche.digest.Digest .. py:method:: _load(key: fleche.digest.Digest | Any) -> Any .. py:class:: _DelegatingStorage Bases: :py:obj:`Storage` Storage that delegates all operations to a wrapped storage instance. .. py:attribute:: storage :type: Storage .. py:method:: _save(value: Any, key: fleche.digest.Digest) -> fleche.digest.Digest .. py:method:: _load(key: fleche.digest.Digest) -> Any .. py:method:: _contains(key: fleche.digest.Digest) -> bool .. py:method:: _evict(key: fleche.digest.Digest) -> None .. py:method:: list() -> Iterable[fleche.digest.Digest] .. py:class:: DestructuringStorage Bases: :py:obj:`DestructuringMixin`, :py:obj:`_DelegatingStorage` Storage wrapper that recursively destructures collections. This is a convenience class combining :class:`DestructuringMixin` with delegation to a wrapped storage. Prefer using :class:`DestructuringMixin` directly as a mixin with a concrete storage class when possible. .. py:attribute:: remaining_depth :type: int :value: 0 .. py:method:: __post_init__() .. py:class:: CallStorage Bases: :py:obj:`StorageBase` Special storage for saving :class:`Call` instances. .. py:method:: save(call: fleche.call.Call) -> fleche.digest.Digest .. py:method:: _save(call: fleche.call.Call) -> fleche.digest.Digest :abstractmethod: .. py:method:: load(key: str | fleche.digest.Digest) -> fleche.call.Call .. py:method:: _load(key: fleche.digest.Digest) -> fleche.call.Call :abstractmethod: .. py:method:: transform(func: Callable[[fleche.call.Call], fleche.call.Call] | None = None) -> None Applies a transformation function to all Call objects in the storage. :param func: A function that takes a Call and returns a transformed Call. If None, the identity function is used (useful for re-calculating keys). :type func: Callable[[Call], Call] | None .. py:method:: 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 :class:`Digest`. :param template: specification for calls to return; use `None` as wildcard. :type template: Call :returns: an iterable over all matching call objects :rtype: Iterable[Call] .. py:method:: _contains(key: fleche.digest.Digest) -> bool .. py:class:: CallStorageAdapter Bases: :py:obj:`CallStorage` Implement a CallStorage from a generic Storage. .. py:attribute:: storage :type: Storage .. py:method:: _save(call: fleche.call.Call) -> fleche.digest.Digest .. py:method:: _load(key: fleche.digest.Digest) -> fleche.call.Call .. py:method:: _contains(key: fleche.digest.Digest) -> bool .. py:method:: _evict(key: fleche.digest.Digest) -> None .. py:method:: list() -> Iterable[fleche.digest.Digest]