valuta¶
Currencies done right
In most payment systems that went international, amounts are represented in integers, instead of decimals, as they are represented in minor currency units (smallest units 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.SQLAlchemy integration package (
valuta.contrib.sqlalchemy_integration
) has been tested with SQLAlchemy 1.4.x.
Documentation¶
Documentation is available on Read the Docs.
Installation¶
Latest stable version on PyPI:
pip install valuta
Or development version from GitHub:
pip install https://github.com/barseghyanartur/valuta/archive/master.tar.gz
Usage examples¶
Pure Python¶
Using currency classes directly¶
If you need numbers back for further calculations¶
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.0
valuta.JPY.convert_to_currency_units(1_000)
# 10.0
If you need to display the values and want a nice string back¶
import valuta
valuta.EUR.display_in_currency_units(1_000)
# '€10.00'
valuta.UGX.display_in_currency_units(1_000)
# 'UGX1,000'
valuta.MRU.display_in_currency_units(1_000)
# 'MRU200.00'
valuta.VND.display_in_currency_units(1_000)
# '₫100'
valuta.TND.display_in_currency_units(1_000)
# 'TND1.000'
valuta.JPY.display_in_currency_units(1_000)
# '¥10'
Custom string formatting¶
Based on the specifics of the given currency, displayed numbers may have or not may have decimal points.
The display_in_currency_units
method accepts optional format
,
locale
and decimal_quantization
arguments. Most common values for
format
are listed in the valuta.constants
.
DISPLAY_FORMAT_NUMBER
Example values: '10000'
or '10000.00'
.
DISPLAY_FORMAT_HUMAN_READABLE
Displays a human readable number.
Example values: '10,000'
or '10,000.00'
.
DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_CODE
Displays a human readable number with currency code.
Example values: 'JPY 10,000'
or 'EUR 10,000.00'
.
DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_SYMBOL
Displays a human readable number with currency symbol.
Example values: '¥ 10,000'
or '€ 10,000.00'
.
A couple of examples:
from valuta.constants import *
valuta.JPY.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE
)
# '10,000'
valuta.JPY.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_CODE
)
# 'JPY 10,000'
valuta.JPY.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_SYMBOL
)
# '¥ 10,000'
valuta.EUR.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE
)
# '10,000.00'
valuta.EUR.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_CODE
)
# 'EUR 10,000.00'
valuta.EUR.display_in_currency_units(
1_000_000,
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_SYMBOL
)
# '€ 10,000.00'
valuta.JPY.display_in_currency_units(1_000_000_000, locale="nl_NL")
# 'JP¥\xa010.000.000'
valuta.JPY.display_in_currency_units(1_000_000_000, locale="en_US")
# '¥10,000,000'
valuta.EUR.display_in_currency_units(1_000_000_000, locale="nl_NL")
# '€\xa010.000.000,00'
valuta.EUR.display_in_currency_units(1_000_000_000, locale="en_US")
# '€10,000,000.00'
valuta.AMD.display_in_currency_units(1_000_000_000, locale="en_US")
# 'AMD10,000,000.00'
valuta.AMD.display_in_currency_units(1_000_000_000, locale="hy_AM")
# '10 000 000,00 ֏'
Working with string representations of the (ISO-4217) currency codes¶
If you need numbers back for further calculations¶
from valuta.shortcuts import convert_to_currency_units
convert_to_currency_units("EUR", 1_000)
# 10.0
convert_to_currency_units("UGX", 1_000)
# 1000.0
convert_to_currency_units("MRU", 1_000)
# 200.0
convert_to_currency_units("VND", 1_000)
# 100.0
convert_to_currency_units("TND", 1_000)
# 1.0
convert_to_currency_units("JPY", 1_000)
# 10.0
If you need to display the values and want a nice string back¶
from valuta.shortcuts import display_in_currency_units
display_in_currency_units("EUR", 1_000)
# '€10.00'
display_in_currency_units("UGX", 1_000)
# 'UGX1,000'
display_in_currency_units("MRU", 1_000)
# 'MRU200.00'
display_in_currency_units("VND", 1_000)
# '₫100'
display_in_currency_units("TND", 1_000)
# 'TND1.000'
display_in_currency_units("JPY", 1_000)
# '¥10'
By default, exceptions arising from invalid currency codes are
suppressed (None
will be returned on invalid currency codes).
If you want to throw exception on invalid currency codes, set fail_silently
to False
. The following example will throw a
valuta.exceptions.InvalidCurrency
exception.
convert_to_currency_units("i-dont-exist", 1_000, fail_silently=False)
The display_in_currency_units
shortcut function also accepts
optional format
argument.
Django integration¶
In its basis, Django integration package is a CurrencyField
representing
the 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 (magic) methods to the model class
for converting field amounts to major currency units (often simply called
currency units
).
There are also template tags and filters for when you need to render non-model data (for instance, JSON) in templates without prior pre-processing.
Installation¶
pip install valuta[django]
Model field¶
Model definition¶
Sample model
product/models.py
from django.db import models
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"])
Sample data
import valuta
from product.models import Product
product = Product.objects.create(
name="My test product",
price=100,
price_with_tax=120,
currency=valuta.AMD.uid,
)
Converting amounts using magic methods¶
You could then refer to the price and price_with_tax as follows:
product.price_in_currency_units()
# 1.0
product.price_with_tax_in_currency_units()
# 1.2
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.
Converting amounts for display using magic methods¶
You could then refer to the price and price_with_tax as follows:
product.price_display_in_currency_units()
# 'AMD1.00'
product.price_with_tax_display_in_currency_units()
# 'AMD1.20'
Note, that every field listed in the amount_fields
gets a correspondent
model method with suffix _display_in_currency_units
for converting the field
amounts to (major) currency units.
Magic methods also accept optional format
argument.
product = Product.objects.create(
name="My test product",
price=100_000,
price_with_tax=120_000,
currency=valuta.EUR.uid,
)
product.price_display_in_currency_units(
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_SYMBOL
)
# '€ 1,000.00'
product.price_with_tax_display_in_currency_units(
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_CODE
)
# 'EUR 1,200.00'
Combining format
and locale
arguments.
product.price_display_in_currency_units(
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_SYMBOL,
locale="nl_NL"
)
# '€ 1.000,00'
product.price_with_tax_display_in_currency_units(
format=DISPLAY_FORMAT_HUMAN_READABLE_WITH_CURRENCY_CODE,
locale="nl_NL"
)
# 'EUR 1.200,00'
Limiting the currency choices¶
On the field level¶
You could limit the currency choices as follows:
currency = CurrencyField(
amount_fields=["price", "price_with_tax"],
limit_choices_to=[valuta.AMD.uid, valuta.EUR.uid],
)
Globally¶
You could also override the CurrencyField
choices in the Django settings:
settings.py
VALUTA_FIELD_LIMIT_CHOICES_TO=(
valuta.AMD.uid,
valuta.EUR.uid,
)
Casting the converted values¶
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 the 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.base 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 values
And then use it as follows:
currency = CurrencyField(
amount_fields=("price", "price_with_tax",),
get_choices_func=get_currency_choices_with_sign,
)
SQLAlchemy integration¶
Similarly to Django integration package, the SQLAlchemy integration package is
a simple CurrencyType
representing the ISO-4217 codes of the currencies.
No magic methods are implemented yet (although planned to). What you get
is a simple SQLAlchemy type for storing the data. For the rest you will have
to make use of the valuta.shortcuts
.
See examples/sqlalchemy_example/valuta_admin/models.py as a good example.
Installation¶
pip install valuta[sqlalchemy]
Model definition¶
Sample model
product/models.py
from valuta.contrib.sqlalchemy_integration.types import CurrencyType
from . import db # Standard SQLAlchemy way
class Product(db.Model):
id = db.Column(db.Integer, primary_key=True)
name = db.Column(db.Unicode(64), unique=True)
price = db.Column(db.Integer())
price_with_tax = db.Column(db.Integer())
currency = db.Column(CurrencyType())
Sample data
import valuta
from product.models import Product
product = Product(
name="My test product",
price=100,
price_with_tax=120,
currency=valuta.AMD.uid,
)
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-currencies
Custom 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_000
Generating 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-line
Testing¶
Simply type:
pytest -vvv
Or use tox:
tox
Or use tox to check specific env:
tox -e py39-django32
Writing 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.
Project documentation¶
Contents:
Table of Contents
- valuta
- Prerequisites
- Documentation
- Installation
- Usage examples
- Pure Python
- Django integration
- Installation
- Model field
- Template tags and filters
- SQLAlchemy integration
- Supported currencies
- Custom currencies
- Generating currencies from a CSV dump
- Testing
- Writing documentation
- License
- Support
- Author
- Project documentation
- Release history and notes
- valuta package
- Subpackages
- valuta.contrib package
- valuta.currencies package
- Submodules
- valuta.currencies.aed module
- valuta.currencies.afn module
- valuta.currencies.all module
- valuta.currencies.amd module
- valuta.currencies.ang module
- valuta.currencies.aoa module
- valuta.currencies.ars module
- valuta.currencies.aud module
- valuta.currencies.awg module
- valuta.currencies.azn module
- valuta.currencies.bam module
- valuta.currencies.bbd module
- valuta.currencies.bdt module
- valuta.currencies.bgn module
- valuta.currencies.bhd module
- valuta.currencies.bif module
- valuta.currencies.bmd module
- valuta.currencies.bnd module
- valuta.currencies.bob module
- valuta.currencies.brl module
- valuta.currencies.bsd module
- valuta.currencies.btc module
- valuta.currencies.btn module
- valuta.currencies.bwp module
- valuta.currencies.byn module
- valuta.currencies.bzd module
- valuta.currencies.cad module
- valuta.currencies.cdf module
- valuta.currencies.chf module
- valuta.currencies.ckd module
- valuta.currencies.clp module
- valuta.currencies.cny module
- valuta.currencies.cop module
- valuta.currencies.crc module
- valuta.currencies.cup module
- valuta.currencies.cve module
- valuta.currencies.czk module
- valuta.currencies.djf module
- valuta.currencies.dkk module
- valuta.currencies.dop module
- valuta.currencies.dzd module
- valuta.currencies.egp module
- valuta.currencies.ern module
- valuta.currencies.etb module
- valuta.currencies.eur module
- valuta.currencies.fjd module
- valuta.currencies.fkp module
- valuta.currencies.fok module
- valuta.currencies.gbp module
- valuta.currencies.gel module
- valuta.currencies.ggp module
- valuta.currencies.ghs module
- valuta.currencies.gip module
- valuta.currencies.gmd module
- valuta.currencies.gnf module
- valuta.currencies.gtq module
- valuta.currencies.gyd module
- valuta.currencies.hkd module
- valuta.currencies.hnl module
- valuta.currencies.hrk module
- valuta.currencies.htg module
- valuta.currencies.huf module
- valuta.currencies.idr module
- valuta.currencies.ils module
- valuta.currencies.imp module
- valuta.currencies.inr module
- valuta.currencies.iqd module
- valuta.currencies.irr module
- valuta.currencies.isk module
- valuta.currencies.jep module
- valuta.currencies.jmd module
- valuta.currencies.jod module
- valuta.currencies.jpy module
- valuta.currencies.kes module
- valuta.currencies.kgs module
- valuta.currencies.khr module
- valuta.currencies.kid module
- valuta.currencies.kmf module
- valuta.currencies.kpw module
- valuta.currencies.krw module
- valuta.currencies.kwd module
- valuta.currencies.kyd module
- valuta.currencies.kzt module
- valuta.currencies.lak module
- valuta.currencies.lbp module
- valuta.currencies.lkr module
- valuta.currencies.lrd module
- valuta.currencies.lsl module
- valuta.currencies.lyd module
- valuta.currencies.mad module
- valuta.currencies.mdl module
- valuta.currencies.mga module
- valuta.currencies.mkd module
- valuta.currencies.mmk module
- valuta.currencies.mnt module
- valuta.currencies.mop module
- valuta.currencies.mru module
- valuta.currencies.mur module
- valuta.currencies.mvr module
- valuta.currencies.mwk module
- valuta.currencies.mxn module
- valuta.currencies.myr module
- valuta.currencies.mzn module
- valuta.currencies.nad module
- valuta.currencies.ngn module
- valuta.currencies.nio module
- valuta.currencies.nok module
- valuta.currencies.npr module
- valuta.currencies.nzd module
- valuta.currencies.omr module
- valuta.currencies.pab module
- valuta.currencies.pen module
- valuta.currencies.pgk module
- valuta.currencies.php module
- valuta.currencies.pkr module
- valuta.currencies.pln module
- valuta.currencies.pnd module
- valuta.currencies.prb module
- valuta.currencies.pyg module
- valuta.currencies.qar module
- valuta.currencies.ron module
- valuta.currencies.rsd module
- valuta.currencies.rub module
- valuta.currencies.rwf module
- valuta.currencies.sar module
- valuta.currencies.sbd module
- valuta.currencies.scr module
- valuta.currencies.sdg module
- valuta.currencies.sek module
- valuta.currencies.sgd module
- valuta.currencies.shp module
- valuta.currencies.sll module
- valuta.currencies.sls module
- valuta.currencies.sos module
- valuta.currencies.srd module
- valuta.currencies.ssp module
- valuta.currencies.stn module
- valuta.currencies.syp module
- valuta.currencies.szl module
- valuta.currencies.thb module
- valuta.currencies.tjs module
- valuta.currencies.tmt module
- valuta.currencies.tnd module
- valuta.currencies.top module
- valuta.currencies.try module
- valuta.currencies.ttd module
- valuta.currencies.tvd module
- valuta.currencies.twd module
- valuta.currencies.tzs module
- valuta.currencies.uah module
- valuta.currencies.ugx module
- valuta.currencies.usd module
- valuta.currencies.uyu module
- valuta.currencies.uzs module
- valuta.currencies.ves module
- valuta.currencies.vnd module
- valuta.currencies.vuv module
- valuta.currencies.wst module
- valuta.currencies.xaf module
- valuta.currencies.xcd module
- valuta.currencies.xof module
- valuta.currencies.xpf module
- valuta.currencies.yer module
- valuta.currencies.zar module
- valuta.currencies.zmw module
- valuta.currencies.zwb module
- Module contents
- valuta.tests package
- Submodules
- valuta.base module
- valuta.cli module
- valuta.exceptions module
- valuta.helpers module
- valuta.registry module
- valuta.scaffolding module
- valuta.shortcuts module
- valuta.utils module
- Module contents
- Subpackages
- Indices and tables
- Release history and notes
- valuta package
- Subpackages
- valuta.contrib package
- valuta.currencies package
- Submodules
- valuta.currencies.aed module
- valuta.currencies.afn module
- valuta.currencies.all module
- valuta.currencies.amd module
- valuta.currencies.ang module
- valuta.currencies.aoa module
- valuta.currencies.ars module
- valuta.currencies.aud module
- valuta.currencies.awg module
- valuta.currencies.azn module
- valuta.currencies.bam module
- valuta.currencies.bbd module
- valuta.currencies.bdt module
- valuta.currencies.bgn module
- valuta.currencies.bhd module
- valuta.currencies.bif module
- valuta.currencies.bmd module
- valuta.currencies.bnd module
- valuta.currencies.bob module
- valuta.currencies.brl module
- valuta.currencies.bsd module
- valuta.currencies.btc module
- valuta.currencies.btn module
- valuta.currencies.bwp module
- valuta.currencies.byn module
- valuta.currencies.bzd module
- valuta.currencies.cad module
- valuta.currencies.cdf module
- valuta.currencies.chf module
- valuta.currencies.ckd module
- valuta.currencies.clp module
- valuta.currencies.cny module
- valuta.currencies.cop module
- valuta.currencies.crc module
- valuta.currencies.cup module
- valuta.currencies.cve module
- valuta.currencies.czk module
- valuta.currencies.djf module
- valuta.currencies.dkk module
- valuta.currencies.dop module
- valuta.currencies.dzd module
- valuta.currencies.egp module
- valuta.currencies.ern module
- valuta.currencies.etb module
- valuta.currencies.eur module
- valuta.currencies.fjd module
- valuta.currencies.fkp module
- valuta.currencies.fok module
- valuta.currencies.gbp module
- valuta.currencies.gel module
- valuta.currencies.ggp module
- valuta.currencies.ghs module
- valuta.currencies.gip module
- valuta.currencies.gmd module
- valuta.currencies.gnf module
- valuta.currencies.gtq module
- valuta.currencies.gyd module
- valuta.currencies.hkd module
- valuta.currencies.hnl module
- valuta.currencies.hrk module
- valuta.currencies.htg module
- valuta.currencies.huf module
- valuta.currencies.idr module
- valuta.currencies.ils module
- valuta.currencies.imp module
- valuta.currencies.inr module
- valuta.currencies.iqd module
- valuta.currencies.irr module
- valuta.currencies.isk module
- valuta.currencies.jep module
- valuta.currencies.jmd module
- valuta.currencies.jod module
- valuta.currencies.jpy module
- valuta.currencies.kes module
- valuta.currencies.kgs module
- valuta.currencies.khr module
- valuta.currencies.kid module
- valuta.currencies.kmf module
- valuta.currencies.kpw module
- valuta.currencies.krw module
- valuta.currencies.kwd module
- valuta.currencies.kyd module
- valuta.currencies.kzt module
- valuta.currencies.lak module
- valuta.currencies.lbp module
- valuta.currencies.lkr module
- valuta.currencies.lrd module
- valuta.currencies.lsl module
- valuta.currencies.lyd module
- valuta.currencies.mad module
- valuta.currencies.mdl module
- valuta.currencies.mga module
- valuta.currencies.mkd module
- valuta.currencies.mmk module
- valuta.currencies.mnt module
- valuta.currencies.mop module
- valuta.currencies.mru module
- valuta.currencies.mur module
- valuta.currencies.mvr module
- valuta.currencies.mwk module
- valuta.currencies.mxn module
- valuta.currencies.myr module
- valuta.currencies.mzn module
- valuta.currencies.nad module
- valuta.currencies.ngn module
- valuta.currencies.nio module
- valuta.currencies.nok module
- valuta.currencies.npr module
- valuta.currencies.nzd module
- valuta.currencies.omr module
- valuta.currencies.pab module
- valuta.currencies.pen module
- valuta.currencies.pgk module
- valuta.currencies.php module
- valuta.currencies.pkr module
- valuta.currencies.pln module
- valuta.currencies.pnd module
- valuta.currencies.prb module
- valuta.currencies.pyg module
- valuta.currencies.qar module
- valuta.currencies.ron module
- valuta.currencies.rsd module
- valuta.currencies.rub module
- valuta.currencies.rwf module
- valuta.currencies.sar module
- valuta.currencies.sbd module
- valuta.currencies.scr module
- valuta.currencies.sdg module
- valuta.currencies.sek module
- valuta.currencies.sgd module
- valuta.currencies.shp module
- valuta.currencies.sll module
- valuta.currencies.sls module
- valuta.currencies.sos module
- valuta.currencies.srd module
- valuta.currencies.ssp module
- valuta.currencies.stn module
- valuta.currencies.syp module
- valuta.currencies.szl module
- valuta.currencies.thb module
- valuta.currencies.tjs module
- valuta.currencies.tmt module
- valuta.currencies.tnd module
- valuta.currencies.top module
- valuta.currencies.try module
- valuta.currencies.ttd module
- valuta.currencies.tvd module
- valuta.currencies.twd module
- valuta.currencies.tzs module
- valuta.currencies.uah module
- valuta.currencies.ugx module
- valuta.currencies.usd module
- valuta.currencies.uyu module
- valuta.currencies.uzs module
- valuta.currencies.ves module
- valuta.currencies.vnd module
- valuta.currencies.vuv module
- valuta.currencies.wst module
- valuta.currencies.xaf module
- valuta.currencies.xcd module
- valuta.currencies.xof module
- valuta.currencies.xpf module
- valuta.currencies.yer module
- valuta.currencies.zar module
- valuta.currencies.zmw module
- valuta.currencies.zwb module
- Module contents
- valuta.tests package
- Submodules
- valuta.base module
- valuta.cli module
- valuta.exceptions module
- valuta.helpers module
- valuta.registry module
- valuta.scaffolding module
- valuta.shortcuts module
- valuta.utils module
- Module contents
- Subpackages