fleche.config
=============

.. py:module:: fleche.config

.. autoapi-nested-parse::

   Configuration system for fleche.

   Example cache.toml:

   [default]
   cache = "mycache"
   metadata = ["Runtime", "CallInfo"]

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

   [transient]
   values.type = "CloudpickleFile"
   values.root = ".fleche/values"
   calls.type = "CloudpickleFile"
   calls.root = ".fleche/calls"

   [global]
   values.type = "BagOfHoldingH5File"
   values.root = "~/.fleche/values"
   calls.type = "CloudpickleFile"
   calls.root = "~/.fleche/calls"



Attributes
----------

.. autoapisummary::

   fleche.config.logger
   fleche.config._live_caches


Functions
---------

.. autoapisummary::

   fleche.config._load_config
   fleche.config._get_config_path
   fleche.config.load_default_metadata
   fleche.config.storage_from_config
   fleche.config._get_storage
   fleche.config.storage_to_config
   fleche.config.cache_from_config
   fleche.config.cache_to_config
   fleche.config._create_cache
   fleche.config.load_cache_config


Module Contents
---------------

.. py:data:: logger

.. py:data:: _live_caches
   :type:  dict[str, fleche.caches.Cache]

.. py:function:: _load_config(path: pathlib.Path) -> dict[str, Any]

.. py:function:: _get_config_path() -> pathlib.Path | None

.. py:function:: load_default_metadata()

   Load the default metadata from the configuration file.


.. py:function:: storage_from_config(d: dict[str, Any]) -> fleche.storage.Storage

   Construct a :class:`~fleche.storage.Storage` from a config dict.

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

   Supported types: ``"Memory"``, ``"Void"``, ``"DestructuringStorage"``,
   ``"PickleFile"``, ``"CloudpickleFile"``, ``"DillFile"``,
   ``"BagOfHoldingH5File"``, ``"Sql"``.


.. py:function:: _get_storage(config: dict[str, Any]) -> fleche.storage.Storage

   Deprecated: use :func:`storage_from_config` instead.


.. py:function:: storage_to_config(s: fleche.storage.Storage | fleche.storage.CallStorage) -> dict[str, Any]

   Convert a Storage or CallStorage instance to a config dict.

   The returned dict contains a ``"type"`` key and any additional parameters
   needed to reconstruct the storage via :func:`storage_from_config`.
   :class:`~fleche.storage.DestructuringStorage` is handled as a first-class
   case, producing a nested ``"storage"`` entry for its inner backend.

   Accepts both :class:`~fleche.storage.Storage` and bare
   :class:`~fleche.storage.CallStorage` instances (e.g. ``Sql``), since ``Sql``
   implements ``CallStorage`` directly without going through
   ``CallStorageAdapter``.


.. py:function:: cache_from_config(d: dict[str, Any] | list[dict[str, Any]]) -> fleche.caches.BaseCache

   Construct a :class:`~fleche.caches.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 :class:`~fleche.caches.CacheStack`,
     with each element processed recursively.
   - A **dict** containing a ``max_size`` key creates a
     :class:`~fleche.caches.SizeLimitedCache`.
   - A **dict** containing ``read_only: true`` wraps the resulting cache in a
     :class:`~fleche.caches.ReadOnlyCache`.
   - Otherwise a plain :class:`~fleche.caches.Cache` is created.

   The ``values`` storage is always wrapped in a
   :class:`~fleche.storage.DestructuringStorage` if it is not already one.
   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"}},
       ])


.. py:function:: cache_to_config(c: fleche.caches.BaseCache) -> dict[str, Any] | list[dict[str, Any]]

   Convert a :class:`~fleche.caches.BaseCache` to a config dict or list.

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

   - :class:`~fleche.caches.Cache` → dict with ``"values"`` and ``"calls"``
   - :class:`~fleche.caches.SizeLimitedCache` → same dict plus ``"max_size"``
   - :class:`~fleche.caches.ReadOnlyCache` wrapping a ``Cache`` or
     ``SizeLimitedCache`` → inner cache dict with ``"read_only": True``
   - :class:`~fleche.caches.CacheStack` → list of dicts

   ``values`` is serialised as-is (a ``DestructuringStorage`` wrapper is
   preserved in the output).  ``calls`` unwraps the
   :class:`~fleche.storage.CallStorageAdapter`.

   :raises ValueError: for unsupported cache types or unsupported
       ``ReadOnlyCache`` inner types.


.. py:function:: _create_cache(cache_config: dict[str, Any]) -> fleche.caches.Cache

.. py:function:: load_cache_config(name: str | None = None) -> fleche.caches.Cache

   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.