easymoney package¶

Main API Functionality¶

class easymoney.money.EasyPeasy(precision=2, fall_back=True, fuzzy_threshold=False, data_path=None)[source]¶

Bases: object

Tools for Monetary Information and Conversions.

Parameters:

precision (int) – number of places to round to when returning results. Defaults to 2. fall_back (bool) – if True, fall back to closest possible date for which data is available. Defaults to True. fuzzy_match_threshold – a threshold for fuzzy matching confidence (requires the fuzzywuzzy package). The value must be an number between 0 and 100. The suggested minimum values is 85. This will only impact attempts to match on natural names, e.g., attempting to match ‘Canada’ by passing ‘Canadian’. If True, a threshold of 90 will be set. Defaults to False. Warning Fuzzy matching may yield inaccurate results. When possible, use terminology exactly as it appears in options(). data_path (str) – alternative path to the database file(s). Defaults to None.

currency_converter(amount, from_currency, to_currency, date='latest', pretty_print=False)[source]¶

Function to perform currency conversion based on, not directly reported from, data obtained from the European Central Bank (ECB). Base Currency: EUR.

Formulae Used

Let \(LCU\) be defined as:

\[LCU(\phi_{EUR}, CUR) = ExchangeRate_{\phi_{EUR} → CUR}\]

\(where\):

\(CUR\) is some local currency unit.

\(\phi = 1\), as in the ECB data.

That is, less formally:

\[LCU(\phi_{EUR}, CUR) = \dfrac{x \space \space CUR}{1 \space EUR}\]

\(Thus\):

From \(CUR_{1}\) to \(CUR_{2}\):

\[amount_{CUR_{2}} = \dfrac{1}{LCU(\phi_{EUR}, CUR_{1})} \cdot LCU(\phi_{EUR}, CUR_{2}) \cdot amount_{CUR_{1}}\]

Parameters:	amount (float or int) – an amount of money to be converted. from_currency (str) – the currency of the amount. to_currency (str) – the currency the amount is to be converted into. date (str) – date of data to perform the conversion with. Dates must be of the form: DD/MM/YYYY. pretty_print (bool) – if True, pretty prints the table otherwise returns the table as a pandas DataFrame. Defaults to False.
Returns:	converted currency.
Return type:	float

inflation(region, year_a, year_b=None, return_raw_cpi_dict=False, pretty_print=False)[source]¶

Calculator to compute the inflation rate from Consumer Price Index (CPI) information.

Inflation Formula:

\[Inflation_{region} = \dfrac{c_{1} - c_{2}}{c_{2}} \cdot 100\]

\(where\):

\(c_{1}\) = CPI of the region in year_b.

\(c_{2}\) = CPI of the region in year_a.

Parameters:	region (str) – a region. year_a (int) – start year. year_b (int) – end year. Defaults to None – can only be left to this default if return_raw_cpi_dict is True. return_raw_cpi_dict (bool) – If True, returns the CPI information in a dict. Defaults to False. pretty_print (bool) – if True, pretty prints the result otherwise returns the result as a float. Defaults to False.
Returns:	the rate of inflation between year_a and year_h. a dictionary of CPI information with the years as keys, CPI as values.
Return type:	float, dict or NaN

inflation_calculator(amount, region, year_a, year_b, pretty_print=False)[source]¶

Adjusts a given amount of money for inflation.

Parameters:	amount (float or int) – a monetary amount. region (str) – a geographical region. year_a (int) – start year. year_b (int) – end year. pretty_print (bool) – if True, pretty prints the result otherwise returns the result as a float. Defaults to False.
Returns:	\(amount \cdot inflation \space rate\).
Return type:	float or NaN

normalize(amount, region, from_year, to_year='latest', base_currency='EUR', exchange_date='latest', pretty_print=False)[source]¶

Convert a Nominal Amount of money to a Real Amount in the same, or another, currency.

This requires both inflation (for currency) and exchange rate information (currency to base_currency). See options(info = 'all', overlap_only = True) for an exhaustive listing of valid values to pass to this method.

Currency Normalization occurs in two steps:

1. Adjust the currency for inflation, e.g., 100 (2010 \(CUR_{1}\)) → x (2015 \(CUR_{1}\)).

2. Convert the adjusted amount into the base_currency.

Parameters:	amount (float or int) – a numeric amount of money. currency (str) – a region or currency. Legal options: Region Name, ISO Alpha2, Alpha3 or Currency Code (see options()). from_year (int) – a year. For valid values see options(). to_year (str or int) – a year. For valid values see options(). Defaults to ‘latest’ (which will use the most recent data available). base_currency (str) – a region or currency. Legal: Region Name, ISO Alpha2, Alpha3 or Currency Code (see options()). Defaults to ‘EUR’. pretty_print (bool) – Pretty print the result if True; return amount if False. Defaults to False.
Returns:	amount adjusted for inflation and converted into the base currency.
Return type:	float

options(info='all', rformat='table', pretty_print=True, table_overlap_only=False, range_table_dates=True)[source]¶

An easy interface to explore all of the terminology EasyPeasy understands as well the dates for which data is available.

Parameters:	info (str) – ‘exchange’, ‘inflation’ or ‘all’ (‘all’ requires rformat is set to ‘table’). rformat (str) – ‘table’ for a table or ‘list’ for just the currency codes, alone. Defaults to ‘table’. pretty_print (bool) – if True, prints the list or table. If False, returns the list or table (as a Pandas DataFrame). Defaults to True. table_overlap_only (bool) – when info is set to ‘all’, keep only those rows for which exchange rate and inflation data overlap. range_table_dates (bool) – if True, only report the minimum and maximum date for which data is available; if False, all dates for which data is available will be reported. Defaults to True.
Returns:	information table or list
Return type:	Pandas DataFrame or list

region_map(region, map_to='alpha_2')[source]¶

Map a ‘region’ to any one of: ISO Alpha 2, ISO Alpha 3, it’s Name or Offical Name.

Examples:

• EasyPeasy().region_map(region='CA', map_to='alpha_2') \(=\) ‘CA’
• EasyPeasy().region_map(region='Canada', map_to='alpha_3') \(=\) ‘CAN’

Parameters:	region (str) – a ‘region’ in the format of a ISO Alpha2, ISO Alpha3 or currency code, as well as natural name. map_to (str) – for region: ‘alpha_2’, ‘alpha_3’, ‘name’ or ‘official_name’. for currency: ‘currency_alpha_3’, ‘currency_numeric’ or ‘currency_name’. Defaults to ‘alpha_2’.
Returns:	the desired mapping from region to ISO Alpha2.
Return type:	str or tuple