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

.. py:module:: fleche.state


Attributes
----------

.. autoapisummary::

   fleche.state._CACHE
   fleche.state._METADATA


Classes
-------

.. autoapisummary::

   fleche.state.BoundWrapper


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


.. py:class:: BoundWrapper

   Utility class that freezes global state for the cache and metadata config.

   Essentially acts like an early binding closure.

   This is intended to enable passing around fleche-decorated functions in pickled form by baking in the state into the
   pickle on request.


   .. py:attribute:: func
      :type:  Callable


   .. py:attribute:: cache
      :type:  fleche.caches.BaseCache


   .. py:attribute:: meta
      :type:  tuple[fleche.metadata.MetaData, Ellipsis]


   .. py:method:: bind(func)
      :classmethod:


      Bind cache and metadata state.

      Returns a new callable that will behave always as if run under the context under which :meth:`.bind()` was
      originally called.

      :param func: any callable; plain functions that only call fleche-wrapped ones are explicitly allowed
      :type func: callable

      :returns: instance with the bound cache and metadata state
      :rtype: :class:`.BoundWrapper`



   .. py:method:: __call__(*args, **kwargs)