imf_reader.weo.api
==================

.. py:module:: imf_reader.weo.api

.. autoapi-nested-parse::

   IMF World Economic Outlook (WEO) API client.



Attributes
----------

.. autoapisummary::

   imf_reader.weo.api.SCALE_LABELS
   imf_reader.weo.api.SCALE_MULTIPLIERS


Functions
---------

.. autoapisummary::

   imf_reader.weo.api._fetch_version_mapping
   imf_reader.weo.api.get_weo_versions
   imf_reader.weo.api._fetch_codelist
   imf_reader.weo.api._align_schema
   imf_reader.weo.api._get_weo_data_cached
   imf_reader.weo.api.get_weo_data


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

.. py:data:: SCALE_LABELS

.. py:data:: SCALE_MULTIPLIERS

.. py:function:: _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"}


.. py:function:: 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)]


.. py:function:: _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.

   :param agency: The agency ID (e.g., "IMF", "IMF.RES")
   :param codelist_id: The codelist ID (e.g., "CL_UNIT", "CL_WEO_COUNTRY")

   :returns: Dict mapping codes to their labels.


.. py:function:: _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.

   :param df: DataFrame from API.

   :returns: DataFrame with old-style column names, labels, and correct data types.


.. py:function:: _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.


.. py:function:: 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.

   :param version: Version tuple (month, year) e.g. ("April", 2025). If None, uses latest.

   :returns: DataFrame with WEO data.