<h1 align="center"> Dinero: Make exact monetary calculations</h1>
<p align="center">
<a href="https://pypi.org/project/dinero/">
<img alt="PyPI" src="https://img.shields.io/pypi/v/dinero">
</a>
<a href="https://pypi.org/project/dinero/">
<img alt="PyPI - Python Version" src="https://img.shields.io/pypi/pyversions/dinero">
</a>
<a href="https://github.com/wilfredinni/dinero/actions">
<img alt="Build status" src="https://github.com/wilfredinni/dinero/actions/workflows/test.yml/badge.svg" data-canonical-src="https://img.shields.io/github/workflow/status/Delgan/loguru/Tests/master" style="max-width: 100%;">
</a>
<a href="https://codecov.io/github/wilfredinni/dinero" >
<img alt="Codecov" src="https://img.shields.io/codecov/c/github/wilfredinni/dinero">
</a>
<a href="https://www.codacy.com/gh/wilfredinni/dinero/dashboard?utm_source=github.com&utm_medium=referral&utm_content=wilfredinni/dinero&utm_campaign=Badge_Grade">
<img alt="Codacy grade" src="https://img.shields.io/codacy/grade/d6b13235aec14905968fb4b0e9a5e8fd">
</a>
<a href="https://github.com/wilfredinni/dinero/blob/master/LICENSE">
<img alt="PyPI - License" src="https://img.shields.io/pypi/l/dinero">
</a>
</p>
<p align="center">
<img width="300" height="200" src="https://media.tenor.com/EWRvErYGzPUAAAAC/bugs-bunny-looney-tunes.gif">
</p>
This project is inspired by the excellent [dinero.js](https://github.com/dinerojs/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](https://wilfredinni.github.io/dinero/)
## Install
```bash
pip install dinero
```
## 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.
```python
>>> 2.32 * 3 == 6.96
False
>>> 2.32 * 3
6.959999999999999
```
You can read [How to Count Money Exactly in Python](https://learnpython.com/blog/count-money-python/) to get a better idea.
## Why Dinero?
A `Dinero` object is an immutable data structure representing a specific monetary value. It comes with methods for creating, parsing, manipulating, testing and formatting.
```python
>>> from dinero import Dinero
>>> from dinero.currencies import USD
>>>
>>> Dinero(2.32, USD) * 3 == Dinero(6.96. USD)
True
```
### Currencies
Dinero give you access to more than 100 different currencies:
```python
>>> from dinero.currencies import USD, EUR, GBP, INR, CLP
```
```python
>>> Dinero(2.32, EUR)
Dinero(amount=2.32, currency={'code': 'EUR', 'base': 10, 'exponent': 2, 'symbol': '€'})
```
```python
>>> Dinero(2.32, EUR).format(symbol=True, currency=True)
'€2.32 EUR'
```
```python
>>> Dinero(2.32, EUR).raw_amount
Decimal('2.32')
```
More about [currencies](https://wilfredinni.github.io/dinero/currencies/).
### Operations
Operations can be performed between Dinero objects or between Dinero objects and numbers by using Python operators or its own methods:
```python
>>> total = Dinero(456.343567, USD) + 345.32 * 3
>>> print(total)
# 1,492.30
```
```python
>>> total = (Dinero(345.32, USD).multiply(3)).add(456.343567)
>>> print(total)
# 1,492.30
```
More about [operations](https://wilfredinni.github.io/dinero/started/#operations).
### Comparisons
Dinero objects can be compared to each other by using Python comparison operators or by using its own methods:
```python
>>> Dinero(100, EUR) == Dinero(100, EUR)
True
```
```python
>>> Dinero(100, EUR).equals_to(Dinero(100, EUR))
True
```
More about [comparisons](https://wilfredinni.github.io/dinero/started/#comparisons).
### Tools
Dinero give you access to some useful tools that allow you to perform common monetary calculations, like percentages, VAT, simple and compound interests, etc.
```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_compound_interest
principal = Dinero("2000", USD)
total_interest = calculate_compound_interest(
principal=principal,
interest_rate=5,
duration=10,
compound_frequency=12,
)
total_interest.format(symbol=True, currency=True)
'$1,294.02 USD'
```
See all the available tools in the [tools](https://wilfredinni.github.io/dinero/tools/) section.
### Custom currencies
You can easily create custom currencies:
```python
from dinero import Dinero
BTC = {
"code": "BTC",
"base": 10,
"exponent": 2,
"symbol": "₿",
}
Dinero(1000.5, BTC)
```
```python
Dinero(amount=1000.5, currency={'code': 'BTC', 'base': 10, 'exponent': 2, 'symbol': '₿'})
```
More about [custom currencies](https://wilfredinni.github.io/dinero/currencies/#custom-currencies).
Raw data
{
"_id": null,
"home_page": "https://github.com/wilfredinni/dinero",
"name": "dinero",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "",
"keywords": "python3,money,decimals,calculations,currency",
"author": "Carlos Montecinos Geisse",
"author_email": "carlos@pythoncheatsheet.org",
"download_url": "https://files.pythonhosted.org/packages/3a/b1/7c9477d32ef90e1a041c2dedc214e5fc999227b6a69e8df537a59c4733dc/dinero-0.3.0.tar.gz",
"platform": null,
"description": "<h1 align=\"center\"> Dinero: Make exact monetary calculations</h1>\n\n<p align=\"center\">\n <a href=\"https://pypi.org/project/dinero/\">\n <img alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/dinero\">\n </a>\n <a href=\"https://pypi.org/project/dinero/\">\n <img alt=\"PyPI - Python Version\" src=\"https://img.shields.io/pypi/pyversions/dinero\">\n </a>\n <a href=\"https://github.com/wilfredinni/dinero/actions\">\n <img alt=\"Build status\" src=\"https://github.com/wilfredinni/dinero/actions/workflows/test.yml/badge.svg\" data-canonical-src=\"https://img.shields.io/github/workflow/status/Delgan/loguru/Tests/master\" style=\"max-width: 100%;\">\n </a>\n <a href=\"https://codecov.io/github/wilfredinni/dinero\" >\n <img alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/wilfredinni/dinero\">\n </a>\n <a href=\"https://www.codacy.com/gh/wilfredinni/dinero/dashboard?utm_source=github.com&utm_medium=referral&utm_content=wilfredinni/dinero&utm_campaign=Badge_Grade\">\n <img alt=\"Codacy grade\" src=\"https://img.shields.io/codacy/grade/d6b13235aec14905968fb4b0e9a5e8fd\">\n </a>\n <a href=\"https://github.com/wilfredinni/dinero/blob/master/LICENSE\">\n <img alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/dinero\">\n </a>\n</p>\n\n<p align=\"center\">\n <img width=\"300\" height=\"200\" src=\"https://media.tenor.com/EWRvErYGzPUAAAAC/bugs-bunny-looney-tunes.gif\">\n</p>\n\nThis project is inspired by the excellent [dinero.js](https://github.com/dinerojs/dinero.js) library.\n\nPython 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.\n\n[Read the Documentation](https://wilfredinni.github.io/dinero/)\n\n## Install\n\n```bash\npip install dinero\n```\n\n## The problem\n\n> 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\u2019s fine. But if you are calculating a transaction involving money, that\u2019s not what you want to see. Sure, you could round it off, but that's a little hacky.\n\n```python\n>>> 2.32 * 3 == 6.96\nFalse\n>>> 2.32 * 3\n6.959999999999999\n```\n\nYou can read [How to Count Money Exactly in Python](https://learnpython.com/blog/count-money-python/) to get a better idea.\n\n## Why Dinero?\n\nA `Dinero` object is an immutable data structure representing a specific monetary value. It comes with methods for creating, parsing, manipulating, testing and formatting.\n\n```python\n>>> from dinero import Dinero\n>>> from dinero.currencies import USD\n>>>\n>>> Dinero(2.32, USD) * 3 == Dinero(6.96. USD)\nTrue\n```\n\n### Currencies\n\nDinero give you access to more than 100 different currencies:\n\n```python\n>>> from dinero.currencies import USD, EUR, GBP, INR, CLP\n```\n\n```python\n>>> Dinero(2.32, EUR)\nDinero(amount=2.32, currency={'code': 'EUR', 'base': 10, 'exponent': 2, 'symbol': '\u20ac'})\n```\n\n```python\n>>> Dinero(2.32, EUR).format(symbol=True, currency=True)\n'\u20ac2.32 EUR'\n```\n\n```python\n>>> Dinero(2.32, EUR).raw_amount\nDecimal('2.32')\n```\n\nMore about [currencies](https://wilfredinni.github.io/dinero/currencies/).\n\n### Operations\n\nOperations can be performed between Dinero objects or between Dinero objects and numbers by using Python operators or its own methods:\n\n\n```python\n>>> total = Dinero(456.343567, USD) + 345.32 * 3\n>>> print(total)\n# 1,492.30\n```\n\n```python\n>>> total = (Dinero(345.32, USD).multiply(3)).add(456.343567)\n>>> print(total)\n# 1,492.30\n```\n\nMore about [operations](https://wilfredinni.github.io/dinero/started/#operations).\n\n### Comparisons\n\nDinero objects can be compared to each other by using Python comparison operators or by using its own methods:\n\n```python\n>>> Dinero(100, EUR) == Dinero(100, EUR)\nTrue\n```\n\n```python\n>>> Dinero(100, EUR).equals_to(Dinero(100, EUR))\nTrue\n```\n\nMore about [comparisons](https://wilfredinni.github.io/dinero/started/#comparisons).\n\n### Tools\n\nDinero give you access to some useful tools that allow you to perform common monetary calculations, like percentages, VAT, simple and compound interests, etc.\n\n```python\nfrom dinero import Dinero\nfrom dinero.currencies import USD\nfrom dinero.tools import calculate_compound_interest\n\nprincipal = Dinero(\"2000\", USD)\ntotal_interest = calculate_compound_interest(\n principal=principal,\n interest_rate=5,\n duration=10,\n compound_frequency=12,\n)\ntotal_interest.format(symbol=True, currency=True)\n'$1,294.02 USD'\n```\n\nSee all the available tools in the [tools](https://wilfredinni.github.io/dinero/tools/) section.\n\n### Custom currencies\n\nYou can easily create custom currencies:\n\n```python\nfrom dinero import Dinero\n\nBTC = {\n \"code\": \"BTC\",\n \"base\": 10,\n \"exponent\": 2,\n \"symbol\": \"\u20bf\",\n}\n\nDinero(1000.5, BTC)\n```\n\n```python\nDinero(amount=1000.5, currency={'code': 'BTC', 'base': 10, 'exponent': 2, 'symbol': '\u20bf'})\n```\n\nMore about [custom currencies](https://wilfredinni.github.io/dinero/currencies/#custom-currencies).",
"bugtrack_url": null,
"license": "MIT",
"summary": "Dinero is a library for working with monetary values in Python.",
"version": "0.3.0",
"project_urls": {
"Homepage": "https://github.com/wilfredinni/dinero",
"Repository": "https://github.com/wilfredinni/dinero"
},
"split_keywords": [
"python3",
"money",
"decimals",
"calculations",
"currency"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fda993239356e0f127b7c7c02e41e5431117b508b2c968fb3a3bc9acbc766ab7",
"md5": "d37c7ac4e26b7379581bc328638724e1",
"sha256": "d09d92acd8a790e154f1a15bc50670d9a3f7f109c3ea97f9ce26b18fa7ad7b28"
},
"downloads": -1,
"filename": "dinero-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d37c7ac4e26b7379581bc328638724e1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 48115,
"upload_time": "2023-10-14T00:45:57",
"upload_time_iso_8601": "2023-10-14T00:45:57.088826Z",
"url": "https://files.pythonhosted.org/packages/fd/a9/93239356e0f127b7c7c02e41e5431117b508b2c968fb3a3bc9acbc766ab7/dinero-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3ab17c9477d32ef90e1a041c2dedc214e5fc999227b6a69e8df537a59c4733dc",
"md5": "be8da7315c372374a61bd1ef34d6f5a5",
"sha256": "b40b39d4c3754f02732cc0c94a01f01c6fa516a51589c83d9e2745d4b12c2646"
},
"downloads": -1,
"filename": "dinero-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "be8da7315c372374a61bd1ef34d6f5a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 18234,
"upload_time": "2023-10-14T00:45:59",
"upload_time_iso_8601": "2023-10-14T00:45:59.048577Z",
"url": "https://files.pythonhosted.org/packages/3a/b1/7c9477d32ef90e1a041c2dedc214e5fc999227b6a69e8df537a59c4733dc/dinero-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-14 00:45:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wilfredinni",
"github_project": "dinero",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "dinero"
}
JSON
