### Install Dinero and Activate Shell

Source: https://github.com/wilfredinni/dinero/blob/master/CONTRIBUTING.md

Install Dinero using Poetry and activate the project's virtual environment. This prepares the environment for development.

```bash
$ poetry install
$ poetry shell
```

--------------------------------

### Perform Basic Monetary Operations

Source: https://github.com/wilfredinni/dinero/blob/master/project-resume.md

Examples of creating instances, performing arithmetic, and formatting output.

```python
# Basic monetary calculations
price = Dinero(2.32, USD)
quantity = 3
total = price.multiply(quantity)  # $6.96

# Currency formatting
price.format(symbol=True)  # "$2.32"
price.format(currency=True)  # "2.32 USD"

# Arithmetic operations
total = price1.add(price2)
discount = total.multiply(0.1)
```

--------------------------------

### Install Dinero Python Package

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Command to install the Dinero library using pip. Ensure you have Python and pip installed.

```bash
pip install dinero
```

--------------------------------

### Clone Dinero Repository

Source: https://github.com/wilfredinni/dinero/blob/master/CONTRIBUTING.md

Clone the Dinero project locally to begin development. Navigate into the cloned directory to proceed with setup.

```bash
$ git clone git@github.com:your_name_here/Dinero.git
$ cd dinero
```

--------------------------------

### Perform Precise Monetary Calculations with Dinero

Source: https://github.com/wilfredinni/dinero/blob/master/docs/index.md

Example of creating a Dinero object and performing arithmetic operations with currency precision.

```python
>>> from dinero import Dinero
>>> from dinero.currencies import USD
>>>
>>> price = Dinero("2.32", USD)  # Use strings for maximum precision
>>> total = price * 3
>>> print(total.format(symbol=True))  # "$6.96"
>>> total == Dinero("6.96", USD)
True
```

--------------------------------

### Perform Addition with Dinero

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Examples of adding monetary values using methods or operators, including handling lists of objects.

```python
from dinero import Dinero
from dinero.currencies import EUR

amount = Dinero("333.3", EUR)
total = amount.add(333.3)
print(total)
```

```python
from dinero import Dinero
from dinero.currencies import EUR, CLP

amount_1 = Dinero("333.3", CLP)
amount_2 = Dinero(333.3, CLP)

total = amount_1.add(amount_2)
print(total.format(symbol=True, currency=True))
```

```python
from dinero import Dinero
from dinero.currencies import EUR, USD

amount_1 = Dinero("333.3", USD)
amount_2 = Dinero(333.3, USD)

total = amount_1 + amount_2
print(total)
```

```python
from dinero import Dinero
from dinero.currencies import EUR, USD

amount_1 = Dinero("333.3", EUR)
amount_2 = Dinero(333.3, EUR)
amount_3 = Dinero(333.3, EUR)

total = sum([amount_1, amount_2, amount_3])
print(total)
```

--------------------------------

### Dinero Precise Monetary Calculation Example

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Shows how to use Dinero to perform accurate monetary calculations, ensuring precision and correct results. Use strings for initial Dinero object creation to maintain maximum precision.

```python
>>> from dinero import Dinero
>>> from dinero.currencies import USD
>>> 
>>> price = Dinero("2.32", USD)  # Use strings for maximum precision
>>> total = price * 3
>>> print(total.format(symbol=True))  # "$6.96"
>>> total == Dinero("6.96", USD)
True
```

--------------------------------

### Get Dinero Version

Source: https://github.com/wilfredinni/dinero/blob/master/CONTRIBUTING.md

Retrieve the installed Dinero version for bug reporting. Ensure you are using a compatible Python version.

```python
print(dinero.__version__)
```

--------------------------------

### Dinero Comparison Operators Usage

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Provides examples of using direct comparison operators (>, <, >=, <=, ==) to compare Dinero objects. These comparisons are precise and respect currency types.

```python
# Direct comparison operators
price1 < price2            # Less than -> returns True/False
price1 <= price2           # Less than or equal -> returns True/False
price1 > price2            # Greater than -> returns True/False
price1 >= price2           # Greater than or equal -> returns True/False
price1 == price2           # Equal -> returns True/False
```

--------------------------------

### Dinero Financial Tools: VAT Calculation

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Example of using the `calculate_vat_portion` function from Dinero's tools to compute the Value Added Tax for a given amount and percentage. The result is a Dinero object representing the VAT amount.

```python
from dinero.tools import calculate_vat_portion

# Calculate VAT
vat = calculate_vat_portion(price, 20)  # 20% VAT
print(vat.format(symbol=True))  # "$20.00"
```

--------------------------------

### Dinero Type-Safe Arithmetic Operations

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Shows examples of performing common arithmetic operations like addition, multiplication, division, and subtraction with Dinero objects. These operations are type-safe and maintain precision.

```python
# Arithmetic operations
total = price + shipping
monthly = rent * 12
unit_cost = total_cost / quantity

# Method chaining for complex calculations
final_price = (
    Dinero("100.00", USD)
    .multiply(1.20)  # Add 20% markup
    .subtract("5.00")  # Apply discount
)
```

--------------------------------

### Initialize and Format Dinero Objects

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Demonstrates creating a Dinero instance and accessing its properties or formatting it as a string.

