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

.. py:module:: fleche.wrapper


Classes
-------

.. autoapisummary::

   fleche.wrapper.Ignored
   fleche.wrapper.Required
   fleche.wrapper.ArgumentPolicy


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:class:: ArgumentPolicy

   Encapsulates the ignored/required argument policy for a cached function.


   .. py:attribute:: ignored
      :type:  frozenset[str]


   .. py:attribute:: required
      :type:  frozenset[str]


   .. py:method:: strip_for_key(bound: dict) -> None

      Remove ignored arguments from a bound arguments dict in-place.



   .. py:method:: check_required(func, args: tuple, kwargs: dict) -> list[str]

      Return names of required args not explicitly provided as keyword arguments.



.. py:function:: fleche(_func=None, *, version: 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:
   - .call(*args, **kwargs): Get the :clas:`.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.
   - .rerun(*args, **kwargs): Forces reevaluation recursively.
   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.