fleche.state
============

.. py:module:: fleche.state


Attributes
----------

.. autoapisummary::

   fleche.state._CACHE
   fleche.state._METADATA


Functions
---------

.. autoapisummary::

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


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

.. py:data:: _CACHE
   :type:  contextvars.ContextVar[fleche.caches.BaseCache]

.. 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:data:: _METADATA
   :type:  contextvars.ContextVar[tuple[fleche.metadata.MetaData, Ellipsis]]

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