```python
from dinero import Dinero
from dinero.currencies import CLP, USD

amount = Dinero(234342.3010, USD)
amount.raw_amount
amount.symbol
amount.code

formatted = amount.format(symbol=True, currency=True)
print(formatted)
```

```python
# Import the library and currency definitions
from dinero import Dinero
from dinero.currencies import CLP, USD

# Create a Dinero instance with a USD amount
amount = Dinero(234342.3010, USD)

# Access properties
print(f"Raw amount: {amount.raw_amount}")
print(f"Symbol: {amount.symbol}")
print(f"Currency code: {amount.code}")

# Format with symbol and currency code
formatted = amount.format(symbol=True, currency=True)
print(f"Formatted: {formatted}")

total = Dinero(456.343567, USD) + 345.32 / 4534.4 *  3
print(total)
```

--------------------------------

### Compare Dinero Instances

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Shows how to compare monetary values for equality.

```python
from dinero import Dinero
from dinero.currencies import CLP, USD

unit_price = Dinero(2.32, USD)
number_sold = 3
money_received = Dinero(6.96, USD)
if unit_price * number_sold == money_received:
    print('Accounts balanced')
else:
    raise ValueError('Accounts not balanced')
```

--------------------------------

### Define Custom BTC Currency and Initialize Dinero

Source: https://github.com/wilfredinni/dinero/blob/master/docs/currencies.md

Defines a custom Bitcoin currency with an exponent of 8 and demonstrates initializing Dinero objects with string amounts for precision, showing formatting with symbol and currency code.

```python
from dinero import Dinero
from dinero.types import Currency # Recommended for type hinting

BTC: Currency = {
    "code": "BTC",
    "base": 10,      # Standard for decimal-based representation
    "exponent": 8,   # Bitcoin is typically represented with 8 decimal places (Satoshis)
    "symbol": "₿",
}

# Initialize with a string for precision, representing 1000.50 BTC
btc_amount = Dinero("1000.50000000", BTC)
print(btc_amount.format(symbol=True)) # Outputs: ₿1,000.50000000

# Example representing 1 Satoshi (0.00000001 BTC)
one_satoshi = Dinero("0.00000001", BTC)
print(one_satoshi.format(currency=True)) # Outputs: 0.00000001 BTC
```

--------------------------------

### Create Dinero Objects

Source: https://context7.com/wilfredinni/dinero/llms.txt

Initialize monetary values using strings, integers, or Decimals. String inputs are recommended to maintain maximum precision.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR, JPY

# Create with string (recommended for precision)
price = Dinero("99.99", USD)

# Create with integer
quantity = Dinero(100, USD)

# Create with Decimal
from decimal import Decimal
exact_amount = Dinero(Decimal("19.99"), EUR)

# Access properties
print(price.raw_amount)  # Decimal('99.99')
print(price.symbol)      # '$'
print(price.code)        # 'USD'
print(price.exponent)    # 2
print(price.precision)   # 10
```

--------------------------------

### Add and Commit Changes

Source: https://github.com/wilfredinni/dinero/blob/master/CONTRIBUTING.md

Stage all modified files and commit them with a descriptive message. This prepares your changes for pushing to the remote repository.

```bash
$ git add .
$ git commit -m 'Add succinct explanation of what changed'
```

--------------------------------

### Initialize Dinero Object

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Create a Dinero object using a string or numeric amount and a currency definition.

```python
from dinero import Dinero
from dinero.currencies import USD

amount = Dinero("100.40", USD) # Initialize with string for precision
```

--------------------------------

### Dinero Currency Conversion

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Illustrates how to convert monetary values between different currencies using the `convert` method. Provide the exchange rate and the target currency.

```python
from dinero.currencies import USD, EUR, JPY

# Convert $100 USD to Euros with exchange rate 0.85
usd_price = Dinero("100.00", USD)
eur_price = usd_price.convert("0.85", EUR)
eur_price.format(symbol=True)  # "€85.00"

# Convert to Japanese Yen
jpy_price = usd_price.convert("110.50", JPY)
jpy_price.format(symbol=True, currency=True)  # "¥11,050 JPY"
```

--------------------------------

### Use Financial Tools for VAT and Interest

Source: https://github.com/wilfredinni/dinero/blob/master/docs/index.md

Utilize built-in tools to calculate VAT portions and compound interest on monetary values.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_vat_portion, calculate_compound_interest

# Calculate VAT (see more in [Tools](tools.md))
# Example: Calculate 20% VAT from a gross price of $120.00
gross_price = Dinero("120.00", USD)
vat_on_gross = calculate_vat_portion(gross_price, 20) # 20% VAT rate
print(f"VAT portion from {gross_price.format(symbol=True)} at 20%: {vat_on_gross.format(symbol=True)}") # "$20.00"

# Calculate compound interest (interest earned)
investment = Dinero("10000", USD)
# The function calculate_compound_interest returns the interest earned.
interest_earned = calculate_compound_interest(
    principal=investment,
    interest_rate=5,  # 5% annual rate
    duration=10,      # 10 years
    compound_frequency=12  # Monthly compounding
)
# Output based on Decimal calculation (actual Dinero output might vary slightly due to internal precision)
print(f"Interest earned over 10 years: {interest_earned.format(symbol=True, currency=True)}") # "$6,470.09 USD (Interest Earned)"
```

--------------------------------

### Dinero Comparison Operators

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Demonstrates how to compare monetary values using standard comparison operators like '>', '<', '==', etc. These operations are currency-aware and ensure accurate comparisons.

