fleche

lru_cache on ‘roids.

Submodules

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

Attributes

__version__

Classes

BoundWrapper	Utility class that freezes global state for the cache and metadata config.
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. If new_cache is provided, it returns a context manager
meta(*new_metadata[, stack])
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.
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 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.

Parameters:

• new_cache (Optional[BaseCache]) – An optional Cache object to set as the active cache.

• stack (bool, default False) – if True, construct a CacheStack, with new_cache at the bottom

Returns:

The current cache object if new_cache is None, otherwise a context manager to set a new cache.

Return type:

Union[BaseCache, AbstractContextManager[None]]

fleche.meta(*new_metadata: fleche.metadata.MetaData, stack=False)

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

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)

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: - .call(*args, **kwargs): Get the :clas:`.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. - .rerun(*args, **kwargs): Forces reevaluation recursively. 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.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.