fleche.wrapper
==============

.. py:module:: fleche.wrapper


Classes
-------

.. autoapisummary::

   fleche.wrapper.Ignored
   fleche.wrapper.Required


Functions
---------

.. autoapisummary::

   fleche.wrapper.fleche


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:function:: fleche(_func=None, *, version: str | int | None = None, meta: tuple[fleche.metadata.MetaData, Ellipsis] = (), hash_version: bool = True, hash_module: bool = True, hash_code: bool = False, require: None | str | list[str] | tuple[str] = None, ignore: None | str | list[str] | tuple[str] = None, isolate: bool = False)

   Cache decorator for functions.

   The decorated function is enhanced with helper methods, accessible either directly
   on the wrapped function or bundled under a ``.fleche`` :class:`types.SimpleNamespace`
   (e.g. ``f.fleche.call(...)`` is equivalent to ``f.call(...)``):

   - .call(*args, **kwargs): Get the :class:`.Call` object.
   - .digest(*args, **kwargs): Get the cache key.
   - .load(*args, **kwargs): Load result from cache.
   - .contains(*args, **kwargs): Check if result is in cache.
   - .query(*args, **kwargs): Return matching calls from the active cache.
   - .rerun(*args, **kwargs): Forces reevaluation recursively.
   - .bind(*args, **kwargs): Create a :class:`.BoundWrapper` that freezes the current cache/metadata state.
     Optionally pre-applies *args*/*kwargs* via :func:`functools.partial`.
   The original function is available via .__wrapped__.

   .. warning::

       ``isolate=True`` is **not thread-safe**.  Internally it calls
       :func:`os.chdir`, which is a process-wide POSIX syscall shared by all
       threads.  Concurrent calls with ``isolate=True`` from multiple threads
       will clobber each other's working directory, and a thread may find its
       temporary directory deleted before it has finished using it.

       Use ``isolate=True`` only from a single thread, or run isolated calls
       in separate processes (e.g. via :class:`concurrent.futures.ProcessPoolExecutor`)
       where each process has its own working directory.