```python
from dinero.currencies import USD

price1 = Dinero("99.99", USD)
price2 = Dinero("89.99", USD)

# Using comparison operators
price1 > price2    # True - first price is higher

# Using methods for more explicit code
price1.eq(price2)  # False - prices are not equal
price2.lt(price1)  # True - price2 is less than price1
```

--------------------------------

### Define Typed Custom BTC Currency

Source: https://github.com/wilfredinni/dinero/blob/master/docs/currencies.md

Demonstrates defining a custom Bitcoin currency using type hints with `dinero.types.Currency` and initializing a Dinero object with this typed definition, showing formatted output.

```python
from dinero import Dinero # Ensure Dinero is imported for the example
from dinero.types import Currency

BTC_definition: Currency = { # Renamed to avoid conflict with BTC above if in same scope
    "code": "BTC",
    "base": 10,
    "exponent": 8, # Consistent with the example above (8 decimal places for Bitcoin)
    "symbol": "₿",
}

# Example of creating a Dinero object with the typed currency definition
my_btc_balance = Dinero("0.12345678", BTC_definition)
print(my_btc_balance.format(symbol=True, currency=True)) # Outputs: ₿0.12345678 BTC
```

--------------------------------

### Create Custom Currency

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Define and use custom currencies by providing a dictionary with 'code', 'base', 'exponent' (decimal places), and 'symbol'.

```python
from dinero.types import Currency

GOLD = {
    "code": "XAU",
    "base": 10,
    "exponent": 4,  # 4 decimal places
    "symbol": "Au"
}

gold_price = Dinero("1842.5930", GOLD)
print(gold_price.format(symbol=True))  # "Au1,842.5930"
```

--------------------------------

### Use String Inputs for Precision

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Initialize with strings to avoid floating-point precision issues.

```python
from dinero import Dinero
from dinero.currencies import USD

# Good ✅ - Preserves exact precision
price_string = Dinero("19.99", USD)
fee_string = Dinero("0.05", USD)

# Avoid ❌ - Can lead to precision loss with certain floats
# price_float = Dinero(19.99, USD) # e.g., 19.99 might be stored as 19.989999...
# fee_float = Dinero(0.05, USD)   # e.g., 0.05 might be stored as 0.050000...
```

--------------------------------

### Dinero Formatting

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Details on how to format Dinero objects into strings, dictionaries, and JSON.

```APIDOC
## Formatting

### String Formatting

You can return a formatted string representation of `Dinero` with the `format` method:

-   `format()`: Returns the amount as a string.
    ```python
    >>> Dinero(2.32, EUR).format()
    '2.32'
    ```
-   `format(symbol=True)`: Returns the amount with the currency symbol.
    ```python
    >>> Dinero(2.32, EUR).format(symbol=True)
    '€2.32'
    ```
-   `format(currency=True)`: Returns the amount with the currency code.
    ```python
    >>> Dinero(2.32, EUR).format(currency=True)
    '2.32 EUR'
    ```
-   `format(symbol=True, currency=True)`: Returns the amount with both symbol and currency code.
    ```python
    >>> Dinero(2.32, EUR).format(symbol=True, currency=True)
    '€2.32 EUR'
    ```

### Dictionary Formatting

Return a `Dinero` instance as a Python Dictionary:

-   `to_dict()`: Converts the Dinero object to a dictionary without amount formatting.
    ```python
    >>> Dinero("3333.259", USD).to_dict()
    {
        'amount': '3333.26',
        'currency':
            {
                'code': 'USD',
                'base': 10,
                'exponent': 2,
                'symbol': '$'
            }
    }
    ```
-   `to_dict(amount_with_format=True)`: Converts the Dinero object to a dictionary with amount formatting (e.g., using commas).
    ```python
    >>> Dinero('3333.26', USD).to_dict(amount_with_format=True)
    {
        'amount': '3,333.26',
        'currency':
            {
                'code': 'USD',
                'base': 10,
                'exponent': 2,
                'symbol': '$'
            }
    }
    ```

### JSON Formatting

Return a `Dinero` instance as a `JSON` string:

-   `to_json()`: Converts the Dinero object to a JSON string without amount formatting.
    ```python
    >>> from dinero import Dinero
    >>> from dinero.currencies import USD
    >>> d = Dinero("1234.56", USD)
    >>> d.to_json()
    '{"amount": "1234.56", "currency": {"code": "USD", "base": 10, "exponent": 2, "symbol": "$"}}'
    ```
-   `to_json(amount_with_format=True)`: Converts the Dinero object to a JSON string with amount formatting.
    ```python
    >>> from dinero import Dinero
    >>> from dinero.currencies import USD
    >>> d = Dinero("1234.56", USD)
    >>> d.to_json(amount_with_format=True)
    '{"amount": "1,234.56", "currency": {"code": "USD", "base": 10, "exponent": 2, "symbol": "$"}}'
    ```
```

--------------------------------

### Compare Prices

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Use comparison methods to check the relationship between two monetary values. These methods return a boolean.

```python
price1.lt(price2)   # Less than -> returns True/False
price1.lte(price2)  # Less than or equal -> returns True/False
price1.gt(price2)   # Greater than -> returns True/False
price1.gte(price2)  # Greater than or equal -> returns True/False
price1.eq(price2)   # Equal -> returns True/False
```

