Configuration

fleche looks for a configuration file in the following order:

  1. fleche.toml in the current working directory (local config)

  2. A global config file, determined by the first matching rule:

    • If $XDG_CONFIG_HOME is set: $XDG_CONFIG_HOME/fleche/cache.toml

    • Otherwise, if $HOME is set: $HOME/.fleche.toml

    • Otherwise: ~/.fleche.toml

The first file found is used. If no configuration file exists, fleche falls back to a default in-memory cache.

Reserved Cache Names

memory

The name memory is a reserved cache name. When requested, fleche will provide a transient in-memory cache. This cache is persistent for the duration of the process, but is not shared with other processes and is lost when the current process exits.

Example:

from fleche import cache
with cache("memory"):
    # Results will be cached in memory. The cache persists for the lifetime of the process.
    ...

void

The name void is a reserved cache name. When requested, fleche will provide a no-op cache that discards all stored values. This is useful for disabling caching entirely without changing your code.

Example:

from fleche import cache
with cache("void"):
    # Results will not be cached at all. Every call executes the function.
    ...

The [default] section

The [default] section is used to configure the default behavior of fleche.

cache

The cache key specifies the name of the default cache to use.

Example:

[default]
cache = "mycache"

metadata

The metadata key specifies the default metadata chain to use. This is a list of strings, where each string is the name of a metadata class from the fleche.metadata module.

Example:

[default]
metadata = ["Runtime"]

Note: The Tags metadata cannot be configured from the config file, as it requires arguments.

Cache sections

You can define multiple cache configurations in the same file, each in its own section.

Each cache section must define two storage backends: values and calls. values is used to store the results of function calls, and calls is used to store the function call details.

Storage backends

Each storage backend is configured using a type key, see the table below. Other keys in the same dict are passed as keyword arguments to the storage constructor.

Example:

[mycache]
values.type = "memory"
calls.type = "memory"

Available storage types

"memory"

Stores data in an in-memory dictionary (ValueMemory / CallMemory). No required keys. Optional (value backend): remaining_depth — see Destructuring below.

"void"

No-op backend — discards all data (ValueVoid / CallVoid). No required keys. Optional (value backend): remaining_depth — see Destructuring below.

"pickle"

Stores data as files on the filesystem using the standard pickle module (ValuePickleFile / CallPickleFile). Required: root — path to the storage directory. Optional: compress (bool, default false) — gzip-compress each stored file. Optional: lock_timeout (float, default 1.0) — maximum seconds to wait for a concurrent write lock before attempting a read anyway. Optional: lock_wait_start (float, default 0.001) — initial wait interval (seconds) for exponential backoff while polling the write lock. Optional (value backend): remaining_depth — see Destructuring below.

"cloudpickle"

Same filesystem backend as "pickle", but serialised with cloudpickle. Handles more complex Python objects (lambdas, closures, etc.). Required: root. Optional: compress (bool, default false) — gzip-compress each stored file. Optional: lock_timeout (float, default 1.0) — maximum seconds to wait for a concurrent write lock before attempting a read anyway. Optional: lock_wait_start (float, default 0.001) — initial wait interval (seconds) for exponential backoff while polling the write lock. Optional (value backend): remaining_depth — see Destructuring below.

"dill"

Same filesystem backend as "pickle", but serialised with dill. Required: root. Optional: compress (bool, default false) — gzip-compress each stored file. Optional: lock_timeout (float, default 1.0) — maximum seconds to wait for a concurrent write lock before attempting a read anyway. Optional: lock_wait_start (float, default 0.001) — initial wait interval (seconds) for exponential backoff while polling the write lock. Optional (value backend): remaining_depth — see Destructuring below.

"bagofholding_hdf"

Stores data in HDF5 files using the bagofholding library (ValueBagOfHoldingH5File / CallBagOfHoldingH5File). Required: root. Optional: lock_timeout (float, default 1.0) — maximum seconds to wait for a concurrent write lock before attempting a read anyway. Optional: lock_wait_start (float, default 0.001) — initial wait interval (seconds) for exponential backoff while polling the write lock. Optional (value backend): remaining_depth — see Destructuring below.

"sql"

Stores call metadata in a SQL database via SQLAlchemy (Sql). Intended for call storage only. Required: url — a SQLAlchemy connection URL, e.g. "sqlite:///~/.fleche/calls.db". Optional: echo (bool, default false) — if true, log all SQL statements (useful for debugging).

Destructuring

All value backends except "sql" (which is call-only) store collections (list, tuple, dict) by destructuring them: each element is stored independently under its own cache key, and on load the original structure is reassembled. This avoids redundant storage of shared sub-structures across different cached calls.

The optional remaining_depth key (integer, default 0) controls the granularity:

  • remaining_depth = 0 — maximum splitting: every element at every nesting level is stored as a separate entry.

  • remaining_depth = N (positive) — elements at nesting levels shallower than N are stored inline within their parent entry rather than as separate entries. For example, remaining_depth = 1 inlines scalars within their parent list or dict so each top-level collection is stored as a single entry.

Higher values mean fewer, larger storage entries and less structural sharing between calls.

Example:

[mycache]
values.type = "cloudpickle"
values.root = "~/.cache/fleche/values"
values.remaining_depth = 1   # inline scalars; one entry per top-level collection
calls.type = "cloudpickle"
calls.root = "~/.cache/fleche/calls"

Full Configuration Example

Below is an example of a complete configuration file demonstrating several features:

[default]
cache = "persistent"
metadata = ["Runtime"]

[persistent]
# Store values as cloudpickle files
values.type = "cloudpickle"
values.root = "~/.cache/fleche/values"

# Store call details as cloudpickle files
calls.type = "cloudpickle"
calls.root = "~/.cache/fleche/calls"

[fast]
# Simple in-memory cache
values.type = "memory"
calls.type = "memory"

[hdf5_values]
# HDF5 values backend with SQL call index
values.type = "bagofholding_hdf"
values.root = "~/.cache/fleche/hdf5_values"
calls.type = "sql"
calls.url = "sqlite:///~/.cache/fleche/calls.db"