fleche.state

Attributes

_CACHE
_METADATA

Classes

_StickyContext	Context manager for sticky ContextVar state.
BoundWrapper	Utility class that freezes global state for the cache and metadata config.

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

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.

func: Callable

cache: fleche.caches.BaseCache

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

classmethod bind(func)

Bind cache and metadata state.

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

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)