imf_reader.sdr
==============

.. py:module:: imf_reader.sdr

.. autoapi-nested-parse::

   Special Drawing Rights (SDR) reader module.

   This module offers access to the IMF's Special Drawing Rights (SDR) data.
   The SDR is an international reserve asset created by the IMF in 1969.
   It is not a currency, but the holder of SDRs can exchange them for usable currencies in times of need.

   Read more about SDRs at: https://www.imf.org/en/About/Factsheets/Sheets/2023/special-drawing-rights-sdr


   Usage:

   Import the module

   ```python
   from imf_reader import sdr
   ```

   Read allocations and holdings data

   ```python
   sdr.fetch_allocations_holdings()
   ```
   SDRs holdings and allocations are published at a monthly frequency. The function fetches the latest data available by
   default. Check the latest available date

   ```python
   sdr.fetch_latest_allocations_holdings_date()
   ```

   To retrieve SDR holdings and allocations for a specific month and year, eg April 2021, pass the year and month as a tuple

   ```python
   sdr.fetch_allocations_holdings((2021, 4))
   ```

   Read interest rates

   ```python
   sdr.fetch_interest_rates()
   ```

   Read exchange rates

   ```python
   sdr.fetch_exchange_rates()
   ```
   By default, the exchange rate is in USDs per 1 SDR. To get the exchange rate in SDRs per 1 USD, pass the unit basis as "USD"

   ```python
   sdr.fetch_exchange_rates("USD")
   ```

   Clear cached data

   ```python
   sdr.clear_cache()
   ```



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/imf_reader/sdr/clear_cache/index
   /autoapi/imf_reader/sdr/read_announcements/index
   /autoapi/imf_reader/sdr/read_exchange_rate/index
   /autoapi/imf_reader/sdr/read_interest_rate/index


Functions
---------

.. autoapisummary::

   imf_reader.sdr.fetch_interest_rates
   imf_reader.sdr.fetch_exchange_rates
   imf_reader.sdr.fetch_allocations_holdings
   imf_reader.sdr.fetch_latest_allocations_holdings_date
   imf_reader.sdr.clear_cache


Package Contents
----------------

.. py:function:: fetch_interest_rates() -> pandas.DataFrame

   Fetch the historic SDR interest rates from the IMF

   The SDR interest rate is based on the sum of the multiplicative products in SDR terms of the currency
   amounts in the SDR valuation basket, the level of the interest rate on the financial
   instrument of each component currency in the basket, and the exchange rate of each currency
   against the SDR. The SDR interest rate for the current week is released on Sunday morning, Washington D.C. time.

   :returns: A DataFrame with the  historical SDR interest rates


.. py:function:: fetch_exchange_rates(unit_basis: Literal['SDR', 'USD'] = 'SDR') -> pandas.DataFrame

   Fetch the historic SDR exchange rates from the IMF

   The currency value of the SDR is determined by summing the values in U.S. dollars, based on market exchange rates, of a basket of major currencies (the U.S. dollar, Euro, Japanese yen, pound sterling and the Chinese renminbi). The SDR currency value is calculated daily except on IMF holidays, or whenever the IMF is closed for business, or on an ad-hoc basis to facilitate unscheduled IMF operations. The SDR valuation basket is reviewed and adjusted every five years.

   Read more at: https://www.imf.org/en/About/Factsheets/Sheets/2023/special-drawing-rights-sdr

   :param unit_basis: The unit basis for the exchange rate. Default is "SDR" i.e. 1 SDR in USD. Other option is "USD" i.e. 1 USD in SDR

   :returns: A DataFrame with the exchange rate data


.. py:function:: fetch_allocations_holdings(date: tuple[int, int] | None = None) -> pandas.DataFrame

   Fetch SDR holdings and allocations data for a given date. If date is not specified, it fetches data for the latest date

   :param date: tuple[int, int]. The year and month to get allocations and holdings data for. e.g. (2024, 11) for November 2024.
   :param If None:
   :param the latest announcements released are fetched.:

   :returns: A dataframe with the SDR allocations and holdings data


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

   Get the latest available SDR allocation holdings date.
   :returns: A tuple containing the year and month of the latest SDR data.
   :rtype: tuple[int, int]


.. py:function:: clear_cache() -> None

   Clear the cache for all SDR data.

   .. deprecated:: 1.5.0
      Use :func:`imf_reader.cache.clear_cache` instead.