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



   .. py:method:: __digest__()


.. py:class:: DigestedIterable

   Bases: :py:obj:`Digested`


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


   .. py:attribute:: items
      :type:  Iterable


   .. py:method:: underlying()


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


.. py:class:: DestructuringStorage

   Bases: :py:obj:`Storage`


   Abstract base class for defining storage mechanisms.


   .. 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:: 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.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.Call) -> 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]