hdx.location.currency

Currency conversion

Currency Objects

class Currency()

[view_source]

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.

setup

@classmethod
def setup(cls,
          retriever: Optional[Retrieve] = None,
          primary_rates_url: str = _primary_rates_url,
          secondary_rates_url: str = _secondary_rates_url,
          secondary_historic_url: str = _secondary_historic_url,
          fallback_historic_to_current: bool = False,
          fallback_current_to_static: bool = False,
          no_historic: bool = False,
          fixed_now: Optional[datetime] = None,
          log_level: int = logging.DEBUG) -> None

[view_source]

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.

Arguments:

  • retriever Optional[Retrieve] - Retrieve object to use for downloading. Defaults to None (generate a new one).
  • primary_rates_url str - Primary rates url to use. Defaults to Yahoo API.
  • secondary_rates_url str - Current rates url to use. Defaults to currency-api.
  • secondary_historic_url str - Historic rates url to use. Defaults to IMF (via IATI).
  • 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 Optional[datetime] - 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.

Returns:

None

get_current_rate

@classmethod
def get_current_rate(cls, currency: str) -> float

[view_source]

Get the current fx rate for currency

Arguments:

  • currency str - Currency

Returns:

  • float - fx rate

get_current_value_in_usd

@classmethod
def get_current_value_in_usd(cls, value: Union[int, float],
                             currency: str) -> float

[view_source]

Get the current USD value of the value in local currency

Arguments:

  • value Union[int, float] - Value in local currency
  • currency str - Currency

Returns:

  • float - Value in USD

get_current_value_in_currency

@classmethod
def get_current_value_in_currency(cls, usdvalue: Union[int, float],
                                  currency: str) -> float

[view_source]

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

Arguments:

  • usdvalue Union[int, float] - Value in USD
  • currency str - Currency

Returns:

  • float - Value in local currency

get_historic_rate

@classmethod
def get_historic_rate(cls,
                      currency: str,
                      date: datetime,
                      ignore_timeinfo: bool = True) -> float

[view_source]

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.

Arguments:

  • 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

get_historic_value_in_usd

@classmethod
def get_historic_value_in_usd(cls,
                              value: Union[int, float],
                              currency: str,
                              date: datetime,
                              ignore_timeinfo: bool = True) -> float

[view_source]

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.

Arguments:

  • value Union[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

get_historic_value_in_currency

@classmethod
def get_historic_value_in_currency(cls,
                                   usdvalue: Union[int, float],
                                   currency: str,
                                   date: datetime,
                                   ignore_timeinfo: bool = True) -> float

[view_source]

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.

Arguments:

  • value Union[int, float] - 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