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

.. py:module:: fleche.state


Attributes
----------

.. autoapisummary::

   fleche.state._CACHE
   fleche.state._METADATA


Classes
-------

.. autoapisummary::

   fleche.state._StickyContext
   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:class:: _StickyContext(var: contextvars.ContextVar, token: contextvars.Token)

   Context manager for sticky ContextVar state.

   The value is set immediately on construction; entering the ``with``-block is a
   no-op, and exiting restores the previous value via the stored token.

   In Python 3.14+, ``Token`` objects returned by ``ContextVar.set()`` support the
   context manager protocol natively, making this class unnecessary.  It serves as
   a backport for earlier Python versions.


   .. py:attribute:: __slots__
      :value: ('_var', '_token')



   .. py:attribute:: _var


   .. py:attribute:: _token


   .. py:method:: __enter__() -> None


   .. py:method:: __exit__(*args: object) -> None


.. 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 ``None``, returns the currently active cache.

   Otherwise, immediately sets ``new_cache`` as the active cache and returns a context manager.
   When used in a ``with`` statement the previous cache is restored on exit; when the returned
   context manager is discarded the new cache remains active (sticky behaviour).

   :param new_cache: Cache object or named cache string to activate, or ``None`` to query.
   :param stack: If ``True``, wrap ``new_cache`` in a :class:`.CacheStack` on top of the current cache.

   :returns: The current :class:`.BaseCache` when called without arguments, otherwise a
             :class:`._StickyContext` context manager.


.. py:data:: _METADATA
   :type:  contextvars.ContextVar[tuple[fleche.metadata.MetaData, Ellipsis]]

.. py:function:: meta(*new_metadata: fleche.metadata.MetaData, stack=False) -> contextlib.AbstractContextManager[None]

   Manages the active metadata for Fleche.

   Immediately sets ``new_metadata`` as the active metadata and returns a context manager.
   When used in a ``with`` statement the previous metadata is restored on exit; when the
   returned context manager is discarded the new metadata remains active (sticky behaviour).

   :param \*new_metadata: :class:`.MetaData` instances to activate.
   :param stack: If ``True``, prepend the current metadata tuple before the new entries.

   :returns: A :class:`._StickyContext` context manager.


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