--------------------------------

### Create Custom Currency

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Defines a custom currency dictionary and uses it to initialize a Dinero object.

```python
from dinero import Dinero

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

Dinero(1000.5, BTC)
```

--------------------------------

### Dinero Basic Usage: Create and Format Money

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Illustrates how to create Dinero objects with specific amounts and currencies, and how to format them for display. Supports various formatting options like currency symbols and codes.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR

# Create monetary values
price = Dinero("99.99", USD)
discount = Dinero("10.00", USD)

# Format output
print(price.format(symbol=True, currency=True))  # "$99.99 USD"
```

--------------------------------

### Convert Currencies

Source: https://context7.com/wilfredinni/dinero/llms.txt

Convert monetary values between different currencies using exchange rates via instance methods or the conversion tool.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR, CLP, JPY
from dinero.tools.conversion import convert

# Method usage - convert $100 USD to EUR at 0.85 rate
usd_amount = Dinero("100", USD)
eur_amount = usd_amount.convert("0.85", EUR)
print(eur_amount.format(symbol=True, currency=True))  # '€85.00 EUR'

# Convert to currency with 0 decimal places (Chilean Peso)
clp_amount = usd_amount.convert(750, CLP)
print(clp_amount.format(currency=True))  # '75,000 CLP'

# Function usage
jpy_amount = convert(usd_amount, "110.25", JPY)
print(jpy_amount.format(symbol=True, currency=True))  # '¥11,025 JPY'
```

--------------------------------

### Format Dinero for Display

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Use the format method to generate string representations for UI or reports.

```python
# Example:
# formatted_price = price_string.format(symbol=True, currency=True) # "$19.99 USD"
# print(formatted_price)
```

--------------------------------

### Dinero Operations

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Explains how to perform arithmetic operations and currency conversions with Dinero objects.

```APIDOC
## Operations

If the addend or subtrahend is an `str`, `int`, `float` or `Decimal`, it will be transformed, under the hood, to a Dinero instance using the same currency:

### Addition

-   `add(other)` or `+` operator: Adds another amount to the current Dinero object.
    ```python
    # those operations
    Dinero(1000, USD).add(Dinero(1000, USD))
    Dinero(1000, USD) + Dinero(1000, USD)

    # are equivalent to
    Dinero(1000, USD).add(1000)
    Dinero(1000, USD) + 1000
    ```

### Subtraction

-   `subtract(other)` or `-` operator: Subtracts another amount from the current Dinero object.
    ```python
    # those operations
    Dinero(1000, USD).subtract(Dinero(100, USD))
    Dinero(1000, USD) - Dinero(100, USD)

    # are equivalent to
    Dinero(1000, USD).subtract(1000)
    Dinero(1000, USD) - 100
    ```

### Currency Conversion

-   `convert(exchange_rate, to_currency)`: Converts the Dinero object to a different currency.
    ```python
    from dinero.currencies import USD, EUR, CLP

    # Convert USD to EUR with an exchange rate of 0.85
    usd_amount = Dinero("100", USD)
    eur_amount = usd_amount.convert("0.85", EUR)
    eur_amount.format(symbol=True)
    '€85.00'
    ```
```

--------------------------------

### Financial Calculation Tools

Source: https://github.com/wilfredinni/dinero/blob/master/docs/api.md

Utility modules for performing common financial calculations including VAT, interest, and margins.

```APIDOC
## Financial Tools

### VAT Tools (dinero.tools.vat)
- calculate_net_amount
- calculate_vat_portion
- calculate_gross_amount

### Percentage Tools (dinero.tools.percentage)
- calculate_percentage

### Interest Tools (dinero.tools.interest)
- calculate_simple_interest
- calculate_compound_interest

### Markup Tools (dinero.tools.markup)
- calculate_base_amount
- calculate_markup_portion
- calculate_marked_up_amount

### Margin Tools (dinero.tools.margin)
- calculate_cost_amount
- calculate_margin_portion
- calculate_selling_price
```

--------------------------------

### Calculate Markup

Source: https://context7.com/wilfredinni/dinero/llms.txt

Calculate base amounts, markup portions, and marked-up amounts for retail pricing.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools.markup import calculate_base_amount, calculate_markup_portion, calculate_marked_up_amount
```

--------------------------------

### Convert USD to CLP using method

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Converts a Dinero object from USD to CLP using a specified exchange rate. The exchange rate can be provided as an integer.

```python
# Convert USD to CLP with an exchange rate of 750
clp_amount = usd_amount.convert(750, CLP)
clp_amount.format(currency=True)
'75,000 CLP'
```

--------------------------------

### Convert USD to EUR using method

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Converts a Dinero object from USD to EUR using a specified exchange rate. Ensure the exchange rate is provided as a string or float.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR, CLP

# Convert USD to EUR with an exchange rate of 0.85
usd_amount = Dinero("100", USD)
eur_amount = usd_amount.convert("0.85", EUR)
eur_amount.format(symbol=True, currency=True)
'€85.00 EUR'
```

--------------------------------

### Use String Inputs for Dinero

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Instantiate Dinero objects with string inputs for amounts to prevent potential floating-point precision issues.

```python
# Good ✅
amount = Dinero("42.42", USD)

# Avoid ❌
amount = Dinero(42.42, USD)  # Potential precision loss
```

--------------------------------

