Usage¶
The Money
class is instantiated with:
An amount which can be of type int, string, float, or Decimal. It will be converted to a Decimal internally. Therefore, it is best to avoid float objects, since they do not convert losslessly to Decimal.
A currency, as a
Currency
object, or as a string which is a three-capital-letters ISO currency code (e.g.'USD'
,'EUR'
etc), which will be converted to aCurrency
object.
For example,
from moneyed import Money
sale_price_today = Money(amount='99.99', currency='USD')
You then use Money
instances as a normal number. The Money class provides
operators with type checking, matching currency checking, and sensible
dimensional behavior, e.g. you cannot multiply two Money instances, nor can you
add a Money instance to a non-Money number; dividing a Money instance by another
results in a Decimal value, etc.
The Currency
class is also provided. All ISO 4217 currencies are
available by importing from the moneyed
module by their 3-letter code, as
pre-built Currency
objects.
You can also pass in the arguments to Money
as positional arguments. So
you can also write:
>>> from moneyed import Money, USD
>>> price = Money('19.50', USD)
>>> price
Money('19.50', 'USD')
>>> price.amount
Decimal('19.50')
>>> price.currency
USD
>>> price.currency.code
'USD'
If you want to get the amount in sub units (ISO 4127 compatible) you can do:
>>> from moneyed import Money, USD
>>> price = Money('19.50', USD)
>>> price.get_amount_in_sub_unit()
1950
>>> price = Money('123.456', USD)
>>> price.get_amount_in_sub_unit()
12345
Currency instances have a zero
property for convenience. It returns a cached
Money
instance of the currency. This can be helpful for instance when summing up a
list of money instances using the builtin sum()
.
>>> from moneyed import Money, USD
>>> currency = USD
>>> items = (Money('19.99', currency), Money('25.00', currency))
>>> sum(items, currency.zero)
Money('44.99', 'USD')
>>> sum((), currency.zero)
Money('0', 'USD')
Search by Country Code¶
In order to find the ISO code associated with a country, the function
get_currencies_of_country()
can be used. This function takes the ISO
country code (case insensitive) as the argument and returns the associated
currency object(s) in a list. If a country with the given name is not found the
function returns an empty list. The code below demonstrates this:
>>> from moneyed import get_currencies_of_country
>>> get_currencies_of_country("IN")
[INR]
>>> get_currencies_of_country("BO")
[BOB, BOV]
>>> get_currencies_of_country("XX")
[]
Get country names¶
Currency.country_codes
returns a list of ISO 3166 country codes. You can
convert these to names using the function get_country_name
, which must be
passed a ISO 2-letter code and a locale code:
>>> from moneyed import ZMW, get_country_name
>>> ZMW.country_codes
['ZM']
>>> get_country_name('ZM', 'en')
'Zambia'
List all currencies¶
You can get all installed currencies as below:
>>> from moneyed import list_all_currencies
>>> list_all_currencies()
[ADP, AED, AFA, ...]
The result is a list of Currency
objects, sorted by ISO code.