imf_reader.cache.config

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

`ENV_VAR`
`_programmatic_override`
`_listeners`
`_clear_listeners`
`_cache_enabled`

Functions

`get_active_root`(→ pathlib.Path)	Return the resolved cache root, version-segmented. No I/O.
`get_http_cache_path`(→ pathlib.Path)	Return the HTTP-layer (requests-cache) sublayer directory.
`get_bulk_cache_dir`(→ pathlib.Path)	Return the WEO bulk-download (SDMX zip) sublayer directory.
`get_dataframe_cache_dir`(→ pathlib.Path)	Return the parsed-DataFrame sublayer directory.
`set_cache_dir`(→ None)	Override the cache root for this process.
`reset_cache_dir`(→ None)	Clear any programmatic override, restoring env-var or platformdirs default.
`register_listener`(→ None)	Register a callback fired with the new root whenever set_cache_dir or reset_cache_dir runs.
`unregister_listener`(→ None)	Remove a previously registered path-change listener.
`register_clear_listener`(→ None)	Register a callback fired by cache.clear_cache() after disk teardown.
`is_cache_enabled`(→ bool)	Return True if caching is currently enabled (the global toggle is on).
`_set_enabled`(→ None)	Flip the global cache-enabled toggle.
`_fire_listeners`(→ None)	Call every registered path-change listener with the current resolved root.

Module Contents

imf_reader.cache.config.ENV_VAR: str = 'IMF_READER_CACHE_DIR'

imf_reader.cache.config._programmatic_override: pathlib.Path | None = None

imf_reader.cache.config._listeners: list[collections.abc.Callable[[pathlib.Path], None]] = []

imf_reader.cache.config._clear_listeners: list[tuple[str, collections.abc.Callable[[], None]]] = []

imf_reader.cache.config._cache_enabled: bool = True

imf_reader.cache.config.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>.

imf_reader.cache.config.get_http_cache_path() → pathlib.Path: Return the HTTP-layer (requests-cache) sublayer directory.

imf_reader.cache.config.get_bulk_cache_dir() → pathlib.Path: Return the WEO bulk-download (SDMX zip) sublayer directory.

imf_reader.cache.config.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.

imf_reader.cache.config.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.

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

imf_reader.cache.config.reset_cache_dir() → None

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

Triggers all registered listeners with the restored root.

imf_reader.cache.config.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.

Parameters:: cb – Callable that receives the new resolved root Path.

imf_reader.cache.config.unregister_listener(cb: collections.abc.Callable[[pathlib.Path], None]) → None

Remove a previously registered path-change listener.

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

imf_reader.cache.config.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.

Parameters:

cb – Zero-arg callable called when the cache is cleared.
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.

imf_reader.cache.config.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.

imf_reader.cache.config._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.

Parameters:: flag – True to enable, False to disable.

imf_reader.cache.config._fire_listeners() → None: Call every registered path-change listener with the current resolved root.