# Django currencies with historical exchange rates
This is a fairly minimal Django app that renders amounts of currencies,
stores historical exchange rates in the database, and performs currency
conversion.
When working with any historical multi-currency data, one often needs to
be able to perform exchange rate calculations with historical rates.
This allows the conversion to be accurately reproduced in the future.
Exchange Rates are stored in a simple database table, with 1 row per
rate per date.
Conversions can be done directly, or across a base currency using 2
rates.
Formatting is defined by [`iso4217`](https://pypi.org/project/iso4217/).
Exchange Rate data can be sourced from:
* The [European ECB Reference Rates](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html).
Public, provides rates for 41 currencies against EUR.
* [openexchangerates.org](https://openexchangerates.org/).
Requires (free) registration, provides 169 currencies against USD.
## Installation
1. Install `django-historical-currencies` in your Python environment.
1. Add `historical_currencies` to `INSTALLED_APPS` in your
`settings.py`.
1. Import yesterday's exchange rates to get started:
`manage.py import_ecb_exchangerates --daily`.
1. Configure a periodic task (e.g. cron, systemd timer, celery beat) to
import daily exchange rates.
## Settings
* `MAX_EXCHANGE_RATE_AGE`: How many days old can an exchange rate be
treated as current?
Optional settings, only required for OpenExchangeRates.org import:
* `OPEN_EXCHANGE_RATES_APP_ID`: OpenExchangeRates App ID.
* `OPEN_EXCHANGE_RATES_BASE_CURRENCY`: Base currency.
## Usage
In code, amounts can be converted using the
`historical_currencies.exchange.exchange()` method.
In templates, this module represents financial amounts as tuple of
`(Decimal, str(currency-code))`. The recommended approach is to add
properties to your Django models to return this tuple for amounts.
In a template the amount can be displayed or converted:
```
{% load currency_format %}
Assuming my_amount = (Decimal(10), 'USD')
Display:
{{ my_amount|currency }}
-> 10.00 USD
Exchange at the latest rate:
{{ my_amount|exchange:"EUR" }}
-> 9.06 EUR
```
### Currency Selectors:
There are two template tags to help render currency selectors. A
high-level one that renders HTML:
```
{% load currency_choices %}
<select>
{% currency_choices_options selected="USD" %}
</select>
```
And a low-level one that returns a list of currencies:
```
{% load currency_choices %}
<select>
{% currency_choices_list as currency_choices %}
{% for code, name in currency_choices %}
<option value="{{ code }}">{{ name }}</option>
{% endfor %}
</select>
```
## License
This Django app is available under the terms of the ISC license, see
`LICENSE`.
Raw data
{
"_id": null,
"home_page": null,
"name": "django-historical-currencies",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "django, currencies, exchange, xe",
"author": null,
"author_email": "Stefano Rivera <stefano@rivera.za.net>",
"download_url": "https://files.pythonhosted.org/packages/21/20/6382fa35291be93fe1a72ade724f8d30c47b707958da10eebd927fb84a8c/django_historical_currencies-0.0.3.tar.gz",
"platform": null,
"description": "# Django currencies with historical exchange rates\n\nThis is a fairly minimal Django app that renders amounts of currencies,\nstores historical exchange rates in the database, and performs currency\nconversion.\n\nWhen working with any historical multi-currency data, one often needs to\nbe able to perform exchange rate calculations with historical rates.\nThis allows the conversion to be accurately reproduced in the future.\n\nExchange Rates are stored in a simple database table, with 1 row per\nrate per date.\nConversions can be done directly, or across a base currency using 2\nrates.\n\nFormatting is defined by [`iso4217`](https://pypi.org/project/iso4217/).\nExchange Rate data can be sourced from:\n\n* The [European ECB Reference Rates](https://www.ecb.europa.eu/stats/policy_and_exchange_rates/euro_reference_exchange_rates/html/index.en.html).\n Public, provides rates for 41 currencies against EUR.\n* [openexchangerates.org](https://openexchangerates.org/).\n Requires (free) registration, provides 169 currencies against USD.\n\n## Installation\n\n1. Install `django-historical-currencies` in your Python environment.\n1. Add `historical_currencies` to `INSTALLED_APPS` in your\n `settings.py`.\n1. Import yesterday's exchange rates to get started:\n `manage.py import_ecb_exchangerates --daily`.\n1. Configure a periodic task (e.g. cron, systemd timer, celery beat) to\n import daily exchange rates.\n\n## Settings\n\n* `MAX_EXCHANGE_RATE_AGE`: How many days old can an exchange rate be\n treated as current?\n\nOptional settings, only required for OpenExchangeRates.org import:\n\n* `OPEN_EXCHANGE_RATES_APP_ID`: OpenExchangeRates App ID.\n* `OPEN_EXCHANGE_RATES_BASE_CURRENCY`: Base currency.\n\n## Usage\n\nIn code, amounts can be converted using the\n`historical_currencies.exchange.exchange()` method.\n\nIn templates, this module represents financial amounts as tuple of\n`(Decimal, str(currency-code))`. The recommended approach is to add\nproperties to your Django models to return this tuple for amounts.\n\nIn a template the amount can be displayed or converted:\n\n```\n{% load currency_format %}\n\nAssuming my_amount = (Decimal(10), 'USD')\nDisplay:\n{{ my_amount|currency }}\n-> 10.00 USD\n\nExchange at the latest rate:\n{{ my_amount|exchange:\"EUR\" }}\n-> 9.06 EUR\n```\n\n### Currency Selectors:\n\nThere are two template tags to help render currency selectors. A\nhigh-level one that renders HTML:\n\n```\n{% load currency_choices %}\n\n<select>\n {% currency_choices_options selected=\"USD\" %}\n</select>\n```\n\nAnd a low-level one that returns a list of currencies:\n\n```\n{% load currency_choices %}\n\n<select>\n {% currency_choices_list as currency_choices %}\n {% for code, name in currency_choices %}\n <option value=\"{{ code }}\">{{ name }}</option>\n {% endfor %}\n</select>\n```\n\n## License\n\nThis Django app is available under the terms of the ISC license, see\n`LICENSE`.\n",
"bugtrack_url": null,
"license": "ISC",
"summary": "Django currencies with historical exchange rates",
"version": "0.0.3",
"project_urls": {
"Changelog": "https://github.com/stefanor/django-historical-currencies/blob/master/CHANGELOG.md",
"Repository": "https://github.com/stefanor/django-historical-currencies/"
},
"split_keywords": [
"django",
" currencies",
" exchange",
" xe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ca79c7f0ae26afe9c4499eaa8d30427dcb689c01ec86a7e0c8f5c6c0b3ff83f1",
"md5": "c6f012ed426aee3cadae3ca04674e4bd",
"sha256": "1dd5f21e35105edf6b8940db6d16b719b4463a82f7cc959326b9a11a7788e097"
},
"downloads": -1,
"filename": "django_historical_currencies-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c6f012ed426aee3cadae3ca04674e4bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 18037,
"upload_time": "2024-05-12T20:46:25",
"upload_time_iso_8601": "2024-05-12T20:46:25.151169Z",
"url": "https://files.pythonhosted.org/packages/ca/79/c7f0ae26afe9c4499eaa8d30427dcb689c01ec86a7e0c8f5c6c0b3ff83f1/django_historical_currencies-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "21206382fa35291be93fe1a72ade724f8d30c47b707958da10eebd927fb84a8c",
"md5": "98ec1e8029204a68d879ee58cfcf9cb3",
"sha256": "a38dde4154fef1caf26dec0cf54977f070539c5d09773369a0221c8c2e45847a"
},
"downloads": -1,
"filename": "django_historical_currencies-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "98ec1e8029204a68d879ee58cfcf9cb3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 11984,
"upload_time": "2024-05-12T20:46:26",
"upload_time_iso_8601": "2024-05-12T20:46:26.152413Z",
"url": "https://files.pythonhosted.org/packages/21/20/6382fa35291be93fe1a72ade724f8d30c47b707958da10eebd927fb84a8c/django_historical_currencies-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-12 20:46:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "stefanor",
"github_project": "django-historical-currencies",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-historical-currencies"
}
JSON
