Currencies done right
In most payment systems that went international, amounts are represented as integers, instead of decimals, as they are represented in minor currency units (smallest unit possible).
For EUR it is cent, which is 1/100 of a single Euro. For MRU it is khoums, which is 1/5 of a single Ouguiya.
List of currencies is generated from a single CSV dump obtained from the list of circulating currencies Wikipedia page using the awesome wikitable2csv.
Prerequisites
Core package requires Python 3.6, 3.7, 3.8 or 3.9.
Django integration package (valuta.contrib.django_integration) requires Django 2.2, 3.0, 3.1 or 3.2.
Documentation
Documentation is available on Read the Docs.
Installation
Latest stable version on PyPI:
pip install valutaOr development version from GitHub:
pip install https://github.com/barseghyanartur/valuta/archive/master.tar.gzUsage examples
Pure Python
import valuta
valuta.EUR.convert_to_currency_units(1_000)
# 10.0
valuta.UGX.convert_to_currency_units(1_000)
# 1000.0
valuta.MRU.convert_to_currency_units(1_000)
# 200.0
valuta.VND.convert_to_currency_units(1_000)
# 100.0
valuta.TND.convert_to_currency_units(1_000)
# 1.0Django integration
In its’ basis, Django integration package is a CurrencyField representing the ISO (ISO 4217) codes of the currencies. If bound to certain number fields (SmallIntegerField, IntegerField, BigIntegerField) holding the amount in minor currency units, it adds up methods to the model class for converting field amounts to major currency units (often simply called currency units).
Model field
Define some models (product/models.py)
from django.db import models
import valuta
from valuta.contrib.django_integration.models import CurrencyField
class Product(models.Model):
name = models.CharField(max_length=255)
price = models.IntegerField() # Amount in minor currency units
price_with_tax = models.IntegerField() # Amount in minor currency units
currency = CurrencyField(amount_fields=["price", "price_with_tax"])Create some data
from product.models import Product
product = Product.objects.create(
name="My test product",
price=100,
price_with_tax=120,
currency=valuta.AMD.uid,
)You could then refer to the `price` and `price_with_tax` as follows
Note, that every field listed in the amount_fields gets a correspondent model method with suffix _in_currency_units for converting the field amounts to (major) currency units.
product.price_in_currency_units()
# 1
product.price_with_tax_in_currency_units()
# 1.2You could limit the currency choices as follows
currency = CurrencyField(
amount_fields=["price", "price_with_tax"],
limit_choices_to=[valuta.AMD.uid, valuta.EUR.uid],
)Casting the `in_currency_units` value
If you want to explicitly cast the result value to a certain type, provide a callable cast_to for the CurrencyField.
For int it would be:
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
cast_to=int,
)For float it would be:
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
cast_to=float,
)For decimal.Decimal it would be:
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
cast_to=lambda __v: Decimal(str(__v)),
)Customize choices display format
By default, the following format is used (valuta.utils.get_currency_choices_with_code):
[
("AMD", "Armenian Dram (AMD)"),
("EUR", "Euro (EUR)"),
]If you want to customize that, provide a callable get_choices_func along:
from valuta.utils import get_currency_choices
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
get_choices_func=get_currency_choices,
)It would then have the following format:
[
("AMD", "Armenian Dram"),
("EUR", "Euro"),
]Take both valuta.utils.get_currency_choices and valuta.utils.get_currency_choices_with_code as a good example of how to customize. You could for instance do something like this:
import operator
from typing import List, Tuple, Set, Union
from babel.numbers import get_currency_symbol
from valuta.registry import Registry
def get_currency_choices_with_sign(
limit_choices_to: Union[Tuple[str, ...], List[str], Set[str]] = None,
sort_by_key: bool = False,
) -> List[Tuple[str, str]]:
"""Get currency choices with code.
List of choices in the following format::
[
("AMD", "AMD - Armenian Dram"),
("EUR", "€ - Euro"),
("USD", "$ - US Dollar"),
]
"""
if limit_choices_to is None:
values = [
(__key, f"{get_currency_symbol(__key)} - {__value.name}")
for __key, __value in Registry.REGISTRY.items()
]
else:
values = [
(__key, f"{get_currency_symbol(__key)} - {__value.name}")
for __key, __value in Registry.REGISTRY.items()
if __key in limit_choices_to
]
if sort_by_key:
values.sort(key=operator.itemgetter(0))
else:
values.sort(key=operator.itemgetter(1))
return valuesAnd then use it as follows:
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
get_choices_func=get_currency_choices_with_sign,
)Supported currencies
Currencies marked with (*) are custom (added manually). The rest is obtained from the already mentioned list of circulating currencies.
┌───────────┬──────────────────────────────────────────┐
│ ISO code │ Currency │
├───────────┼──────────────────────────────────────────┤
│ AED │ United Arab Emirates Dirham │
├───────────┼──────────────────────────────────────────┤
│ AFN │ Afghan Afghani │
├───────────┼──────────────────────────────────────────┤
│ ALL │ Albanian Lek │
├───────────┼──────────────────────────────────────────┤
│ AMD │ Armenian Dram │
├───────────┼──────────────────────────────────────────┤
│ ANG │ Netherlands Antillean Guilder │
├───────────┼──────────────────────────────────────────┤
│ AOA │ Angolan Kwanza │
├───────────┼──────────────────────────────────────────┤
│ ARS │ Argentine Peso │
├───────────┼──────────────────────────────────────────┤
│ AUD │ Australian Dollar │
├───────────┼──────────────────────────────────────────┤
│ AWG │ Aruban Florin │
├───────────┼──────────────────────────────────────────┤
│ AZN │ Azerbaijani Manat │
├───────────┼──────────────────────────────────────────┤
│ BAM │ Bosnia-Herzegovina Convertible Mark │
├───────────┼──────────────────────────────────────────┤
│ BBD │ Barbadian Dollar │
├───────────┼──────────────────────────────────────────┤
│ BDT │ Bangladeshi Taka │
├───────────┼──────────────────────────────────────────┤
│ BGN │ Bulgarian Lev │
├───────────┼──────────────────────────────────────────┤
│ BHD │ Bahraini Dinar │
├───────────┼──────────────────────────────────────────┤
│ BIF │ Burundian Franc │
├───────────┼──────────────────────────────────────────┤
│ BMD │ Bermudan Dollar │
├───────────┼──────────────────────────────────────────┤
│ BND │ Brunei Dollar │
├───────────┼──────────────────────────────────────────┤
│ BOB │ Bolivian Boliviano │
├───────────┼──────────────────────────────────────────┤
│ BRL │ Brazilian Real │
├───────────┼──────────────────────────────────────────┤
│ BSD │ Bahamian Dollar │
├───────────┼──────────────────────────────────────────┤
│ BTC │ Bitcoin (*) │
├───────────┼──────────────────────────────────────────┤
│ BTN │ Bhutanese Ngultrum │
├───────────┼──────────────────────────────────────────┤
│ BWP │ Botswanan Pula │
├───────────┼──────────────────────────────────────────┤
│ BYN │ Belarusian Ruble │
├───────────┼──────────────────────────────────────────┤
│ BZD │ Belize Dollar │
├───────────┼──────────────────────────────────────────┤
│ CAD │ Canadian Dollar │
├───────────┼──────────────────────────────────────────┤
│ CDF │ Congolese Franc │
├───────────┼──────────────────────────────────────────┤
│ CHF │ Swiss Franc │
├───────────┼──────────────────────────────────────────┤
│ CKD │ CKD │
├───────────┼──────────────────────────────────────────┤
│ CLP │ Chilean Peso │
├───────────┼──────────────────────────────────────────┤
│ CNY │ Chinese Yuan │
├───────────┼──────────────────────────────────────────┤
│ COP │ Colombian Peso │
├───────────┼──────────────────────────────────────────┤
│ CRC │ Costa Rican Colón │
├───────────┼──────────────────────────────────────────┤
│ CUP │ Cuban Peso │
├───────────┼──────────────────────────────────────────┤
│ CVE │ Cape Verdean Escudo │
├───────────┼──────────────────────────────────────────┤
│ CZK │ Czech Koruna │
├───────────┼──────────────────────────────────────────┤
│ DJF │ Djiboutian Franc │
├───────────┼──────────────────────────────────────────┤
│ DKK │ Danish Krone │
├───────────┼──────────────────────────────────────────┤
│ DOP │ Dominican Peso │
├───────────┼──────────────────────────────────────────┤
│ DZD │ Algerian Dinar │
├───────────┼──────────────────────────────────────────┤
│ EGP │ Egyptian Pound │
├───────────┼──────────────────────────────────────────┤
│ ERN │ Eritrean Nakfa │
├───────────┼──────────────────────────────────────────┤
│ ETB │ Ethiopian Birr │
├───────────┼──────────────────────────────────────────┤
│ EUR │ Euro │
├───────────┼──────────────────────────────────────────┤
│ FJD │ Fijian Dollar │
├───────────┼──────────────────────────────────────────┤
│ FKP │ Falkland Islands Pound │
├───────────┼──────────────────────────────────────────┤
│ FOK │ FOK │
├───────────┼──────────────────────────────────────────┤
│ GBP │ British Pound │
├───────────┼──────────────────────────────────────────┤
│ GEL │ Georgian Lari │
├───────────┼──────────────────────────────────────────┤
│ GGP │ GGP │
├───────────┼──────────────────────────────────────────┤
│ GHS │ Ghanaian Cedi │
├───────────┼──────────────────────────────────────────┤
│ GIP │ Gibraltar Pound │
├───────────┼──────────────────────────────────────────┤
│ GMD │ Gambian Dalasi │
├───────────┼──────────────────────────────────────────┤
│ GNF │ Guinean Franc │
├───────────┼──────────────────────────────────────────┤
│ GTQ │ Guatemalan Quetzal │
├───────────┼──────────────────────────────────────────┤
│ GYD │ Guyanaese Dollar │
├───────────┼──────────────────────────────────────────┤
│ HKD │ Hong Kong Dollar │
├───────────┼──────────────────────────────────────────┤
│ HNL │ Honduran Lempira │
├───────────┼──────────────────────────────────────────┤
│ HRK │ Croatian Kuna │
├───────────┼──────────────────────────────────────────┤
│ HTG │ Haitian Gourde │
├───────────┼──────────────────────────────────────────┤
│ HUF │ Hungarian Forint │
├───────────┼──────────────────────────────────────────┤
│ IDR │ Indonesian Rupiah │
├───────────┼──────────────────────────────────────────┤
│ ILS │ Israeli New Shekel │
├───────────┼──────────────────────────────────────────┤
│ IMP │ IMP │
├───────────┼──────────────────────────────────────────┤
│ INR │ Indian Rupee │
├───────────┼──────────────────────────────────────────┤
│ IQD │ Iraqi Dinar │
├───────────┼──────────────────────────────────────────┤
│ IRR │ Iranian Rial │
├───────────┼──────────────────────────────────────────┤
│ ISK │ Icelandic Króna │
├───────────┼──────────────────────────────────────────┤
│ JEP │ JEP │
├───────────┼──────────────────────────────────────────┤
│ JMD │ Jamaican Dollar │
├───────────┼──────────────────────────────────────────┤
│ JOD │ Jordanian Dinar │
├───────────┼──────────────────────────────────────────┤
│ JPY │ Japanese Yen │
├───────────┼──────────────────────────────────────────┤
│ KES │ Kenyan Shilling │
├───────────┼──────────────────────────────────────────┤
│ KGS │ Kyrgystani Som │
├───────────┼──────────────────────────────────────────┤
│ KHR │ Cambodian Riel │
├───────────┼──────────────────────────────────────────┤
│ KID │ KID │
├───────────┼──────────────────────────────────────────┤
│ KMF │ Comorian Franc │
├───────────┼──────────────────────────────────────────┤
│ KPW │ North Korean Won │
├───────────┼──────────────────────────────────────────┤
│ KRW │ South Korean Won │
├───────────┼──────────────────────────────────────────┤
│ KWD │ Kuwaiti Dinar │
├───────────┼──────────────────────────────────────────┤
│ KYD │ Cayman Islands Dollar │
├───────────┼──────────────────────────────────────────┤
│ KZT │ Kazakhstani Tenge │
├───────────┼──────────────────────────────────────────┤
│ LAK │ Laotian Kip │
├───────────┼──────────────────────────────────────────┤
│ LBP │ Lebanese Pound │
├───────────┼──────────────────────────────────────────┤
│ LKR │ Sri Lankan Rupee │
├───────────┼──────────────────────────────────────────┤
│ LRD │ Liberian Dollar │
├───────────┼──────────────────────────────────────────┤
│ LSL │ Lesotho Loti │
├───────────┼──────────────────────────────────────────┤
│ LYD │ Libyan Dinar │
├───────────┼──────────────────────────────────────────┤
│ MAD │ Moroccan Dirham │
├───────────┼──────────────────────────────────────────┤
│ MDL │ Moldovan Leu │
├───────────┼──────────────────────────────────────────┤
│ MGA │ Malagasy Ariary │
├───────────┼──────────────────────────────────────────┤
│ MKD │ Macedonian Denar │
├───────────┼──────────────────────────────────────────┤
│ MMK │ Myanmar Kyat │
├───────────┼──────────────────────────────────────────┤
│ MNT │ Mongolian Tugrik │
├───────────┼──────────────────────────────────────────┤
│ MOP │ Macanese Pataca │
├───────────┼──────────────────────────────────────────┤
│ MRU │ Mauritanian Ouguiya │
├───────────┼──────────────────────────────────────────┤
│ MUR │ Mauritian Rupee │
├───────────┼──────────────────────────────────────────┤
│ MVR │ Maldivian Rufiyaa │
├───────────┼──────────────────────────────────────────┤
│ MWK │ Malawian Kwacha │
├───────────┼──────────────────────────────────────────┤
│ MXN │ Mexican Peso │
├───────────┼──────────────────────────────────────────┤
│ MYR │ Malaysian Ringgit │
├───────────┼──────────────────────────────────────────┤
│ MZN │ Mozambican Metical │
├───────────┼──────────────────────────────────────────┤
│ NAD │ Namibian Dollar │
├───────────┼──────────────────────────────────────────┤
│ NGN │ Nigerian Naira │
├───────────┼──────────────────────────────────────────┤
│ NIO │ Nicaraguan Córdoba │
├───────────┼──────────────────────────────────────────┤
│ NOK │ Norwegian Krone │
├───────────┼──────────────────────────────────────────┤
│ NPR │ Nepalese Rupee │
├───────────┼──────────────────────────────────────────┤
│ NZD │ New Zealand Dollar │
├───────────┼──────────────────────────────────────────┤
│ OMR │ Omani Rial │
├───────────┼──────────────────────────────────────────┤
│ PAB │ Panamanian Balboa │
├───────────┼──────────────────────────────────────────┤
│ PEN │ Peruvian Sol │
├───────────┼──────────────────────────────────────────┤
│ PGK │ Papua New Guinean Kina │
├───────────┼──────────────────────────────────────────┤
│ PHP │ Philippine Piso │
├───────────┼──────────────────────────────────────────┤
│ PKR │ Pakistani Rupee │
├───────────┼──────────────────────────────────────────┤
│ PLN │ Polish Zloty │
├───────────┼──────────────────────────────────────────┤
│ PND │ PND │
├───────────┼──────────────────────────────────────────┤
│ PRB │ PRB │
├───────────┼──────────────────────────────────────────┤
│ PYG │ Paraguayan Guarani │
├───────────┼──────────────────────────────────────────┤
│ QAR │ Qatari Rial │
├───────────┼──────────────────────────────────────────┤
│ RON │ Romanian Leu │
├───────────┼──────────────────────────────────────────┤
│ RSD │ Serbian Dinar │
├───────────┼──────────────────────────────────────────┤
│ RUB │ Russian Ruble │
├───────────┼──────────────────────────────────────────┤
│ RWF │ Rwandan Franc │
├───────────┼──────────────────────────────────────────┤
│ SAR │ Saudi Riyal │
├───────────┼──────────────────────────────────────────┤
│ SBD │ Solomon Islands Dollar │
├───────────┼──────────────────────────────────────────┤
│ SCR │ Seychellois Rupee │
├───────────┼──────────────────────────────────────────┤
│ SDG │ Sudanese Pound │
├───────────┼──────────────────────────────────────────┤
│ SEK │ Swedish Krona │
├───────────┼──────────────────────────────────────────┤
│ SGD │ Singapore Dollar │
├───────────┼──────────────────────────────────────────┤
│ SHP │ St. Helena Pound │
├───────────┼──────────────────────────────────────────┤
│ SLL │ Sierra Leonean Leone │
├───────────┼──────────────────────────────────────────┤
│ SLS │ SLS │
├───────────┼──────────────────────────────────────────┤
│ SOS │ Somali Shilling │
├───────────┼──────────────────────────────────────────┤
│ SRD │ Surinamese Dollar │
├───────────┼──────────────────────────────────────────┤
│ SSP │ South Sudanese Pound │
├───────────┼──────────────────────────────────────────┤
│ STN │ São Tomé & Príncipe Dobra │
├───────────┼──────────────────────────────────────────┤
│ SYP │ Syrian Pound │
├───────────┼──────────────────────────────────────────┤
│ SZL │ Swazi Lilangeni │
├───────────┼──────────────────────────────────────────┤
│ THB │ Thai Baht │
├───────────┼──────────────────────────────────────────┤
│ TJS │ Tajikistani Somoni │
├───────────┼──────────────────────────────────────────┤
│ TMT │ Turkmenistani Manat │
├───────────┼──────────────────────────────────────────┤
│ TND │ Tunisian Dinar │
├───────────┼──────────────────────────────────────────┤
│ TOP │ Tongan Paʻanga │
├───────────┼──────────────────────────────────────────┤
│ TRY │ Turkish Lira │
├───────────┼──────────────────────────────────────────┤
│ TTD │ Trinidad & Tobago Dollar │
├───────────┼──────────────────────────────────────────┤
│ TVD │ TVD │
├───────────┼──────────────────────────────────────────┤
│ TWD │ New Taiwan Dollar │
├───────────┼──────────────────────────────────────────┤
│ TZS │ Tanzanian Shilling │
├───────────┼──────────────────────────────────────────┤
│ UAH │ Ukrainian Hryvnia │
├───────────┼──────────────────────────────────────────┤
│ UGX │ Ugandan Shilling │
├───────────┼──────────────────────────────────────────┤
│ USD │ US Dollar │
├───────────┼──────────────────────────────────────────┤
│ UYU │ Uruguayan Peso │
├───────────┼──────────────────────────────────────────┤
│ UZS │ Uzbekistani Som │
├───────────┼──────────────────────────────────────────┤
│ VES │ Venezuelan Bolívar │
├───────────┼──────────────────────────────────────────┤
│ VND │ Vietnamese Dong │
├───────────┼──────────────────────────────────────────┤
│ VUV │ Vanuatu Vatu │
├───────────┼──────────────────────────────────────────┤
│ WST │ Samoan Tala │
├───────────┼──────────────────────────────────────────┤
│ XAF │ Central African CFA Franc │
├───────────┼──────────────────────────────────────────┤
│ XCD │ East Caribbean Dollar │
├───────────┼──────────────────────────────────────────┤
│ XOF │ West African CFA Franc │
├───────────┼──────────────────────────────────────────┤
│ XPF │ CFP Franc │
├───────────┼──────────────────────────────────────────┤
│ YER │ Yemeni Rial │
├───────────┼──────────────────────────────────────────┤
│ ZAR │ South African Rand │
├───────────┼──────────────────────────────────────────┤
│ ZMW │ Zambian Kwacha │
├───────────┼──────────────────────────────────────────┤
│ ZWB │ ZWB │
└───────────┴──────────────────────────────────────────┘Run the following command in terminal to list all available currencies:
valuta-list-currenciesCustom currencies
To register a new custom currency, do as follows:
from valuta.base import BaseCurrency
class XYZ(BaseCurrency):
"""XYZ - The XYZ currency."""
uid: str = "XYZ"
rate: int = 100_000_000Generating currencies from a CSV dump
If list of circulating currencies is ever updated, grab it the same way, save as list_of_circulating_currencies.csv in the source and run the following command:
valuta-generate-currencies --skip-first-lineTesting
Simply type:
pytest -vvvOr use tox:
toxOr use tox to check specific env:
tox -e py39-django32Writing documentation
Keep the following hierarchy.
=====
title
=====
header
======
sub-header
----------
sub-sub-header
~~~~~~~~~~~~~~
sub-sub-sub-header
^^^^^^^^^^^^^^^^^^
sub-sub-sub-sub-header
++++++++++++++++++++++
sub-sub-sub-sub-sub-header
**************************License
GPL-2.0-only OR LGPL-2.1-or-later
Support
For any issues contact me at the e-mail given in the Author section.
1 maintainer
Release files for valuta 0.1.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| valuta-0.1.6.tar.gz | 62.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| valuta-0.1.6-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details |
Total release size: 163.0 kB
Release files / valuta-0.1.6.tar.gz
| Download URL | valuta-0.1.6.tar.gz |
|---|---|
| Size | 62.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4eaa9e214a917cebd8d8b252e4fc2621f20b34a7c68b03faac56d6943ce6a1d1
|
|
BLAKE2b-256 checksum How to use checksums |
5fa623c788e909efd2582e50543425e25bcc043d17d8533b5eb7bade85ed87ba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.6.13
|
Release files / valuta-0.1.6-py2.py3-none-any.whl
| Download URL | valuta-0.1.6-py2.py3-none-any.whl |
|---|---|
| Size | 100.7 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
91de36c56de8e31bce6ed14a9f2c0c48d21e39ab97b425611a79415cb1e60627
|
|
BLAKE2b-256 checksum How to use checksums |
b325481e47145a4dd53f629efe80e24b2be1a01bf61c8a23fe50e210ee4767fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.4.1 importlib_metadata/4.0.1 pkginfo/1.7.0 requests/2.25.1 requests-toolbelt/0.9.1 tqdm/4.60.0 CPython/3.6.13
|
