fleche
======

.. py:module:: fleche

.. autoapi-nested-parse::

   lru_cache on 'roids.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/fleche/caches/index
   /autoapi/fleche/call/index
   /autoapi/fleche/config/index
   /autoapi/fleche/digest/index
   /autoapi/fleche/metadata/index
   /autoapi/fleche/security/index
   /autoapi/fleche/state/index
   /autoapi/fleche/storage/index
   /autoapi/fleche/wrapper/index


Classes
-------

.. autoapisummary::

   fleche.Ignored
   fleche.Required


Functions
---------

.. autoapisummary::

   fleche.cache
   fleche.meta
   fleche.tags
   fleche.project
   fleche.fleche


Package Contents
----------------

.. py:function:: cache(new_cache: None = None, stack: bool = False) -> fleche.caches.BaseCache
                 cache(new_cache: fleche.caches.BaseCache | str, stack: bool = False) -> contextlib.AbstractContextManager[None]

   Manages the active cache for Fleche. If `new_cache` is provided, it returns a context manager
   that sets the cache for the duration of the context. If `new_cache` is None, it returns
   the currently active cache.

   :param new_cache: An optional Cache object to set as the active cache.
   :type new_cache: Optional[BaseCache]
   :param stack: if True, construct a CacheStack, with new_cache at the bottom
   :type stack: bool, default False

   :returns:     The current cache object if `new_cache` is `None`, otherwise a context manager to set a new cache.
   :rtype: Union[:class:`.BaseCache`, AbstractContextManager[None]]


.. py:function:: meta(*new_metadata: fleche.metadata.MetaData, stack=False)

.. py:function:: tags(**kwargs)

   A context manager to add arbitrary tags to results.

   :param \*\*kwargs: The tags to add to the results.


.. py:function:: project(name)

   A context manager to tag results with a project name.

   :param name: The name of the project.
   :type name: str


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


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