### Markup Calculations

Source: https://context7.com/wilfredinni/dinero/llms.txt

Calculate base amounts, markup portions, and final selling prices based on a percentage markup.

```python
final_amount = Dinero(115, USD)
base_amount = calculate_base_amount(final_amount, 15)
print(base_amount.format(symbol=True, currency=True))  # '$100.00 USD'

# Extract markup portion from final price
markup = calculate_markup_portion(final_amount, 15)
print(markup.format(symbol=True, currency=True))  # '$15.00 USD'

# Calculate final price with 15% markup
cost = Dinero(100, USD)
selling_price = calculate_marked_up_amount(cost, 15)
print(selling_price.format(symbol=True, currency=True))  # '$115.00 USD'
```

--------------------------------

### Use Currency Type Hint

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Applies the Currency type hint to a custom currency definition.

```python
from dinero.types import Currency

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

Dinero(1000.5, BTC)
```

--------------------------------

### Error Handling

Source: https://context7.com/wilfredinni/dinero/llms.txt

Manage currency mismatches and invalid operations using specific exception classes.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR
from dinero.exceptions import DifferentCurrencyError, InvalidOperationError

# Handle currency mismatch in arithmetic
usd_price = Dinero("100.00", USD)
eur_price = Dinero("85.00", EUR)

try:
    total = usd_price + eur_price
except DifferentCurrencyError as e:
    print(f"Error: {e}")  # "Currencies can not be different"
    # Convert first, then add
    converted = eur_price.convert("1.18", USD)
    total = usd_price + converted
    print(total.format(symbol=True))  # '$200.30'

# Handle invalid comparison
try:
    result = Dinero(100, USD) == 100  # Can't compare to non-Dinero
except InvalidOperationError as e:
    print(f"Error: {e}")  # "You can only compare against other Dinero instances."
```

--------------------------------

### Margin Calculations

Source: https://context7.com/wilfredinni/dinero/llms.txt

Calculate cost amounts, margin portions, and selling prices based on profit margin percentage.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools.margin import calculate_cost_amount, calculate_margin_portion, calculate_selling_price

# Extract cost from selling price with 20% margin
selling_price = Dinero(100, USD)
cost = calculate_cost_amount(selling_price, 20)
print(cost.format(symbol=True, currency=True))  # '$80.00 USD'

# Extract margin portion from selling price
margin = calculate_margin_portion(selling_price, 20)
print(margin.format(symbol=True, currency=True))  # '$20.00 USD'

# Calculate selling price from cost with 20% margin
cost_amount = Dinero(80, USD)
price = calculate_selling_price(cost_amount, 20)
print(price.format(symbol=True, currency=True))  # '$100.00 USD'
```

--------------------------------

### Function-based Currency Conversion

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Utilize the `convert` tool for currency conversions. This function requires the source amount, exchange rate, and target currency.

```python
from dinero.tools.conversion import convert
jpy_amount = convert(usd_amount, "110.25", JPY)
jpy_amount.format()  # "11,050"
```

--------------------------------

### Calculate Gross Amount from Net Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Calculates the gross amount (including VAT) by adding VAT to a net amount. Requires importing the calculate_gross_amount tool.

```python
from dinero.tools.vat import calculate_gross_amount

net_amount = Dinero(100, USD)  # Amount without VAT
gross_amount = calculate_gross_amount(net_amount, 20)
gross_amount.format(symbol=True, currency=True)
'$120.00 USD'
```

--------------------------------

### Calculate Marked Up Amount from Base Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Adds markup to a base amount to calculate the final selling price. Requires the base amount and the markup rate as a percentage.

```python
from dinero.tools.markup import calculate_marked_up_amount

base_amount = Dinero(100, USD)  # Amount without markup
final_amount = calculate_marked_up_amount(base_amount, 15)
final_amount.format(symbol=True, currency=True)
'$115.00 USD'
```

--------------------------------

### Calculate VAT

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Utility functions for calculating gross amounts and VAT portions.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools.vat import calculate_gross_amount

# Amount including 20% VAT
total = Dinero(120, USD)

# Get the amount without VAT
net_amount = calculate_gross_amount(total, 19)
print(f"Total (inc. VAT): {total.format(symbol=True)}")
print(f"Net amount: {net_amount.format(symbol=True)}")
```

```python
from dinero.tools.vat import calculate_vat_portion

# Calculate VAT portion from total amount
vat = calculate_vat_portion(total, 20)
print(f"VAT amount: {vat.format(symbol=True)}")

# Verify that net + VAT = total
print(f"Net + VAT = Total: {(net_amount + vat) == total}")
```

```python
from dinero.tools.vat import calculate_gross_amount

# Start with net amount
net_price = Dinero(100, USD)
```

--------------------------------

### Demonstrate Dinero Object Immutability

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Illustrates that operations on Dinero objects return new instances, leaving the original unchanged. Verifies object identity.

```python
from dinero import Dinero
from dinero.currencies import USD

initial_price = Dinero("100.00", USD)
discount = Dinero("10.00", USD)

# Subtracting the discount creates a new Dinero object
final_price = initial_price - discount

# The original object remains unchanged
print(f"Initial price: {initial_price.format(symbol=True)}")  # $100.00
print(f"Final price: {final_price.format(symbol=True)}")    # $90.00

