<div align="center">
# Dinero
### Make exact monetary calculations.
[![PyPI][pypi-badge]][pypi-url]
[![Build Status][build-badge]][build-url]
[](https://github.com/wilfredinni/dinero/actions/workflows/github-code-scanning/codeql)
[![Codecov][codecov-badge]][codecov-url]
[![License][license-badge]][license-url]
<!-- Badge URLs -->
[pypi-badge]: https://img.shields.io/pypi/v/dinero
[build-badge]: https://github.com/wilfredinni/dinero/actions/workflows/test.yml/badge.svg
[codecov-badge]: https://img.shields.io/codecov/c/github/wilfredinni/dinero
[license-badge]: https://img.shields.io/pypi/l/dinero
<!-- Links -->
[pypi-url]: https://pypi.org/project/dinero/
[build-url]: https://github.com/wilfredinni/dinero/actions
[codecov-url]: https://codecov.io/github/wilfredinni/dinero
[license-url]: https://github.com/wilfredinni/dinero/blob/master/LICENSE
</div>
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 represent 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
>>> amount = Dinero(2.32, EUR)
>>> amount.format(symbol=True, currency=True)
'€2.32 EUR'
>>>
>>> amount.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:
```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:
```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": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "python3, money, decimals, calculations, currency",
"author": "Carlos Montecinos Geisse",
"author_email": "carlos@pythoncheatsheet.org",
"download_url": "https://files.pythonhosted.org/packages/e0/a9/d876fef5dd1a010278a89bfd81d68addf691800fa1086463a0e7412beca8/dinero-0.3.1.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Dinero\n### Make exact monetary calculations.\n\n[![PyPI][pypi-badge]][pypi-url]\n[![Build Status][build-badge]][build-url]\n[](https://github.com/wilfredinni/dinero/actions/workflows/github-code-scanning/codeql)\n[![Codecov][codecov-badge]][codecov-url]\n[![License][license-badge]][license-url]\n\n<!-- Badge URLs -->\n[pypi-badge]: https://img.shields.io/pypi/v/dinero\n[build-badge]: https://github.com/wilfredinni/dinero/actions/workflows/test.yml/badge.svg\n[codecov-badge]: https://img.shields.io/codecov/c/github/wilfredinni/dinero\n[license-badge]: https://img.shields.io/pypi/l/dinero\n\n<!-- Links -->\n[pypi-url]: https://pypi.org/project/dinero/\n[build-url]: https://github.com/wilfredinni/dinero/actions\n[codecov-url]: https://codecov.io/github/wilfredinni/dinero\n[license-url]: https://github.com/wilfredinni/dinero/blob/master/LICENSE\n</div>\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 represent 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>>> amount = Dinero(2.32, EUR)\n>>> amount.format(symbol=True, currency=True)\n'\u20ac2.32 EUR'\n>>>\n>>> amount.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:\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:\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.1",
"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": "a6c63ff12ae118a1de79f53f44dc1f9732143406d28307829459dc093e5a5a01",
"md5": "d97ef96e337219dc4b7ec98b56fd188a",
"sha256": "0976c1f69fe6e6542084ef03346624520288805ce4b2c543d1a836cf375621a8"
},
"downloads": -1,
"filename": "dinero-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d97ef96e337219dc4b7ec98b56fd188a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 48522,
"upload_time": "2024-10-31T21:40:15",
"upload_time_iso_8601": "2024-10-31T21:40:15.640216Z",
"url": "https://files.pythonhosted.org/packages/a6/c6/3ff12ae118a1de79f53f44dc1f9732143406d28307829459dc093e5a5a01/dinero-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e0a9d876fef5dd1a010278a89bfd81d68addf691800fa1086463a0e7412beca8",
"md5": "e8f6fcf5b27590261cae6a76ea2b3f95",
"sha256": "231744ce90801e1a13df43eaeb6644998e437ebc122e7d0278f595150143e973"
},
"downloads": -1,
"filename": "dinero-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "e8f6fcf5b27590261cae6a76ea2b3f95",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 17825,
"upload_time": "2024-10-31T21:40:17",
"upload_time_iso_8601": "2024-10-31T21:40:17.031789Z",
"url": "https://files.pythonhosted.org/packages/e0/a9/d876fef5dd1a010278a89bfd81d68addf691800fa1086463a0e7412beca8/dinero-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-31 21:40:17",
"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
