fleche.call =========== .. py:module:: fleche.call Attributes ---------- .. autoapisummary:: fleche.call.AnyCall Classes ------- .. autoapisummary:: fleche.call.Ignored fleche.call.Required fleche.call.FunctionProfile fleche.call.Call fleche.call.DigestedCall fleche.call.LazyCall fleche.call.QueryCall Functions --------- .. autoapisummary:: fleche.call.bind Module Contents --------------- .. py:class:: Ignored Type wrapper to mark a function argument as ignored for caching. Can be used as a type hint: ``arg: fleche.Ignored`` or ``arg: fleche.Ignored[int]``. .. py:method:: __class_getitem__(item) :classmethod: .. py:class:: Required Type wrapper to mark a function argument as required for caching. Arguments marked as required must be explicitly provided by the caller as keyword arguments (i.e. not via their default value) for the result to be cached. This is useful for arguments like random seeds or iteration counts, where using the default value might lead to non-deterministic or otherwise undesirable caching behavior. This is mainly useful when wrapping third-party functions where you do not control the default arguments. Can be used as a type hint: ``arg: fleche.Required`` or ``arg: fleche.Required[int]``. .. py:method:: __class_getitem__(item) :classmethod: .. py:class:: FunctionProfile All static per-function metadata, cached once per callable. .. py:attribute:: signature :type: inspect.Signature .. py:attribute:: qualname :type: str .. py:attribute:: module :type: str .. py:attribute:: version :type: str | int | None .. py:attribute:: code_digest :type: fleche.digest.Digest | None .. py:attribute:: ignored :type: frozenset[str] .. py:attribute:: required :type: frozenset[str] .. py:method:: of(func) -> FunctionProfile :classmethod: Compute a :class:`FunctionProfile` for *func* without caching. .. py:method:: strip_for_key(bound: dict) -> None Remove ignored arguments from a bound arguments dict in-place. .. py:method:: check_required(args: tuple, kwargs: dict) -> list[str] Return names of required args not explicitly provided as keyword arguments. .. 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:: detach() -> DigestedCall Return the cache-free :class:`DigestedCall` shadow of this :class:`LazyCall`. The inverse of :meth:`DigestedCall.fetch`: strips the ``_cache`` reference so the result can cross process boundaries (e.g. over the wire in :mod:`fleche.remote`) without carrying a live cache pointer. .. 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