fleche.config

Configuration system for fleche.

Storage type names

The type key in a storage config dict is case-sensitive and uses the following lowercase identifiers:

"memory": In-memory dict (ValueMemory / CallMemory). No required keys. Optional (value backend): remaining_depth (int, default 0).
"void": No-op — discards all data (ValueVoid / CallVoid). No required keys. Optional (value backend): remaining_depth (int, default 0).
"pickle": Filesystem backend serialised with the standard pickle module (ValuePickleFile / CallPickleFile). Required: root (path to storage directory). Optional: compress (bool, default False) — gzip-compress files. Optional: lock_timeout (float, default 1.0) — write-lock wait timeout (s). Optional: lock_wait_start (float, default 0.001) — initial lock-poll interval for exponential backoff (s). Optional (value backend): remaining_depth (int, default 0).
"cloudpickle": Filesystem backend serialised with cloudpickle — handles more complex Python objects than pickle. Required: root. Optional: compress (bool, default False) — gzip-compress files. Optional: lock_timeout (float, default 1.0) — write-lock wait timeout (s). Optional: lock_wait_start (float, default 0.001) — initial lock-poll interval for exponential backoff (s). Optional (value backend): remaining_depth (int, default 0).
"dill": Filesystem backend serialised with dill. Required: root. Optional: compress (bool, default False) — gzip-compress files. Optional: lock_timeout (float, default 1.0) — write-lock wait timeout (s). Optional: lock_wait_start (float, default 0.001) — initial lock-poll interval for exponential backoff (s). Optional (value backend): remaining_depth (int, default 0).
"bagofholding_hdf": HDF5-backed storage via the bagofholding library (ValueBagOfHoldingH5File / CallBagOfHoldingH5File). Required: root. Optional: lock_timeout (float, default 1.0) — write-lock wait timeout (s). Optional: lock_wait_start (float, default 0.001) — initial lock-poll interval for exponential backoff (s). Optional (value backend): remaining_depth (int, default 0).
"sql": SQL database via SQLAlchemy (Sql). Call storage only. Required: url (SQLAlchemy connection URL, e.g. "sqlite:///~/.fleche/calls.db"). Optional: echo (bool, default False) — log SQL statements.

Example fleche.toml

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

[persistent]
values.type = "cloudpickle"
values.root = "~/.fleche/values"
calls.type = "cloudpickle"
calls.root = "~/.fleche/calls"

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

[with_sql_calls]
values.type = "cloudpickle"
values.root = "~/.fleche/values"
calls.type = "sql"
calls.url = "sqlite:///~/.fleche/calls.db"

Attributes

`logger`
`_live_caches`
`_STORAGE_NAME_MAPPING`
`_STORAGE_CLASS_TO_NAME`

Functions

`_load_config`(→ dict[str, Any])
`_get_config_path`(→ pathlib.Path \| None)
`load_default_metadata`()	Load the default metadata from the configuration file.
`storage_from_config`(…)	Construct a `StorageBackend` from a config dict.
`storage_to_config`(→ dict[str, Any])	Convert a Storage instance to a config dict (inverse of `storage_from_config`).
`cache_from_config`(→ fleche.caches.BaseCache)	Construct a `BaseCache` from a config dict or list.
`cache_to_config`(→ dict[str, Any] \| list[dict[str, Any]])	Convert a `BaseCache` to a config dict or list.
`_create_cache`(→ fleche.caches.Cache)
`load_cache_config`(→ fleche.caches.Cache)	Load a cache from the configuration file.

Module Contents

fleche.config.logger[source]

fleche.config._live_caches: dict[str, fleche.caches.Cache][source]

fleche.config._load_config(path: pathlib.Path) → dict[str, Any][source]

fleche.config._get_config_path() → pathlib.Path | None[source]

fleche.config.load_default_metadata()[source]: Load the default metadata from the configuration file.

fleche.config._STORAGE_NAME_MAPPING[source]

fleche.config._STORAGE_CLASS_TO_NAME: dict[type, str][source]

fleche.config.storage_from_config(d: dict[str, Any], type: Literal['call']) → fleche.storage.CallStorage[source]

fleche.config.storage_from_config(d: dict[str, Any], type: Literal['value']) → fleche.storage.ValueStorage

Construct a StorageBackend from a config dict.

The dict must contain a "type" key (case-sensitive, lowercase) and any additional parameters required by that storage backend. The input dict is not mutated.

Supported type values and their parameters:

{"type": "memory"}
{"type": "void"}
{"type": "pickle", "root": "<path>"} — optional: compress, lock_timeout, lock_wait_start, remaining_depth (value only)
{"type": "cloudpickle", "root": "<path>"} — same optional keys as "pickle"
{"type": "dill", "root": "<path>"} — same optional keys as "pickle"
{"type": "bagofholding_hdf", "root": "<path>"} — optional: lock_timeout, lock_wait_start, remaining_depth (value only)
{"type": "sql", "url": "<sqlalchemy-url>"} (call storage only) — optional: echo

See the module docstring for full descriptions of each key.

fleche.config.storage_to_config(s: fleche.storage.ValueStorage | fleche.storage.CallStorage) → dict[str, Any][source]

Convert a Storage instance to a config dict (inverse of storage_from_config).

The returned dict contains a "type" key and any additional parameters needed to reconstruct the storage via storage_from_config().

fleche.config.cache_from_config(d: dict[str, Any] | list[dict[str, Any]]) → fleche.caches.BaseCache[source]

Construct a BaseCache from a config dict or list.

The cache type is determined implicitly from the shape of the input:

A list of dicts is treated as a CacheStack, with each element processed recursively.
A dict containing a max_size key creates a SizeLimitedCache.
A dict containing read_only: true wraps the resulting cache in a ReadOnlyCache.
Otherwise a plain Cache is created.

The input dict is not mutated.

Examples:

# Plain cache with in-memory storage
cache_from_config({
    "values": {"type": "memory"},
    "calls": {"type": "memory"},
})

# Size-limited cache — presence of max_size selects SizeLimitedCache
cache_from_config({
    "values": {"type": "memory"},
    "calls": {"type": "memory"},
    "max_size": 100,
})

# Read-only cache — read_only: true wraps the cache in ReadOnlyCache
cache_from_config({
    "values": {"type": "memory"},
    "calls": {"type": "memory"},
    "read_only": True,
})

# CacheStack — a list of dicts is implicitly treated as a stack
cache_from_config([
    {"values": {"type": "memory"}, "calls": {"type": "memory"}},
    {"values": {"type": "void"}, "calls": {"type": "void"}},
])

fleche.config.cache_to_config(c: fleche.caches.BaseCache) → dict[str, Any] | list[dict[str, Any]][source]

Convert a BaseCache to a config dict or list.

This is the inverse of cache_from_config(). The output can be round-tripped back via cache_from_config(cache_to_config(cache)).

Cache → dict with "values" and "calls"
SizeLimitedCache → same dict plus "max_size"
ReadOnlyCache wrapping a Cache or SizeLimitedCache → inner cache dict with "read_only": True
CacheStack → list of dicts

Raises:: ValueError – for unsupported cache types or unsupported ReadOnlyCache inner types.

fleche.config._create_cache(cache_config: dict[str, Any]) → fleche.caches.Cache[source]

fleche.config.load_cache_config(name: str | None = None) → fleche.caches.Cache[source]

Load a cache from the configuration file.

If name is None, the default cache is loaded. The names ‘memory’ and ‘void’ are special-cased to return a transient in-memory cache and a no-op cache respectively.

Note: The Tags metadata cannot be configured from the config file.