imf_reader.weo.api

IMF World Economic Outlook (WEO) API client.

Attributes

`SCALE_LABELS`
`SCALE_MULTIPLIERS`

Functions

`_fetch_version_mapping`(→ dict[imf_reader.weo.Version, str])	Fetch mapping of Version tuples to API version strings.
`get_weo_versions`(→ list[imf_reader.weo.Version])	Fetch all available WEO versions from the IMF API.
`_fetch_codelist`(→ dict[str, str])	Fetch a codelist from the IMF API and return as a code->label mapping.
`_align_schema`(→ pandas.DataFrame)	Align the schema of the DataFrame to match the old SDMX format.
`_get_weo_data_cached`(→ pandas.DataFrame)	Inner cached fetch — keyed on a resolved (month, year) tuple.
`get_weo_data`(→ pandas.DataFrame)	Fetch WEO data for a specific version.

Module Contents

imf_reader.weo.api.SCALE_LABELS

imf_reader.weo.api.SCALE_MULTIPLIERS

imf_reader.weo.api._fetch_version_mapping() → dict[imf_reader.weo.Version, str]

Fetch mapping of Version tuples to API version strings.

Results are cached for 1 hour to avoid redundant HTTP calls (F10).

Returns:: Dict mapping (month, year) tuples to API version strings. e.g. {(“October”, 2025): “9.0.0”, (“April”, 2025): “6.0.0”}

imf_reader.weo.api.get_weo_versions() → list[imf_reader.weo.Version]

Fetch all available WEO versions from the IMF API.

Returns:: List of Version tuples (month, year) sorted newest first. e.g. [(“October”, 2025), (“April”, 2025)]

imf_reader.weo.api._fetch_codelist(agency: str, codelist_id: str) → dict[str, str]

Fetch a codelist from the IMF API and return as a code->label mapping.

Results are cached locally to avoid repeated API calls.

Parameters:

agency – The agency ID (e.g., “IMF”, “IMF.RES”)
codelist_id – The codelist ID (e.g., “CL_UNIT”, “CL_WEO_COUNTRY”)

Returns:

Dict mapping codes to their labels.

imf_reader.weo.api._align_schema(df: pandas.DataFrame) → pandas.DataFrame

Align the schema of the DataFrame to match the old SDMX format.

Renames columns, adds label columns for codes, and fixes data types.

Parameters:: df – DataFrame from API.
Returns:: DataFrame with old-style column names, labels, and correct data types.

imf_reader.weo.api._get_weo_data_cached(version: imf_reader.weo.Version) → pandas.DataFrame

Inner cached fetch — keyed on a resolved (month, year) tuple.

Splitting the cache from the public get_weo_data ensures that version=None is mapped to the current latest release before the cache lookup. Otherwise the wrapper would cache under None for 7 days and keep serving the previous release even after the version-mapping TTL (1 hour) sees a new one.

imf_reader.weo.api.get_weo_data(version: imf_reader.weo.Version | None = None) → pandas.DataFrame

Fetch WEO data for a specific version.

Data is cached locally to avoid repeated API calls. Use clear_cache() to clear.

Parameters:: version – Version tuple (month, year) e.g. (“April”, 2025). If None, uses latest.
Returns:: DataFrame with WEO data.