Welcome to CurrencyConverter’s documentation!

class currency_converter.currency_converter.CurrencyConverter(currency_file=u'/home/docs/checkouts/readthedocs.org/user_builds/currencyconverter/checkouts/latest/currency_converter/eurofxref-hist.zip', fallback_on_wrong_date=False, fallback_on_missing_rate=False, fallback_on_missing_rate_method=u'linear_interpolation', ref_currency=u'EUR', na_values=frozenset([u'', u'N/A']), decimal=False, verbose=False)[source]

Bases: object

At init, load the historic currencies (since 1999) from the ECB. The rates are EUR foreign exchange reference rates:

Date,USD,JPY,BGN,CYP,CZK,… 2014-03-28,1.3759,140.9,1.9558,N/A,27.423,… 2014-03-27,1.3758,…

_rates is a dictionary with:

  • currencies as keys
  • {date: rate, …} as values.

currencies is a set of all available currencies. bounds is a dict if first and last date available per currency.

__init__(currency_file=u'/home/docs/checkouts/readthedocs.org/user_builds/currencyconverter/checkouts/latest/currency_converter/eurofxref-hist.zip', fallback_on_wrong_date=False, fallback_on_missing_rate=False, fallback_on_missing_rate_method=u'linear_interpolation', ref_currency=u'EUR', na_values=frozenset([u'', u'N/A']), decimal=False, verbose=False)[source]

Instantiate a CurrencyConverter.

Parameters:
  • currency_file (str) – Path to the source data. Can be a local path, or an URL starting with ‘http://’ or ‘https://’. Defaults to the European Central Bank historical rates file included in the package.
  • fallback_on_wrong_date (bool) – Set to False (default) to raise a RateNotFoundError when dates are requested outside the data’s range. Set to True to extrapolate rates for dates outside the source data’s range. The extrapolation is done by falling back to the first or last data point, for dates before and after the data’s range, respectively.
  • fallback_on_missing_rate (bool) – Set to True to linearly interpolate missing rates by their two closest valid rates. This only affects dates within the source data’s range. Default False.
  • fallback_on_missing_rate_method (bool) – Choose the fallback on missing rate method. Default is “linear_interpolation”, also available is “last_known”.
  • ref_currency (str) – Three-letter currency code for the currency that the source data is oriented towards. This is EUR for the default European Central Bank data, and so the default is ‘EUR’.
  • na_values (iterable) – What to interpret as missing values in the source data.
  • decimal – Set to True to use decimal.Decimal internally, this will slow the loading time but will allow exact conversions
  • verbose – Set to True to print what is going on under the hood.
convert(amount, currency, new_currency=u'EUR', date=None)[source]

Convert amount from a currency to another one.

Parameters:
  • amount (float) – The amount of currency to convert.
  • currency (str) – The currency to convert from.
  • new_currency (str) – The currency to convert to.
  • date (datetime.date) – Use the conversion rate of this date. If this is not given, the most recent rate is used.
Returns:

The value of amount in new_currency.

Return type:

float

>>> from datetime import date
>>> c = CurrencyConverter()
>>> c.convert(100, 'EUR', 'USD', date=date(2014, 3, 28))
137.5...
>>> c.convert(100, 'USD', date=date(2014, 3, 28))
72.67...
>>> c.convert(100, 'BGN', date=date(2010, 11, 21))
Traceback (most recent call last):
RateNotFoundError: BGN has no rate for 2010-11-21
load_file(currency_file)[source]

To be subclassed if alternate methods of loading data.

load_lines(lines)[source]
class currency_converter.currency_converter.S3CurrencyConverter(currency_file, **kwargs)[source]

Bases: currency_converter.currency_converter.CurrencyConverter

Load the ECB CSV file from an S3 key instead of from a local file. The first argument should be an instance of boto.s3.key.Key (or any other object that provides a get_contents_as_string() method which returns the CSV file as a string).

__init__(currency_file, **kwargs)[source]

Make currency_file a required attribute

load_file(currency_file)[source]
exception currency_converter.currency_converter.RateNotFoundError[source]

Bases: exceptions.Exception

Custom exception when data is missing in the rates file.