{"id":16969605,"url":"https://github.com/wilfredinni/dinero","last_synced_at":"2025-10-18T11:22:38.119Z","repository":{"id":62467557,"uuid":"552497976","full_name":"wilfredinni/dinero","owner":"wilfredinni","description":"Make exact monetary calculations","archived":false,"fork":false,"pushed_at":"2024-05-21T05:26:05.000Z","size":2236,"stargazers_count":9,"open_issues_count":10,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-05-21T11:42:32.269Z","etag":null,"topics":["amount","calculations","currency","immutable","monetary","money","python"],"latest_commit_sha":null,"homepage":"https://wilfredinni.github.io/dinero/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wilfredinni.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"wilfredinni"}},"created_at":"2022-10-16T18:20:22.000Z","updated_at":"2024-05-28T19:11:22.102Z","dependencies_parsed_at":"2023-10-15T00:46:50.646Z","dependency_job_id":"bb49e018-6843-4aee-a173-cb533d3c5485","html_url":"https://github.com/wilfredinni/dinero","commit_stats":{"total_commits":372,"total_committers":4,"mean_commits":93.0,"dds":0.553763440860215,"last_synced_commit":"0f9d153e1417a6d0e0907589f531fffb165f190d"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wilfredinni%2Fdinero","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wilfredinni%2Fdinero/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wilfredinni%2Fdinero/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wilfredinni%2Fdinero/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wilfredinni","download_url":"https://codeload.github.com/wilfredinni/dinero/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243852499,"owners_count":20358271,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amount","calculations","currency","immutable","monetary","money","python"],"created_at":"2024-10-14T00:25:52.830Z","updated_at":"2025-10-18T11:22:38.108Z","avatar_url":"https://github.com/wilfredinni.png","language":"Python","funding_links":["https://github.com/sponsors/wilfredinni"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Dinero\n### Precise, Type-Safe Monetary Calculations in Python\n\n[![PyPI][pypi-badge]][pypi-url]\n[![Build Status][build-badge]][build-url]\n[![CodeQL Status](https://github.com/wilfredinni/dinero/actions/workflows/github-code-scanning/codeql/badge.svg)](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\u003c!-- Badge URLs --\u003e\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\u003c!-- Links --\u003e\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\u003c/div\u003e\n\nDinero is a modern Python library that brings precision and type safety to monetary calculations. Built on Python's `Decimal` type, it provides an intuitive API for financial operations while ensuring accuracy and maintainability.\n\n[📚 Read the Full Documentation](https://wilfredinni.github.io/dinero/)\n\n## Key Features\n\n- 🎯 **Precise Calculations**: Built on Python's `Decimal` type for exact monetary computations\n- 🔒 **Type Safety**: Full type hint support and runtime validation\n- 🌍 **Currency Support**: Over 100 currencies following ISO 4217 standards\n- 🧮 **Financial Tools**: Built-in support for VAT, interest calculations, markup, and more\n- 🔄 **Immutable Objects**: Thread-safe with predictable behavior\n- 💪 **Modern Python**: Type hints, clean API, and comprehensive test coverage\n\n## Why Dinero?\n\nWorking with money in Python can be tricky due to floating-point arithmetic:\n\n```python\n\u003e\u003e\u003e 2.32 * 3 == 6.96\nFalse\n\u003e\u003e\u003e 2.32 * 3\n6.959999999999999  # Not ideal for financial calculations!\n```\n\nDinero makes it simple and safe:\n\n```python\n\u003e\u003e\u003e from dinero import Dinero\n\u003e\u003e\u003e from dinero.currencies import USD\n\u003e\u003e\u003e\n\u003e\u003e\u003e price = Dinero(\"2.32\", USD)  # Use strings for maximum precision\n\u003e\u003e\u003e total = price * 3\n\u003e\u003e\u003e print(total.format(symbol=True))  # \"$6.96\"\n\u003e\u003e\u003e total == Dinero(\"6.96\", USD)\nTrue\n```\n\n## Quick Start\n\n### Installation\n\n```bash\npip install dinero\n```\n\n### Basic Usage\n\n1. Create and Format Money:\n```python\nfrom dinero import Dinero\nfrom dinero.currencies import USD, EUR\n\n# Create monetary values\nprice = Dinero(\"99.99\", USD)\ndiscount = Dinero(\"10.00\", USD)\n\n# Format output\nprint(price.format(symbol=True, currency=True))  # \"$99.99 USD\"\n```\n\n2. Perform Currency-Safe Calculations:\n```python\n# Basic arithmetic\ntotal = price - discount  # Dinero(\"89.99\", USD)\n\n# Safe currency handling\neuro_price = Dinero(\"89.99\", EUR)\ntry:\n    total = price + euro_price  # Raises DifferentCurrencyError\nexcept DifferentCurrencyError:\n    print(\"Cannot add different currencies!\")\n```\n\n3. Use Financial Tools:\n```python\nfrom dinero.tools import calculate_vat_portion, calculate_compound_interest\n\n# Calculate VAT\nvat = calculate_vat_portion(price, 20)  # 20% VAT\nprint(vat.format(symbol=True))  # \"$20.00\"\n\n# Calculate compound interest\ninvestment = Dinero(\"10000\", USD)\nfuture_value = calculate_compound_interest(\n    principal=investment,\n    interest_rate=5,  # 5% annual rate\n    duration=10,      # 10 years\n    compound_frequency=12  # Monthly compounding\n)\n```\n\n4. Compare Monetary Values:\n```python\nfrom dinero.currencies import USD\n\nprice1 = Dinero(\"99.99\", USD)\nprice2 = Dinero(\"89.99\", USD)\n\n# Using comparison operators\nprice1 \u003e price2    # True - first price is higher\n\n# Using methods for more explicit code\nprice1.eq(price2)  # False - prices are not equal\nprice2.lt(price1)  # True - price2 is less than price1\n```\n\n5. Convert Between Currencies:\n```python\nfrom dinero.currencies import USD, EUR, JPY\n\n# Convert $100 USD to Euros with exchange rate 0.85\nusd_price = Dinero(\"100.00\", USD)\neur_price = usd_price.convert(\"0.85\", EUR)\neur_price.format(symbol=True)  # \"€85.00\"\n\n# Convert to Japanese Yen\njpy_price = usd_price.convert(\"110.50\", JPY)\njpy_price.format(symbol=True, currency=True)  # \"¥11,050 JPY\"\n```\n\n## Features\n\n### Type-Safe Currency Operations\n\n```python\n# Arithmetic operations\ntotal = price + shipping\nmonthly = rent * 12\nunit_cost = total_cost / quantity\n\n# Method chaining for complex calculations\nfinal_price = (\n    Dinero(\"100.00\", USD)\n    .multiply(1.20)  # Add 20% markup\n    .subtract(\"5.00\")  # Apply discount\n)\n```\n\n### Comparison Operators\n\n```python\n# Direct comparison operators\nprice1 \u003c price2            # Less than -\u003e returns True/False\nprice1 \u003c= price2           # Less than or equal -\u003e returns True/False\nprice1 \u003e price2            # Greater than -\u003e returns True/False\nprice1 \u003e= price2           # Greater than or equal -\u003e returns True/False\nprice1 == price2           # Equal -\u003e returns True/False\n\n# Method-based comparisons\nprice1.lt(price2)   # Less than -\u003e returns True/False\nprice1.lte(price2)  # Less than or equal -\u003e returns True/False\nprice1.gt(price2)   # Greater than -\u003e returns True/False\nprice1.gte(price2)  # Greater than or equal -\u003e returns True/False\nprice1.eq(price2)   # Equal -\u003e returns True/False\n```\n\n### Currency Conversion\n\n```python\nfrom dinero.currencies import USD, EUR, CLP\n\n# Convert USD to EUR with an exchange rate of 0.85\nusd_amount = Dinero(\"100\", USD)\neur_amount = usd_amount.convert(\"0.85\", EUR)\neur_amount.format(symbol=True)  # \"€85.00\"\n\n# Convert USD to CLP (which has 0 decimal places)\nclp_amount = usd_amount.convert(750, CLP)\nclp_amount.format(currency=True)  # \"75,000 CLP\"\n\n# Function-based conversion\nfrom dinero.tools.conversion import convert\njpy_amount = convert(usd_amount, \"110.25\", JPY)\njpy_amount.format()  # \"11,050\"\n```\n\n### Currency Support\n\n- Access over 100 pre-defined ISO 4217 currencies:\n```python\nfrom dinero.currencies import USD, EUR, GBP, JPY, BTC\n\n# Each currency knows its symbol and decimal places\namount = Dinero(\"42.42\", EUR)\nprint(amount.format(symbol=True))  # \"€42.42\"\n```\n\n- Create custom currencies:\n```python\nfrom dinero.types import Currency\n\nGOLD = {\n    \"code\": \"XAU\",\n    \"base\": 10,\n    \"exponent\": 4,  # 4 decimal places\n    \"symbol\": \"Au\"\n}\n\ngold_price = Dinero(\"1842.5930\", GOLD)\nprint(gold_price.format(symbol=True))  # \"Au1,842.5930\"\n```\n\n## Best Practices\n\n1. **Use String Inputs**: Avoid float precision issues by using strings:\n```python\n# Good ✅\namount = Dinero(\"42.42\", USD)\n\n# Avoid ❌\namount = Dinero(42.42, USD)  # Potential precision loss\n```\n\n2. **Handle Currency Mismatches**: Always validate currency compatibility:\n```python\n# Good ✅\ntry:\n    total = usd_price + eur_price\nexcept DifferentCurrencyError:\n    # Convert currencies or handle error\n```\n\n3. **Format for Display**: Use appropriate formatting options:\n```python\n# Full format with symbol and code\nprice.format(symbol=True, currency=True)  # \"$42.42 USD\"\n\n# Just the number\nprice.format()  # \"42.42\"\n```\n\nFor more detailed information and advanced features, check out our [comprehensive documentation](https://wilfredinni.github.io/dinero/).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilfredinni%2Fdinero","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilfredinni%2Fdinero","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilfredinni%2Fdinero/lists"}