assert initial_price == Dinero("100.00", USD) # Value is the same
assert final_price == Dinero("90.00", USD)
assert id(initial_price) != id(final_price) # They are different objects
```

--------------------------------

### Perform Addition with Dinero

Source: https://context7.com/wilfredinni/dinero/llms.txt

Add monetary values using the add() method or the + operator. Non-Dinero inputs are automatically converted to the base currency.

```python
from dinero import Dinero
from dinero.currencies import USD

amount_1 = Dinero("2.32", USD)
amount_2 = Dinero("2.32", USD)

# Using method
result = amount_1.add(amount_2)
print(result.format(symbol=True))  # '$4.64'

# Using operator
result = Dinero("2.32", USD) + Dinero("2.32", USD)
print(result.format(symbol=True))  # '$4.64'

# Add raw values (automatically converted to Dinero)
result = Dinero("2.32", USD) + "2.32"
print(result.format(symbol=True))  # '$4.64'

result = Dinero(1000, USD).add(500)
print(result.format(symbol=True))  # '$1,500.00'
```

--------------------------------

### Calculate Percentage of an Amount

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Calculates a percentage of a given Dinero amount. Requires importing calculate_percentage from dinero.tools.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_percentage

amount = Dinero("3000", USD)
vat_amount = calculate_percentage(
    amount=amount,
    percentage=15,
)
vat_amount.format(symbol=True, currency=True)
```

--------------------------------

### Test Directory Structure

Source: https://github.com/wilfredinni/dinero/blob/master/project-resume.md

The standard layout for organizing core functionality, arithmetic, utility, and validation tests.

```text
tests/
├── test_dinero.py      # Core functionality tests
├── test_operations.py  # Arithmetic operations tests
├── test_utils.py      # Utility function tests
└── test_validators.py # Validation logic tests
```

--------------------------------

### Calculate VAT

Source: https://context7.com/wilfredinni/dinero/llms.txt

Extract net amounts and VAT portions from gross prices, or calculate gross amounts from net prices.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools.vat import calculate_net_amount, calculate_vat_portion, calculate_gross_amount

# Extract net amount from gross (price including 20% VAT)
gross_amount = Dinero(120, USD)
net_amount = calculate_net_amount(gross_amount, 20)
print(net_amount.format(symbol=True, currency=True))  # '$100.00 USD'

# Extract VAT portion from gross amount
vat = calculate_vat_portion(gross_amount, 20)
print(vat.format(symbol=True, currency=True))  # '$20.00 USD'

# Calculate gross amount from net (add 20% VAT)
net_price = Dinero(100, USD)
gross_price = calculate_gross_amount(net_price, 20)
print(gross_price.format(symbol=True, currency=True))  # '$120.00 USD'
```

--------------------------------

### Perform Division Operations

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Shows various ways to divide Dinero objects using methods or operators.

```python
from dinero import Dinero
from dinero.currencies import EUR

amount = Dinero("20", EUR)
total = amount.divide(2)
print(total)
```

```python
from dinero import Dinero
from dinero.currencies import EUR

amount = Dinero("20.00", EUR)
total = amount.divide(2)
print(total)
```

```python
from dinero import Dinero
from dinero.currencies import EUR

amount = Dinero("20.00", EUR)
total = amount / 2
print(total)
```

```python
from dinero import Dinero
from dinero.currencies import EUR

amount = Dinero("20", EUR)
total = amount / 2
print(total)
```

```python
# different currencies will raise a DifferentCurrencyError
from dinero import Dinero
from dinero.currencies import EUR, USD
from dinero.exceptions import DifferentCurrencyError

amount_1 = Dinero("20", EUR)

try:
    amount_1.divide(2)
    print(amount_1 / 2)
except DifferentCurrencyError:
    print("Can not operate with different currencies")
```

--------------------------------

### Apply Type Safety

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Use type hints for Dinero objects and currency definitions to improve code clarity and static analysis.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.types import Currency

# Dinero objects are fully typed
price: Dinero = Dinero("100", USD)

# Currency dictionaries can be typed too
# For example, when defining a custom currency:
gold_currency_def: Currency = {"code": "XAU", "base": 10, "exponent": 2, "symbol": "Gold"}
# gold_price: Dinero = Dinero("1500", gold_currency_def) # Example usage
```

--------------------------------

### Dinero Class Methods

Source: https://github.com/wilfredinni/dinero/blob/master/docs/api.md

Core methods for the Dinero class to handle currency formatting, arithmetic operations, comparisons, and serialization.

```APIDOC
## Dinero Class Methods

### Description
Provides methods for currency arithmetic, comparison, and data export.

### Methods
- format: Formats the currency value.
- add: Adds a value to the Dinero object.
- subtract: Subtracts a value from the Dinero object.
- multiply: Multiplies the Dinero object value.
- divide: Divides the Dinero object value.
- convert: Converts the currency.
- eq, gt, gte, lt, lte: Comparison operators.
- to_dict: Exports to dictionary format.
- to_json: Exports to JSON format.
```

--------------------------------

### Calculate Percentages

Source: https://context7.com/wilfredinni/dinero/llms.txt

Compute specific percentages of monetary values, useful for discounts or tax calculations.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_percentage

# Calculate 15% of $3000
amount = Dinero("3000", USD)
percentage_amount = calculate_percentage(amount=amount, percentage=15)
print(percentage_amount.format(symbol=True, currency=True))  # '$450.00 USD'

