Skip to content

hdx.location.currency

module hdx.location.currency

Currency conversion

Classes

  • CurrencyError

  • Currency — Currency class for performing currency conversion. Uses Yahoo, falling back on https://github.com/fawazahmed0/currency-api for current rates and Yahoo falling back on IMF for historic rates. Note that rate calls are cached.

class CurrencyError()

Bases : Exception

class Currency()

Currency class for performing currency conversion. Uses Yahoo, falling back on https://github.com/fawazahmed0/currency-api for current rates and Yahoo falling back on IMF for historic rates. Note that rate calls are cached.

Methods

  • setup — Setup the sources. If you wish to use a static fallback file by setting fallback_current_to_static to True, it needs to be named "secondary_rates.json" and put in the fallback_dir of the passed in Retriever.

  • get_current_rate — Get the current fx rate for currency

  • get_current_value_in_usd — Get the current USD value of the value in local currency

  • get_current_value_in_currency — Get the current value in local currency of the value in USD

  • get_historic_rate — Get the fx rate for currency on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

  • get_historic_value_in_usd — Get the USD value of the value in local currency on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

  • get_historic_value_in_currency — Get the current value in local currency of the value in USD on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

classmethod Currency.setup(retriever: Retrieve | None = None, primary_rates_url: Path | str = _primary_rates_url, secondary_rates_url: Path | str = _secondary_rates_url, secondary_historic_url: Path | str | None = _secondary_historic_url, secondary_historic_rates: dict | None = None, fallback_historic_to_current: bool = False, fallback_current_to_static: bool = False, no_historic: bool = False, fixed_now: datetime | None = None, log_level: int = logging.DEBUG, current_rates_cache: dict = {'USD': 1}, historic_rates_cache: dict = {}, use_secondary_historic: bool = False) → None

Setup the sources. If you wish to use a static fallback file by setting fallback_current_to_static to True, it needs to be named "secondary_rates.json" and put in the fallback_dir of the passed in Retriever.

Parameters

  • retriever : Retrieve | None — Retrieve object to use for downloading. Defaults to None (generate a new one).

  • primary_rates_url : Path | str — Primary rates url to use. Defaults to Yahoo API.

  • secondary_rates_url : Path | str — Current rates url to use. Defaults to currency-api.

  • secondary_historic_url : Path | str | None — Historic rates url to use. Defaults to IMF (via IATI).

  • secondary_historic_rates : dict | None — Historic rates to use. Defaults to None.

  • fallback_historic_to_current : bool — If historic unavailable, fallback to current. Defaults to False.

  • fallback_current_to_static : bool — Use static file as final fallback. Defaults to False.

  • no_historic : bool — Do not set up historic rates. Defaults to False.

  • fixed_now : datetime | None — Use a fixed datetime for now. Defaults to None (use datetime.now()).

  • log_level : int — Level at which to log messages. Defaults to logging.DEBUG.

  • current_rates_cache : dict — Pre-populate current rates cache with given values. Defaults to {"USD": 1}.

  • historic_rates_cache : dict — Pre-populate historic rates cache with given values. Defaults to {}.

  • use_secondary_historic : bool — Use secondary historic first. Defaults to False.

Returns

  • None — None

classmethod Currency.get_current_rate(currency: str) → float

Get the current fx rate for currency

Parameters

  • currency : str — Currency

Returns

  • float — fx rate

Raises

classmethod Currency.get_current_value_in_usd(value: int | float, currency: str) → float

Get the current USD value of the value in local currency

Parameters

  • value : int | float — Value in local currency

  • currency : str — Currency

Returns

  • float — Value in USD

classmethod Currency.get_current_value_in_currency(usdvalue: int | float, currency: str) → float

Get the current value in local currency of the value in USD

Parameters

  • usdvalue : int | float — Value in USD

  • currency : str — Currency

Returns

  • float — Value in local currency

classmethod Currency.get_historic_rate(currency: str, date: datetime, ignore_timeinfo: bool = True) → float

Get the fx rate for currency on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

Parameters

  • currency : str — Currency

  • date : datetime — Date to use for fx conversion

  • ignore_timeinfo : bool — Ignore time and time zone of date. Defaults to True.

Returns

  • float — fx rate

classmethod Currency.get_historic_value_in_usd(value: int | float, currency: str, date: datetime, ignore_timeinfo: bool = True) → float

Get the USD value of the value in local currency on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

Parameters

  • value : int | float — Value in local currency

  • currency : str — Currency

  • date : datetime — Date to use for fx conversion

  • ignore_timeinfo : bool — Ignore time and time zone of date. Defaults to True.

Returns

  • float — Value in USD

classmethod Currency.get_historic_value_in_currency(usdvalue: int | float, currency: str, date: datetime, ignore_timeinfo: bool = True) → float

Get the current value in local currency of the value in USD on a particular date. Any time and time zone information will be ignored by default (meaning that the time is set to 00:00:00 and the time zone set to UTC). To have the time and time zone accounted for, set ignore_timeinfo to False. This may affect which day's closing value is used.

Parameters

  • value — Value in USD

  • currency : str — Currency

  • date : datetime — Date to use for fx conversion

  • ignore_timeinfo : bool — Ignore time and time zone of date. Defaults to True.

Returns

  • float — Value in local currency