Dinero

Make exact monetary calculations

Description

This project is inspired by the excellent dinero.js library.

Python Decimal instances are enough for basic monetary calculations, but when you face more complex use-cases they often show limitations and are not so intuitive to work with. Dinero provides a cleaner and easier to use API while still relying on the standard library. So it's still Decimal, but easier.

Read the Documentation

Programming language: Python

License: MIT License

Tags: RESTful API     Flask     Money     Python     Python3     Immutable     Currency     Calculations     Amount    

README

Dinero: Make exact monetary calculations

This project is inspired by the excellent dinero.js library.

A Dinero object is an immutable data structure representing a specific monetary value. It comes with methods for creating, parsing, manipulating, testing and formatting them.

Read the Documentation

The problem

Using floats to do exact calculations in Python can be dangerous. When you try to find out how much 2.32 x 3 is, Python tells you it's 6.959999999999999. For some calculations, that’s fine. But if you are calculating a transaction involving money, that’s not what you want to see. Sure, you could round it off, but that's a little hacky.

>>> 2.32 * 3 == 6.96
False
>>> 2.32 * 3
6.959999999999999

You can read How to Count Money Exactly in Python to get a better idea.

Why Dinero?

Python Decimal instances are enough for basic cases but when you face more complex use-cases they often show limitations and are not so intuitive to work with. Dinero provides a cleaner and more easy to use API while still relying on the standard library. So it's still Decimal but easier.

>>> from dinero import Dinero
>>> from dinero.currencies import USD
>>>
>>> Dinero(2.32, USD) * 3 == 6.96
True

Currencies

Dinero give you access to more than 100 different currencies:

>>> from dinero.currencies import USD, EUR, GBP, INR, CLP

>>> Dinero(2.32, EUR)
Dinero(amount=2.32, currency={'code': 'EUR', 'base': 10, 'exponent': 2, 'symbol': '€'})

>>> Dinero(2.32, EUR).format(symbol=True, currency=True)
'€2.32 EUR'

>>> Dinero(2.32, EUR).raw_amount
Decimal('2.32')

Operations

>>> total = Dinero(456.343567, USD) + 345.32 *  3
>>> print(total)
# 1,492.30

>>> product = Dinero(345.32, USD).multiply(3)
>>> total = product.add(456.343567)
>>> print(total)
# 1,492.30

Comparisons

>>> Dinero(100, EUR) == Dinero(100, EUR)
True

>>> Dinero(100, EUR).equals_to(Dinero(100, EUR))
True

>>> Dinero(100, EUR) == 100
True

>>> Dinero(100, EUR).equals_to(100)
True

Custom currencies

You can easily create custom currencies:

from dinero import Dinero

BTC = {
    "code": "BTC",
    "base": 10,
    "exponent": 2,
    "symbol": "₿",
}

Dinero(1000.5, BTC)

Dinero(amount=1000.5, currency={'code': 'BTC', 'base': 10, 'exponent': 2, 'symbol': '₿'})