# Calculate 10% discount
original_price = Dinero("250.00", USD)
discount = calculate_percentage(amount=original_price, percentage=10)
final_price = original_price - discount
print(f"Discount: {discount.format(symbol=True)}")      # 'Discount: $25.00'
print(f"Final: {final_price.format(symbol=True)}")     # 'Final: $225.00'
```

--------------------------------

### Format and Export Dinero Values

Source: https://context7.com/wilfredinni/dinero/llms.txt

Convert monetary objects into formatted strings, dictionaries, or JSON representations.

```python
from dinero import Dinero
from dinero.currencies import USD, EUR

amount = Dinero("234342.30", USD)

# Basic formatting
print(amount.format())                              # '234,342.30'
print(amount.format(symbol=True))                   # '$234,342.30'
print(amount.format(currency=True))                 # '234,342.30 USD'
print(amount.format(symbol=True, currency=True))   # '$234,342.30 USD'

# Export as dictionary
data = Dinero("3333.26", USD).to_dict()
# {'amount': '3333.26', 'currency': {'code': 'USD', 'base': 10, 'exponent': 2, 'symbol': '$'}}

# With formatted amount
data_formatted = Dinero("3333.26", USD).to_dict(amount_with_format=True)
# {'amount': '3,333.26', 'currency': {'code': 'USD', 'base': 10, 'exponent': 2, 'symbol': '$'}}

# Export as JSON
json_str = Dinero("1234.56", USD).to_json()
# '{"amount": "1234.56", "currency": {"code": "USD", "base": 10, "exponent": 2, "symbol": "$"}}'
```

--------------------------------

### Calculate Selling Price from Cost Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Calculates the final selling price by adding a desired profit margin to a cost amount. Requires the cost amount and the desired margin rate as a percentage of the selling price.

```python
from dinero.tools.margin import calculate_selling_price

cost_amount = Dinero(80, USD)  # Cost amount before margin
selling_price = calculate_selling_price(cost_amount, 20)
selling_price.format(symbol=True, currency=True)
'$100.00 USD'
```

--------------------------------

### VAT Calculations

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Provides functions for calculating net amount, VAT portion, and gross amount.

```APIDOC
## VAT Calculations

The library provides three functions for working with VAT (Value Added Tax):

### Calculate Net Amount

Extracts the net amount (excluding VAT) from a gross amount (including VAT).

#### Parameters
- **amount** (Dinero object) - Required - The gross amount (including VAT).
- **vat_rate** (float) - Required - The VAT rate as a percentage.

### Calculate VAT Portion

Extracts just the VAT amount from a gross amount.

#### Parameters
- **amount** (Dinero object) - Required - The gross amount (including VAT).
- **vat_rate** (float) - Required - The VAT rate as a percentage.

### Calculate Gross Amount

Adds VAT to a net amount to get the gross amount.

#### Parameters
- **amount** (Dinero object) - Required - The net amount (excluding VAT).
- **vat_rate** (float) - Required - The VAT rate as a percentage.
```

--------------------------------

### Calculate Net Amount from Gross Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Calculates the net amount (excluding VAT) from a gross amount (including VAT) given the VAT rate. Requires importing the calculate_net_amount tool.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools.vat import calculate_net_amount

gross_amount = Dinero(120, USD)  # Amount including 20% VAT
net_amount = calculate_net_amount(gross_amount, 20)
net_amount.format(symbol=True, currency=True)
'$100.00 USD'
```

--------------------------------

### Calculate Gross Price with VAT

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Calculates the gross price including a specified VAT percentage. Ensure net_price is a Dinero object.

```python
from dinero import Dinero

net_price = Dinero("100.00", "USD")
def calculate_gross_amount(net_amount, vat_percentage):
    vat_amount = net_amount * (vat_percentage / 100)
    return net_amount + vat_amount

gross_price = calculate_gross_amount(net_price, 20)
print(f"Net price: {net_price.format(symbol=True)}")
print(f"Gross price (inc. VAT): {gross_price.format(symbol=True)}")
```

--------------------------------

### Dinero Currency-Safe Calculations

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Demonstrates performing arithmetic operations between Dinero objects and handling potential errors when adding different currencies. A `DifferentCurrencyError` is raised if currencies do not match.

```python
# Basic arithmetic
total = price - discount  # Dinero("89.99", USD)

# Safe currency handling
euro_price = Dinero("89.99", EUR)
try:
    total = price + euro_price  # Raises DifferentCurrencyError
except DifferentCurrencyError:
    print("Cannot add different currencies!")
```

--------------------------------

### Run Pytest for Unit Tests

Source: https://github.com/wilfredinni/dinero/blob/master/CONTRIBUTING.md

Execute unit tests using Pytest to ensure code quality and verify that no tests are failing. This should be done after implementing changes.

```bash
$ pytest
```

--------------------------------

### Python Floating-Point Arithmetic Issue

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Demonstrates the inaccuracy of standard floating-point arithmetic for financial calculations in Python. Use Dinero for precise monetary computations.

```python
>>> 2.32 * 3 == 6.96
False
>>> 2.32 * 3
6.959999999999999  # Not ideal for financial calculations!
```

--------------------------------

### Format EUR Amount with Symbol

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Access pre-defined ISO 4217 currencies. Each currency object contains its symbol and decimal place information.

