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

.. py:module:: imf_reader.cache

.. autoapi-nested-parse::

   Public API for the imf_reader cache subpackage.

   Provides a unified interface for cache management across all imf_reader
   sub-modules (WEO, SDR).

   Usage::

       import imf_reader.cache as cache

       cache.clear_cache()                # clear everything
       cache.clear_cache(scope="weo")     # clear only WEO sublayers
       cache.set_cache_dir("/tmp/my_cache")
       cache.reset_cache_dir()
       print(cache.get_cache_dir())
       cache.disable_cache()
       cache.enable_cache()



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/imf_reader/cache/config/index
   /autoapi/imf_reader/cache/dataframe/index
   /autoapi/imf_reader/cache/http/index
   /autoapi/imf_reader/cache/legacy/index
   /autoapi/imf_reader/cache/manager/index


Attributes
----------

.. autoapisummary::

   imf_reader.cache.get_cache_dir


Exceptions
----------

.. autoapisummary::

   imf_reader.cache.BulkPayloadCorruptError


Functions
---------

.. autoapisummary::

   imf_reader.cache.get_bulk_cache_dir
   imf_reader.cache.get_dataframe_cache_dir
   imf_reader.cache.get_http_cache_path
   imf_reader.cache.reset_cache_dir
   imf_reader.cache.set_cache_dir
   imf_reader.cache.clear_cache
   imf_reader.cache.enable_cache
   imf_reader.cache.disable_cache


Package Contents
----------------

.. py:exception:: BulkPayloadCorruptError

   Bases: :py:obj:`Exception`


   Raised when a cached or freshly-downloaded bulk payload (e.g., the WEO SDMX zip) fails
   integrity validation. The corrupt cache entry is removed before this is raised, so the next
   call re-downloads cleanly.


.. 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:: get_http_cache_path() -> pathlib.Path

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


.. 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:: 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:data:: get_cache_dir

.. py:function:: clear_cache(scope: Literal['all', 'weo', 'sdr', 'http'] = 'all') -> None

   Clear cached data for the named scope.

   :param scope: Which sublayers to remove.

                 - ``"all"`` (default) — remove every immediate subdir of the cache root.
                   Uses a filesystem walk so future sublayers are automatically included
                   (avoids the F1 failure mode of silently leaking newly-added sublayers).
                 - ``"weo"`` — remove ``weo_sdmx``, ``weo_sdmx_parsed``, and ``weo_api``.
                 - ``"sdr"`` — remove the ``sdr`` sublayer.
                 - ``"http"`` — remove the ``http`` sublayer.


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

   Re-enable caching after a previous disable_cache() call.

   Has no effect if caching is already enabled.


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

   Disable caching for this process.

   All decorated functions bypass both the read and write cache paths and call
   through to the underlying function directly.  Has no effect on already-cached
   data on disk.