bblocks.import_tools.sdr
========================

.. py:module:: bblocks.import_tools.sdr


Attributes
----------

.. autoapisummary::

   bblocks.import_tools.sdr.BASE_URL
   bblocks.import_tools.sdr.MAIN_PAGE_URL
   bblocks.import_tools.sdr.EXCHANGE_URL


Classes
-------

.. autoapisummary::

   bblocks.import_tools.sdr.SDR


Functions
---------

.. autoapisummary::

   bblocks.import_tools.sdr.create_tsv_link
   bblocks.import_tools.sdr.get_response
   bblocks.import_tools.sdr.parse_sdr_links
   bblocks.import_tools.sdr.get_latest_date
   bblocks.import_tools.sdr.clean_df
   bblocks.import_tools.sdr.read_tsv
   bblocks.import_tools.sdr.get_data
   bblocks.import_tools.sdr.format_date
   bblocks.import_tools.sdr.check_if_not_downloaded
   bblocks.import_tools.sdr.__get_rate
   bblocks.import_tools.sdr.__get_exchange_date
   bblocks.import_tools.sdr.parse_exchange
   bblocks.import_tools.sdr.get_latest_exchange_rate


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

.. py:data:: BASE_URL
   :value: 'https://www.imf.org/external/np/fin/tad/'


.. py:data:: MAIN_PAGE_URL
   :value: 'https://www.imf.org/external/np/fin/tad/extsdr1.aspx'


.. py:data:: EXCHANGE_URL
   :value: 'https://www.imf.org/external/np/fin/data/rms_sdrv.aspx'


.. py:function:: create_tsv_link(year: int, month: int, day: int) -> str

   Generate a TSV download link for a specific date


.. py:function:: get_response(url: str) -> requests.models.Response

   Request a response from a url


.. py:function:: parse_sdr_links(response: bytes) -> dict

   Function to parse SDR tables. returns a dictionary of dates and links


.. py:function:: get_latest_date() -> str

   Get the latest available date


.. py:function:: clean_df(df: pandas.DataFrame, date: str) -> pandas.DataFrame

   Clean the SDR dataframe


.. py:function:: read_tsv(url: str) -> pandas.DataFrame

   Read a tsv file from a url and return a dataframe


.. py:function:: get_data(date: str) -> pandas.DataFrame

   Get the SDR _data for a specific date


.. py:function:: format_date(date: list | tuple) -> str

   Format a date string containing year and month, and adds the last day for that month-year


.. py:function:: check_if_not_downloaded(date: str) -> bool

   Checks if _data is already downloaded for an indicator and area grouping
   :returns: True if _data is not downloaded, False if _data is downloaded


.. py:function:: __get_rate(table: bs4.BeautifulSoup, currency: str) -> float

   Returns currency value from SDR exchange rate table


.. py:function:: __get_exchange_date(table: bs4.BeautifulSoup) -> str

   Returns date of exchange rate table


.. py:function:: parse_exchange(response: bytes, currency: str) -> tuple[str, float]

   Parse the exchange rate response


.. py:function:: get_latest_exchange_rate(currency: str = 'USD', only_value: bool = False) -> float | dict

   Get the latest exchange rate for a specific currency

   :param currency: Currency to get exchange rate for. Default is USD. Choose from 'USD' or 'SDR'
   :param only_value: If False, a dictionary containing the date and exchange rate is returned.
                      If True, only the exchange rate is returned. Default is False.

   :returns: A dictionary containing the date and exchange rate, or only the exchange rate


.. py:class:: SDR

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


   An object to import SDR data

   An object to help extract and store the latest Special Drawing Rights (SDR)
   data from the IMF website: https://www.imf.org/external/np/fin/tad/extsdr1.aspx

   In order to use, create an instance of this class.
   Then, call the `load_data` method to load SDR _data for a specific date. If no date is provided,
   the latest date will be found and loaded.
   Call `latest_date` to get the latest date available.
   If the data for a specific date has never been downloaded, it will be downloaded. If it has been downloaded,
   it will be loaded from disk. You can force an update by calling `update_data` if you
   want to refresh the data stored on disk and in the object.
   Call `get_data` to get the data as a DataFrame.



   .. py:attribute:: __latest_date
      :type:  str
      :value: None



   .. py:method:: __repr__()


   .. py:method:: latest_date()

      Return the latest date of the _data



   .. py:method:: load_data(date: str | tuple = 'latest') -> bblocks.import_tools.common.ImportData

      Load the SDR _data for a specific date

      :returns: the same object to allow chaining



   .. py:method:: update_data(reload: bool) -> bblocks.import_tools.common.ImportData

      Update the data stored on disk and in the object

      :returns: the same object to allow chaining



   .. py:method:: get_data(date: str = None, indicator: str = None) -> pandas.DataFrame

      Get SDR _data as a DataFrame

      :param date: the date of the _data to be retrieved. If no date is provided, _data for all dates will be retrieved
                   If 'latest' is provided, all the _data will be returned.
      :param indicator: the indicator to be retrieved, choose from ['holdings', 'allocations].
                        If no indicator is provided, all the indicators will be returned.

      :returns: a DataFrame containing the SDR _data