```python
from dinero.currencies import USD, EUR, GBP, JPY, BTC

# Each currency knows its symbol and decimal places
amount = Dinero("42.42", EUR)
print(amount.format(symbol=True))  # "€42.42"
```

--------------------------------

### Convert Currency Between Dinero Objects

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Converts a Dinero object from one currency to another using a specified exchange rate. Requires importing necessary currencies.

```python
from dinero.currencies import USD, EUR, CLP

# Convert USD to EUR with an exchange rate of 0.85
usd_amount = Dinero("100", USD)
eur_amount = usd_amount.convert("0.85", EUR)
eur_amount.format(symbol=True)
'€85.00'
```

--------------------------------

### Perform Division with Dinero

Source: https://context7.com/wilfredinni/dinero/llms.txt

Divide monetary values by a factor using the divide() method or the / operator.

```python
from dinero import Dinero
from dinero.currencies import USD

total = Dinero("100.00", USD)

# Using method
per_person = total.divide(4)
print(per_person.format(symbol=True))  # '$25.00'

# Using operator
per_person = Dinero("2.32", USD) / 3
print(per_person.format(symbol=True))  # '$0.77'

# Split evenly
monthly = Dinero("1200.00", USD) / 12
print(monthly.format(symbol=True))  # '$100.00'
```

--------------------------------

### Handle Currency Mismatches

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Demonstrates that operations between different currencies raise a DifferentCurrencyError.

```python
# different currencies will raise a DifferentCurrencyError
from dinero import Dinero
from dinero.currencies import EUR, USD
from dinero.exceptions import DifferentCurrencyError

amount_1 = Dinero("333.3", EUR)
amount_2 = Dinero(333.3, USD)

try:
    amount_1.add(amount_2)
    print(amount_1 + amount_2)
    sum([amount_1, amount_2])
except DifferentCurrencyError:
    print('Can not operate with different currencies')
```

```python
# different currencies will raise a DifferentCurrencyError
from dinero import Dinero
from dinero.currencies import EUR, USD
from dinero.exceptions import DifferentCurrencyError

amount_1 = Dinero("333.3", EUR)
amount_2 = Dinero(333.3, USD)

try:
    amount_1.subtract(amount_2)
    print(amount_1 - amount_2)
except DifferentCurrencyError:
    print('Can not operate with different currencies')
```

--------------------------------

### Dinero Financial Tools: Compound Interest Calculation

Source: https://github.com/wilfredinni/dinero/blob/master/README.md

Shows how to calculate future investment value using compound interest with the `calculate_compound_interest` function. Specify principal, interest rate, duration, and compounding frequency.

```python
from dinero.tools import calculate_compound_interest

# Calculate compound interest
investment = Dinero("10000", USD)
future_value = calculate_compound_interest(
    principal=investment,
    interest_rate=5,  # 5% annual rate
    duration=10,      # 10 years
    compound_frequency=12  # Monthly compounding
)
```

--------------------------------

### Calculate VAT Portion from Gross Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Extracts the VAT amount from a gross amount (including VAT) based on the provided VAT rate. Requires importing the calculate_vat_portion tool.

```python
from dinero.tools.vat import calculate_vat_portion

gross_amount = Dinero(120, USD)  # Amount including 20% VAT
vat = calculate_vat_portion(gross_amount, 20)
vat.format(symbol=True, currency=True)
'$20.00 USD'
```

--------------------------------

### Calculate Markup Amount

Source: https://github.com/wilfredinni/dinero/blob/master/examples.ipynb

Calculates the markup amount on a cost price. Requires importing calculate_markup from dinero.tools.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_markup

cost_price = Dinero("1000", USD)
markup_amount = calculate_markup(
    cost=cost_price,
    markup=15,
)
markup_amount.format(symbol=True, currency=True)
```

--------------------------------

### Compare Monetary Values

Source: https://github.com/wilfredinni/dinero/blob/master/docs/index.md

Use comparison operators or explicit methods to evaluate relationships between monetary objects.

```python
from dinero import Dinero
from dinero.currencies import USD

price1 = Dinero("99.99", USD)
price2 = Dinero("89.99", USD)

# Using comparison operators (see more on [Comparisons](started.md#comparisons))
print(price1 > price2)    # True

# Using methods for more explicit code
print(price1.eq(price2))  # False
print(price2.lt(price1))  # True
```

--------------------------------

### Convert Dinero Object to Dictionary (amount_with_format=True)

Source: https://github.com/wilfredinni/dinero/blob/master/docs/started.md

Represents a Dinero object as a dictionary with the amount formatted using locale-specific separators.

```python
>>> Dinero('3333.26', USD).to_dict(amount_with_format=True)
{
    'amount': '3,333.26',
    'currency':
        {
            'code': 'USD',
            'base': 10,
            'exponent': 2,
            'symbol': '$'
        }
}
```

--------------------------------

### Calculate Percentage of an Amount

Source: https://github.com/wilfredinni/dinero/blob/master/docs/tools.md

Calculates a specific percentage of a given monetary amount. Requires importing the calculate_percentage tool.

```python
from dinero import Dinero
from dinero.currencies import USD
from dinero.tools import calculate_percentage

amount = Dinero("3000", USD)
vat_amount = calculate_percentage(
    amount=amount,
    percentage=15,
)
vat_amount.format(symbol=True, currency=True)
'$450.00 USD'
```