imf_reader.cache.config
=======================

.. py:module:: imf_reader.cache.config

.. autoapi-nested-parse::

   CacheConfig singleton for imf_reader.

   Resolution order for the cache root (precedence rule I4):
   1. The most recent set_cache_dir(...) call (programmatic override) until reset_cache_dir() clears it.
   2. The IMF_READER_CACHE_DIR env var if no programmatic override is active.
   3. platformdirs.user_cache_dir("imf_reader", appauthor=False).

   The resolved base is always followed by /<package_version> so every package
   upgrade gets a fresh cache directory automatically (F2/F17).



Attributes
----------

.. autoapisummary::

   imf_reader.cache.config.ENV_VAR
   imf_reader.cache.config._programmatic_override
   imf_reader.cache.config._listeners
   imf_reader.cache.config._clear_listeners
   imf_reader.cache.config._cache_enabled


Functions
---------

.. autoapisummary::

   imf_reader.cache.config.get_active_root
   imf_reader.cache.config.get_http_cache_path
   imf_reader.cache.config.get_bulk_cache_dir
   imf_reader.cache.config.get_dataframe_cache_dir
   imf_reader.cache.config.set_cache_dir
   imf_reader.cache.config.reset_cache_dir
   imf_reader.cache.config.register_listener
   imf_reader.cache.config.unregister_listener
   imf_reader.cache.config.register_clear_listener
   imf_reader.cache.config.is_cache_enabled
   imf_reader.cache.config._set_enabled
   imf_reader.cache.config._fire_listeners


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

.. py:data:: ENV_VAR
   :type:  str
   :value: 'IMF_READER_CACHE_DIR'


.. py:data:: _programmatic_override
   :type:  pathlib.Path | None
   :value: None


.. py:data:: _listeners
   :type:  list[collections.abc.Callable[[pathlib.Path], None]]
   :value: []


.. py:data:: _clear_listeners
   :type:  list[tuple[str, collections.abc.Callable[[], None]]]
   :value: []


.. py:data:: _cache_enabled
   :type:  bool
   :value: True


.. py:function:: get_active_root() -> pathlib.Path

   Return the resolved cache root, version-segmented. No I/O.

   Resolution order (precedence rule I4):
   1. The most recent set_cache_dir(...) call until reset_cache_dir() clears it.
   2. The IMF_READER_CACHE_DIR env var if no programmatic override is active.
   3. platformdirs.user_cache_dir("imf_reader", appauthor=False).

   Always followed by /<imf_reader package version>.


.. py:function:: get_http_cache_path() -> pathlib.Path

   Return the HTTP-layer (requests-cache) sublayer directory.


.. py:function:: get_bulk_cache_dir() -> pathlib.Path

   Return the WEO bulk-download (SDMX zip) sublayer directory.


.. py:function:: get_dataframe_cache_dir() -> pathlib.Path

   Return the parsed-DataFrame sublayer directory.

   Note: imf_reader writes parsed DataFrames into per-domain sublayers
   (``sdr``, ``weo_api``, ``weo_sdmx_parsed``). This helper returns the
   SDR sublayer for parity with ``oda_reader._cache.config``; use
   ``get_active_root() / "<sublayer>"`` for the WEO variants.


.. py:function:: set_cache_dir(path: str | pathlib.Path) -> None

   Override the cache root for this process.

   Triggers all registered listeners with the new root. No I/O at the old
   path. Overrides any IMF_READER_CACHE_DIR env-var setting until
   reset_cache_dir() runs.

   :param path: New cache root base (version segment is appended automatically).


.. py:function:: reset_cache_dir() -> None

   Clear any programmatic override, restoring env-var or platformdirs default.

   Triggers all registered listeners with the restored root.


.. py:function:: register_listener(cb: collections.abc.Callable[[pathlib.Path], None]) -> None

   Register a callback fired with the new root whenever set_cache_dir or reset_cache_dir runs.

   :param cb: Callable that receives the new resolved root Path.


.. py:function:: unregister_listener(cb: collections.abc.Callable[[pathlib.Path], None]) -> None

   Remove a previously registered path-change listener.

   :param cb: The callback to remove. No-op if not registered.


.. py:function:: register_clear_listener(cb: collections.abc.Callable[[], None], *, sublayer: str) -> None

   Register a callback fired by cache.clear_cache() after disk teardown.

   Used for in-memory state cleanup (e.g. LRU caches that mirror disk state).
   The umbrella only fires callbacks whose sublayer is part of the cleared
   scope, so a scope='sdr' clear cannot reach into weo_api or http state.

   :param cb: Zero-arg callable called when the cache is cleared.
   :param sublayer: Sublayer name this callback belongs to (e.g. "sdr", "weo_api",
                    "http"). Must match one of the sublayers registered in the umbrella's
                    scope mapping.


.. py:function:: is_cache_enabled() -> bool

   Return True if caching is currently enabled (the global toggle is on).

   :returns: True when caching is active, False when disable_cache() has been called.


.. py:function:: _set_enabled(flag: bool) -> None

   Flip the global cache-enabled toggle.

   Called by cache.enable_cache() / cache.disable_cache() in the umbrella.
   Not part of the public surface — use the umbrella functions instead.

   :param flag: True to enable, False to disable.


.. py:function:: _fire_listeners() -> None

   Call every registered path-change listener with the current resolved root.