fleche.call
===========

.. py:module:: fleche.call


Attributes
----------

.. autoapisummary::

   fleche.call.AnyCall


Classes
-------

.. autoapisummary::

   fleche.call.Call
   fleche.call.DigestedCall
   fleche.call.LazyCall
   fleche.call.QueryCall


Functions
---------

.. autoapisummary::

   fleche.call.bind


Module Contents
---------------

.. py:function:: bind(func, args, kwargs, apply_defaults=False, partial=False)

   Thin wrapper around :meth:`inspect.Signature.bind` / :meth:`~inspect.Signature.bind_partial`.

   :param func: The callable whose signature to bind against.
   :param args: Positional arguments.
   :param kwargs: Keyword arguments.
   :param apply_defaults: If ``True``, fill in default values for parameters
                          that were not explicitly supplied.
   :param partial: If ``True``, use :meth:`~inspect.Signature.bind_partial`,
                   which allows required arguments to be omitted (treated as wildcards).

   :returns: :attr:`inspect.BoundArguments.arguments` — an ``OrderedDict``
             containing the supplied (and, when requested, defaulted) values.


.. py:class:: Call

   Represents a function call, capturing its name, arguments, and keyword arguments.

   `module` and `version` can be optionally set to be included in the hash of the call.
   `version` should be a plain integer and monotonically increase.  Each different version will completely change the
   hash of the call, invalidating previously cached results.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: arguments
      :type:  dict[str, Any]


   .. py:attribute:: metadata
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: module
      :type:  str | None
      :value: None



   .. py:attribute:: version
      :type:  str | int | None
      :value: None



   .. py:attribute:: code_digest
      :type:  str | None
      :value: None



   .. py:attribute:: result
      :type:  Any
      :value: None



   .. py:method:: from_call(func, *args, **kwargs)
      :classmethod:



   .. py:method:: to_lookup_key() -> fleche.digest.Digest


   .. py:method:: _to_digested(save_fn: Callable[[Any], fleche.digest.Digest]) -> DigestedCall

      Generic conversion to DigestedCall using *save_fn* to handle each value.



   .. py:method:: stash(values) -> DigestedCall

      Save arguments and result into *values*, returning a :class:`DigestedCall`.

      Result save errors propagate to the caller.  Argument save errors fall back
      to a digest-only reference (the value is hashed but not stored).

      :param values: A :class:`~fleche.storage.ValueStorage` instance to persist values into.

      :returns: A :class:`DigestedCall` with all argument values and the result replaced by
                their :class:`~fleche.digest.Digest` keys.

      .. seealso:: :meth:`digest` for a variant that does not write to storage.



   .. py:method:: digest() -> DigestedCall

      Digest arguments and result without saving to storage, returning a :class:`DigestedCall`.

      Equivalent to :meth:`stash` but uses :func:`~fleche.digest.digest` instead of
      ``values.save``, so no data is written anywhere.



.. py:class:: DigestedCall

   A Call where arguments and result are :class:`~fleche.digest.Digest` pointers into a value store.

   Produced by :meth:`Call.stash` or :meth:`Call.digest`; represents a call whose values have been
   replaced by their content-addressed keys.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: arguments
      :type:  dict[str, fleche.digest.Digest]


   .. py:attribute:: result
      :type:  fleche.digest.Digest | None
      :value: None



   .. py:attribute:: metadata
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: module
      :type:  str | None
      :value: None



   .. py:attribute:: version
      :type:  str | int | None
      :value: None



   .. py:attribute:: code_digest
      :type:  str | None
      :value: None



   .. py:method:: __eq__(other: object) -> bool


   .. py:method:: __digest__()


   .. py:method:: to_lookup_key() -> fleche.digest.Digest


   .. py:method:: fetch(cache) -> LazyCall

      Wrap this :class:`DigestedCall` in a :class:`LazyCall` backed by *cache*.

      :param cache: A cache instance (e.g. :class:`~fleche.caches.Cache`) whose value
                    storage will be used to load argument and result values on demand.

      :returns: A :class:`LazyCall` that loads values lazily from *cache*.



.. py:class:: LazyCall

   .. py:attribute:: name
      :type:  str


   .. py:attribute:: _arguments
      :type:  dict[str, Any]


   .. py:attribute:: _result
      :type:  Any


   .. py:attribute:: _cache
      :type:  Any


   .. py:attribute:: metadata
      :type:  dict[str, dict[str, Any]]


   .. py:attribute:: module
      :type:  str | None
      :value: None



   .. py:attribute:: version
      :type:  str | int | None
      :value: None



   .. py:attribute:: code_digest
      :type:  str | None
      :value: None



   .. py:property:: arguments


   .. py:property:: result


   .. py:method:: to_lookup_key() -> str


   .. py:method:: fetch() -> Call

      Reconstruct a full Call object by loading all values from the cache.



   .. py:method:: __digest__()


.. py:class:: QueryCall

   .. py:attribute:: name
      :type:  StrQueryType
      :value: None



   .. py:attribute:: arguments
      :type:  dict[str, AnyQueryType] | None
      :value: None



   .. py:attribute:: metadata
      :type:  dict[str, dict[str, StrQueryType]] | None
      :value: None



   .. py:attribute:: module
      :type:  str | None
      :value: None



   .. py:attribute:: version
      :type:  str | int | None
      :value: None



   .. py:attribute:: code_digest
      :type:  fleche.digest.Digest | None
      :value: None



   .. py:attribute:: result
      :type:  AnyQueryType
      :value: None



   .. py:method:: from_call(func, *args, **kwargs)
      :classmethod:



   .. py:method:: matches(other: Call | LazyCall | DigestedCall) -> bool

      Check if this call matches another call, treating None as a wildcard in this object.



.. py:data:: AnyCall