Skip to main content

A currency converter using the European Central Bank data.

Project description

https://raw.githubusercontent.com/alexprengere/currencyconverter/master/logo/cc3.png

actions cratev crated

This is a currency converter that uses historical rates against a reference currency (Euro). It is compatible with Python3.6+.

Currency data sources

The default source is the European Central Bank. This is the ECB historical rates for 42 currencies against the Euro since 1999. It can be downloaded here: eurofxref-hist.zip. The converter can use different sources as long as the format is the same.

Note that the currency converter does not query the API in real time, to avoid the overhead of the HTTP request. It uses embedded data in the library, which might not be up to date. If you need the latest data, please refer to the data section.

Installation

You can install directly after cloning:

$ python setup.py install --user

Or use the Python package:

$ pip install --user currencyconverter

Command line tool

After installation, you should have currency_converter in your $PATH:

$ currency_converter 100 USD --to EUR
100.000 USD = 87.512 EUR on 2016-05-06

Python API

Create once the currency converter object:

>>> from currency_converter import CurrencyConverter
>>> c = CurrencyConverter()

Convert from EUR to USD using the last available rate:

>>> c.convert(100, 'EUR', 'USD') # doctest: +SKIP
137.5...

Default target currency is EUR:

>>> c.convert(100, 'EUR')
100.0
>>> c.convert(100, 'USD') # doctest: +SKIP
72.67...

You can change the date of the rate:

>>> from datetime import date # datetime works too
>>> c.convert(100, 'EUR', 'USD', date=date(2013, 3, 21))
129...

Data

You can use your own currency file, as long as it has the same format (ECB):

from currency_converter import ECB_URL, SINGLE_DAY_ECB_URL

# Load the packaged data (might not be up to date)
c = CurrencyConverter()

# Download the full history, this will be up to date. Current value is:
# https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist.zip
c = CurrencyConverter(ECB_URL)

# Dowload only the latest available day. Current value is:
# https://www.ecb.europa.eu/stats/eurofxref/eurofxref.zip
c = CurrencyConverter(SINGLE_DAY_ECB_URL)

# Load your custom file
c = CurrencyConverter('./path/to/currency/file.csv')

Since the raw data is updated only once a day, it might be better to only download it once a day:

import os.path as op
import urllib.request
from datetime import date

from currency_converter import ECB_URL, CurrencyConverter

filename = f"ecb_{date.today():%Y%m%d}.zip"
if not op.isfile(filename):
    urllib.request.urlretrieve(ECB_URL, filename)
c = CurrencyConverter(filename)

Fallbacks

Some rates are missing:

>>> c.convert(100, 'BGN', date=date(2010, 11, 21))
Traceback (most recent call last):
RateNotFoundError: BGN has no rate for 2010-11-21

But we have a fallback mode for those, using a linear interpolation of the closest known rates, as long as you ask for a date within the currency date bounds:

>>> c = CurrencyConverter(fallback_on_missing_rate=True)
>>> c.convert(100, 'BGN', date=date(2010, 11, 21))
51.12...

The fallback method can be configured with the fallback_on_missing_rate_method parameter, which currently supports "linear_interpolation" and "last_known" values.

We also have a fallback mode for dates outside the currency bounds:

>>> c = CurrencyConverter()
>>> c.convert(100, 'EUR', 'USD', date=date(1986, 2, 2))
Traceback (most recent call last):
RateNotFoundError: 1986-02-02 not in USD bounds 1999-01-04/2016-04-29
>>>
>>> c = CurrencyConverter(fallback_on_wrong_date=True)
>>> c.convert(100, 'EUR', 'USD', date=date(1986, 2, 2)) # fallback to 1999-01-04
117.89...

Decimal

If you need exact conversions, you can use the decimal option to use decimal.Decimal internally when parsing rates. This will slow down the load time by a factor 10 though.

>>> c = CurrencyConverter(decimal=True)
>>> c.convert(100, 'EUR', 'USD', date=date(2013, 3, 21))
Decimal('129.100')

Other attributes

  • bounds lets you know the first and last available date for each currency

>>> first_date, last_date = c.bounds['USD']
>>> first_date
datetime.date(1999, 1, 4)
>>> last_date # doctest: +SKIP
datetime.date(2016, 11, 14)
  • currencies is a set containing all available currencies

>>> c.currencies # doctest: +SKIP
set(['SGD', 'CAD', 'SEK', 'GBP', ...
>>> 'AAA' in c.currencies
False
>>> c.convert(100, 'AAA')
Traceback (most recent call last):
ValueError: AAA is not a supported currency

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

currencyconverter-0.17.34.tar.gz (3.8 MB view details)

Uploaded Source

Built Distribution

CurrencyConverter-0.17.34-py3-none-any.whl (611.6 kB view details)

Uploaded Python 3

File details

Details for the file currencyconverter-0.17.34.tar.gz.

File metadata

  • Download URL: currencyconverter-0.17.34.tar.gz
  • Upload date:
  • Size: 3.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for currencyconverter-0.17.34.tar.gz
Algorithm Hash digest
SHA256 58cfae73bf45598834ee14fc65dc1af52dcc5fdf331357eaf0230db3b74bed23
MD5 48e5c57cb30681d04c8f73992dd28681
BLAKE2b-256 7ff2f055826c125a2368482f3850625b388e86e6dab4af83a271b0eb01e22129

See more details on using hashes here.

Provenance

The following attestation bundles were made for currencyconverter-0.17.34.tar.gz:

Publisher: python-package.yml on alexprengere/currencyconverter

Attestations:

File details

Details for the file CurrencyConverter-0.17.34-py3-none-any.whl.

File metadata

File hashes

Hashes for CurrencyConverter-0.17.34-py3-none-any.whl
Algorithm Hash digest
SHA256 ddfce0d2fe962099afdadfd2dfde0dc051b20f982009553be41eb5608579f734
MD5 f18f7f2420b9b172a205752a5715a437
BLAKE2b-256 7cec68e08ea21a759ebda22b12a9644c9bf597f89b1e01e74920bed5c0ebbc84

See more details on using hashes here.

Provenance

The following attestation bundles were made for CurrencyConverter-0.17.34-py3-none-any.whl:

Publisher: python-package.yml on alexprengere/currencyconverter

Attestations:

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page