bblocks.import_tools.imf_weo
============================

.. py:module:: bblocks.import_tools.imf_weo

.. autoapi-nested-parse::

   Tools to import IMF World Economic Outlook data.



Attributes
----------

.. autoapisummary::

   bblocks.import_tools.imf_weo.BASE_URL
   bblocks.import_tools.imf_weo.COLUMN_MAPPER


Classes
-------

.. autoapisummary::

   bblocks.import_tools.imf_weo.Parser
   bblocks.import_tools.imf_weo.WEO


Functions
---------

.. autoapisummary::

   bblocks.import_tools.imf_weo._smdx_query_url
   bblocks.import_tools.imf_weo._parse_sdmx_query_response
   bblocks.import_tools.imf_weo.get_sdmx_href
   bblocks.import_tools.imf_weo.gen_latest_version
   bblocks.import_tools.imf_weo.roll_back_version
   bblocks.import_tools.imf_weo.extract_data


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

.. py:data:: BASE_URL
   :value: 'https://www.imf.org/'


.. py:data:: COLUMN_MAPPER

.. py:function:: _smdx_query_url(version: tuple[int, int]) -> str

   Generate the url for the SDMX query


.. py:function:: _parse_sdmx_query_response(content: requests.Response.content) -> str

   Parse the response from the SDMX query


.. py:function:: get_sdmx_href(version: tuple[int, int]) -> str | None

   retrieve the href for the SDMX file

   :param version: the version of the WEO data as a tuple of (year, version)
   :type version: tuple[int, int]


.. py:class:: Parser(folder: zipfile.ZipFile)

   Helper class to parse WEO data

   This class parses the data and schema files into a clean dataframe
   to be used in the main WEO class

   :param folder: the folder containing the data and schema files


   .. py:attribute:: folder
      :type:  zipfile.ZipFile


   .. py:attribute:: data_file
      :type:  xml.etree.ElementTree
      :value: None



   .. py:attribute:: schema_file
      :type:  xml.etree.ElementTree
      :value: None



   .. py:attribute:: data
      :type:  pandas.DataFrame | None
      :value: None



   .. py:method:: get_files() -> None

      Get the root of files



   .. py:method:: _extract_data() -> None

      extract data from data file



   .. py:method:: _convert_series_codes(series: pandas.Series, lookup_value: str) -> pandas.Series

      Converts a series of codes to the corresponding values in the schema file



   .. py:method:: _clean_data() -> None

      Clean and format the dataframe



   .. py:method:: parse_data() -> None

      Parse the data to a dataframe



   .. py:method:: get_data() -> pandas.DataFrame

      Get the data. If the data is not already parsed, parse it first



.. py:function:: gen_latest_version() -> tuple[int, int]

   Generates the latest expected version based on the current date


.. py:function:: roll_back_version(version: tuple[int, int]) -> tuple[int, int]

   Roll back version to the previous version


.. py:function:: extract_data(version) -> pandas.DataFrame | None

   Downloads latest data or data for specified version

   :param version: version to download
   :type version: tuple[int, int]


.. py:class:: WEO

   Bases: :py:obj:`bblocks.import_tools.common.ImportData`


   An object to extract WEO data from the IMF website using SDMX
   To use, create an instance of the class setting the version to the desired version,
   or leave blank to get the latest version.
   Call the load_data method to load the data to the object. If the data is already
   downloaded, it will load from disk, otherwise it will download the data.
   To force an update of the data, call the update_data method.
   To retrieve the data, call the get_data method.

   .. attribute:: version

      tuple of (year, release) or "latest". Default is "latest"


   .. py:attribute:: version
      :type:  str | tuple[int, int]
      :value: 'latest'



   .. py:method:: __post_init__()

      check that version is valid



   .. py:property:: _path

      Generate path based on version


   .. py:method:: _download_data() -> None

      Downloads latest data or data for specified version if not already available in disk

      If version is "latest" it will generate the expected version based on the current date
      and try download the data. If it is not available for the expected version, it will
      roll back the version and try again. If no data is found, it will raise an error.

      If version is a tuple of (year, release), it will try download the data for that version



   .. py:method:: load_data(indicators: str | list = 'all') -> bblocks.import_tools.common.ImportData

      Load data to object

      When called this method will load WEO indicators to the object.
      If the data is not downloaded, it will download the data. If the data is
      already downloaded, it will load the data from disk. If the version is set to
      'latest', it will find the latest version and download the data.

      :param indicators: The indicators to load. If 'all' is passed, all indicators will be loaded. Default is 'all'

      :returns: same object with data loaded



   .. py:method:: update_data(reload_data: bool = True) -> bblocks.import_tools.common.ImportData

      Update the data

      When called it will update the data used to load the indicators.
      If reload_data is True, it will reload the indicators to the object.

      :param reload_data: If True, reload the indicators after updating the data. Default is True.

      :returns: same object with updated data to allow chaining



   .. py:method:: available_indicators() -> dict[str, str]

      Returns a DataFrame of available indicators to load to the object



   .. py:method:: get_old_format_data() -> pandas.DataFrame

      This function returns the data in the old format that weo-reader returns

      NOTE: This will return all the data in the object in the old format, regardless of the indicators loaded
      Not all columns that existed in weo-reader are returned as they don't exist in the sdmx data files. However,
      this should not cause issues are they are metadata columns not used in analysis.