fleche

lru_cache on ‘roids.

Submodules

• fleche.caches
• fleche.call
• fleche.config
• fleche.digest
• fleche.executor
• fleche.metadata
• fleche.query
• fleche.security
• fleche.state
• fleche.storage
• fleche.wrapper

Attributes

__version__

Classes

BoundWrapper	A plain callable that freezes cache and metadata state at construction time.
Ignored	Type wrapper to mark a function argument as ignored for caching.
Required	Type wrapper to mark a function argument as required for caching.

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.
fleche([_func, version, meta, hash_version, ...])	Cache decorator for functions.
wrap_executor(executor)	Monkey-patch executor.submit to intercept fleche-wrapped functions.
D(→ digest.Digest)	Convenience wrapper to create a Digest from a value.

Package Contents

fleche.__version__ = 'unknown'

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

fleche.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.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.tags(**kwargs)

A context manager to add arbitrary tags to results.

Parameters:

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

fleche.project(name)

A context manager to tag results with a project name.

Parameters:

name (str) – The name of the project.

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

fleche.fleche(_func=None, *, version: int | None = None, meta: tuple[fleche.metadata.MetaData, Ellipsis] = (), hash_version: bool = True, hash_module: bool = True, hash_code: bool = False, require: None | str | list[str] | tuple[str] = None, ignore: None | str | list[str] | tuple[str] = None, isolate: bool = False)

Cache decorator for functions.

The decorated function is enhanced with helper methods, accessible either directly on the wrapped function or bundled under a .fleche types.SimpleNamespace (e.g. f.fleche.call(...) is equivalent to f.call(...)):

• .call(*args, **kwargs): Get the Call object.

• .digest(*args, **kwargs): Get the cache key.

• .load(*args, **kwargs): Load result from cache.

• .contains(*args, **kwargs): Check if result is in cache.

• .query(*args, **kwargs): Return matching calls from the active cache.

• .rerun(*args, **kwargs): Forces reevaluation recursively.

• .bind(args, **kwargs): Create a :class:`.BoundWrapper` that freezes the current cache/metadata state. Optionally pre-applies *args/kwargs via functools.partial().

The original function is available via .__wrapped__.

Warning

isolate=True is not thread-safe. Internally it calls os.chdir(), which is a process-wide POSIX syscall shared by all threads. Concurrent calls with isolate=True from multiple threads will clobber each other’s working directory, and a thread may find its temporary directory deleted before it has finished using it.

Use isolate=True only from a single thread, or run isolated calls in separate processes (e.g. via concurrent.futures.ProcessPoolExecutor) where each process has its own working directory.

class fleche.Ignored

Type wrapper to mark a function argument as ignored for caching.

Can be used as a type hint: arg: fleche.Ignored or arg: fleche.Ignored[int].

classmethod __class_getitem__(item)

class fleche.Required

Type wrapper to mark a function argument as required for caching.

Arguments marked as required must be explicitly provided by the caller as keyword arguments (i.e. not via their default value) for the result to be cached. This is useful for arguments like random seeds or iteration counts, where using the default value might lead to non-deterministic or otherwise undesirable caching behavior.

This is mainly useful when wrapping third-party functions where you do not control the default arguments.

Can be used as a type hint: arg: fleche.Required or arg: fleche.Required[int].

classmethod __class_getitem__(item)

fleche.wrap_executor(executor)

Monkey-patch executor.submit to intercept fleche-wrapped functions.

Calling wrap_executor() on an executor that is already wrapped is a no-op: the patch is not stacked, and the original submit continues to refer to the pre-wrap method.

Parameters:

executor – any object with a submit(func, *args, **kwargs) method (e.g. concurrent.futures.Executor subclass instances).

Returns:

The same executor instance, with a replaced submit attribute.

fleche.D(value) → digest.Digest

Convenience wrapper to create a Digest from a value.

If given a non-empty string that is a valid hexadecimal string of at most DIGEST_LENGTH characters, wraps it in a Digest directly (allowing short hex prefixes for use with expand()). For any other value — including strings that are not valid hex digests — computes the digest.

Warning

Passing an arbitrary string to D() will silently compute its digest rather than treating the string as a digest identifier. Only strings that consist entirely of hexadecimal characters (0-9, a-f, A-F) and are no longer than DIGEST_LENGTH characters are used verbatim. If you intend to look up a cached value by its digest string, make sure the string you pass satisfies those constraints; otherwise you will get the digest of the string itself, which is almost certainly not what you want.

Digests passed as arguments to @fleche decorated functions are automatically expanded to their cached values.