fleche.state

Attributes

_CACHE
_METADATA

Classes

_StickyContext	Context manager for sticky ContextVar state.
BoundWrapper	A plain callable that freezes cache and metadata state at construction time.

Functions

cache(…)	Manages the active cache for Fleche.
meta(→ contextlib.AbstractContextManager[None])	Manages the active metadata for Fleche.
tags(**kwargs)	A context manager to add arbitrary tags to results.
project(name)	A context manager to tag results with a project name.

Module Contents

fleche.state._CACHE: contextvars.ContextVar[fleche.caches.BaseCache]

class fleche.state._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.

__slots__ = ('_var', '_token')

_var

_token

__enter__() → None

__exit__(*args: object) → None

fleche.state.cache(new_cache: None = None, stack: bool = False) → fleche.caches.BaseCache

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

Parameters:

• new_cache – Cache object or named cache string to activate, or None to query.

• stack – If True, wrap new_cache in a CacheStack on top of the current cache.

Returns:

The current BaseCache when called without arguments, otherwise a _StickyContext context manager.

fleche.state._METADATA: contextvars.ContextVar[tuple[fleche.metadata.MetaData, Ellipsis]]

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

Parameters:

• *new_metadata – MetaData instances to activate.

• stack – If True, prepend the current metadata tuple before the new entries.

Returns:

A _StickyContext context manager.

fleche.state.tags(**kwargs)

A context manager to add arbitrary tags to results.

Parameters:

**kwargs – The tags to add to the results.

fleche.state.project(name)

A context manager to tag results with a project name.

Parameters:

name (str) – The name of the project.

class fleche.state.BoundWrapper

A plain callable that freezes cache and metadata state at construction time.

BoundWrapper is intentionally a minimal wrapper: it captures the active BaseCache and metadata tuple and restores them around every call to the wrapped function, but it does not expose the fleche helper namespace (digest, call, load, contains, query, rerun). Those helpers are available on the original decorated function.

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

func: Callable

cache: fleche.caches.BaseCache

meta: tuple[fleche.metadata.MetaData, Ellipsis]

classmethod bind(func)

Bind cache and metadata state.

Returns a plain callable that always executes as if called under the context in which bind() was originally invoked. The returned object is a BoundWrapper — a simple dataclass with a __call__ method — and does not carry the fleche helper namespace. To access helpers such as digest or query, use them on the original decorated function.

Parameters:

func (callable) – any callable; plain functions that only call fleche-wrapped ones are explicitly allowed

Returns:

instance with the bound cache and metadata state

Return type:

BoundWrapper

__call__(*args, **kwargs)