DOCSEARCHbyAlgolia
Submit Docs

CurrencyConverter

repository·master·Indexed 42 days ago

https://github.com/alexprengere/currencyconverter

A Python library for performing historical currency conversions against the Euro, primarily using data from the European Central Bank. It provides a Python API via the CurrencyConverter class and a command-line interface. Features include support for custom data sources, high-precision Decimal conversions, and fallback mechanisms for missing rates or out-of-bounds dates.

Tokens
1.3K
Snippets
7
Records
7
Agent score
4%

What's inside CurrencyConverter

  1. Configure fallback modes for missing rates or dates

    master

    If a specific rate is missing for a requested date, or if the date is outside the available currency bounds, you can enable fallback mechanisms.

    Missing Rates Fallback

    If a rate is missing for a date within the currency's known bounds, use fallback_on_missing_rate=True. You can choose the method via fallback_on_missing_rate_method.

    • Supported methods: "linear_interpolation" (default) and "last_known".
    c = CurrencyConverter(fallback_on_missing_rate=True)
# Uses linear interpolation if the exact date rate is missing
c.convert(100, 'BGN', date=date(2010, 11, 21))

    Out-of-Bounds Date Fallback

    If the requested date is outside the available range for a currency, use fallback_on_wrong_date=True to fall back to the closest available bound.

    c = CurrencyConverter(fallback_on_wrong_date=True)
# Falls back to the earliest available date in the dataset
c.convert(100, 'EUR', 'USD', date=date(1986, 2, 2))
    c = CurrencyConverter(fallback_on_missing_rate=True, fallback_on_wrong_date=True)

  3. Load different currency data sources

    master

    The CurrencyConverter constructor accepts a path to a currency file or a URL to download data. The data must follow the ECB (European Central Bank) format.

    Available Data Options

    • Packaged data: CurrencyConverter() (Uses embedded data, might be outdated).
    • Full history: CurrencyConverter(ECB_URL) (Downloads the full history from ECB).
    • Latest day only: CurrencyConverter(SINGLE_DAY_ECB_URL) (Downloads only the most recent available day).
    • Custom file: CurrencyConverter('./path/to/file.csv') (Loads a local file).

    Recommended: Daily Download Pattern

    To avoid unnecessary overhead, download the file once per day and then load it:

    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)
    from currency_converter import ECB_URL, SINGLE_DAY_ECB_URL

# Download full history
c = CurrencyConverter(ECB_URL)

# Download only latest day
c = CurrencyConverter(SINGLE_DAY_ECB_URL)

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

  4. Use high-precision Decimal conversions

    master

    By default, the converter uses floating-point math. For exact conversions, you can enable decimal mode.

    Warning: Enabling decimal=True will slow down the initial data loading time by approximately a factor of 10.

    from currency_converter import CurrencyConverter
from datetime import date

c = CurrencyConverter(decimal=True)
result = c.convert(100, 'EUR', 'USD', date=date(2013, 3, 21))
# result is a decimal.Decimal object
    c = CurrencyConverter(decimal=True)

  5. Use the CurrencyConverter Python API

    master

    The core functionality is accessed via the CurrencyConverter class. By default, it uses embedded data which may not be up to date.

    Basic Conversion

    Convert an amount from one currency to another. If no target currency is provided, it defaults to EUR.

    from currency_converter import CurrencyConverter
c = CurrencyConverter()

# Convert 100 EUR to USD
c.convert(100, 'EUR', 'USD')

# Convert 100 USD to the default (EUR)
c.convert(100, 'USD')

    Conversion with a Specific Date

    You can specify a date (using datetime.date or datetime.datetime) to perform a historical conversion.

    from datetime import date
c.convert(100, 'EUR', 'USD', date=date(2013, 3, 21))
    from currency_converter import CurrencyConverter
c = CurrencyConverter()
c.convert(100, 'EUR', 'USD')

  6. Inspect available currencies and date bounds

    master

    You can inspect the capabilities of a CurrencyConverter instance using the following attributes:

    • currencies: A set containing all supported currency codes (e.g., 'USD', 'EUR').
    • bounds: A dictionary where keys are currency codes and values are tuples containing the (first_date, last_date) available for that currency.
    # Check available currencies
if 'USD' in c.currencies:
    print("USD is supported")

# Get date range for a currency
first_date, last_date = c.bounds['USD']
    # Accessing attributes
print(c.currencies)
first_date, last_date = c.bounds['USD']

  7. Use the currency_converter CLI

    master

    Once installed, you can use the currency_converter command in your terminal. The syntax allows you to specify the amount, the source currency, and the target currency using the --to flag.

    Example:

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