Skip to content

API: Dinero Methods#

Bases: Operations

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.

Parameters:

Name Type Description Default
amount (str, int, float, Decimal)

The amount to work with.

required
currency dict

Expressed as an ISO 4217 currency code.

required

format(symbol=False, currency=False) #

Format a Dinero object with his decimals, symbol and/or code.

Examples:

>>> Dinero('234342.3010', USD).format()
234,342.30
>>> Dinero('234342.3010', USD).format(symbol=True)
$234,342.30
>>> Dinero('234342.3010', USD).format(currency=True)
234,342.30 USD
>>> Dinero('234342.3010', USD).format(symbol=True, currency=True)
$234,342.30 USD

Parameters:

Name Type Description Default
symbol bool

Add the country currency symbol. Defaults to False.

False
currency bool

Add the country currency code. Defaults to False.

False

Returns:

Name Type Description
STR str

Formatted string representation of a Dinero object.

add(amount) #

Returns a new Dinero object that represents the sum of this and an other object.

If the addend is not a Dinero object, it will be transformed to one using the same currency.

Examples:

>>> amount_1 = Dinero("2.32", USD)
>>> amount_2 = Dinero("2.32", USD)
>>> amount_1.add(amount_2)
4.64
>>> amount = Dinero("2.32", USD)
>>> amount.add("2.32")
4.64
>>> Dinero("2.32", USD) + Dinero("2.32", USD)
4.64
>>> Dinero("2.32", USD) + "2.32"
4.64

Parameters:

Name Type Description Default
amount (str, int, float, Decimal, Dinero)

The addend.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
DINERO Dinero

Dinero object.

subtract(amount) #

Returns a new Dinero object that represents the difference of this and other.

If the subtrahend is not a Dinero object, it will be transformed to one using the same currency.

Examples:

>>> amount_1 = Dinero("2.32", USD)
>>> amount_2 = Dinero("2", USD)
>>> amount_1.subtract(amount_2)
0.32
>>> amount = Dinero("2.32", USD)
>>> amount.subtract(2)
0.32
>>> Dinero("2.32", USD) - Dinero("2", USD)
0.32
>>> Dinero("2.32", USD) - "2"
0.32

Parameters:

Name Type Description Default
amount (str, int, float, Decimal, Dinero)

The subtrahend.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
DINERO Dinero

Dinero object.

multiply(amount) #

Returns a new Dinero object that represents the multiplied value by the given factor.

Examples:

>>> amount = Dinero("2.32", USD)
>>> amount.multiply(3)
6.96
>>> Dinero("2.32", USD) * 3
6.96

Parameters:

Name Type Description Default
amount (int, float, Decimal)

The multiplicand.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
DINERO Dinero

Dinero object.

divide(amount) #

Returns a new Dinero object that represents the divided value by the given factor.

Examples:

>>> amount = Dinero("2.32", USD)
>>> amount.divide(3)
0.77
>>> Dinero("2.32", USD) / 3
0.77

Parameters:

Name Type Description Default
amount (int, float, Decimal)

The divisor.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
DINERO Dinero

Dinero object.

convert(exchange_rate, currency) #

Converts the Dinero object to a different currency using the specified exchange rate.

Parameters:

Name Type Description Default
exchange_rate str | float

The exchange rate to use for conversion.

required
currency Currency

The target currency to convert to.

required

Returns:

Name Type Description
Dinero Dinero

A new Dinero object in the target currency.

Raises:

Type Description
TypeError

If currency is not a Currency object.

ValueError

If exchange_rate is negative, zero, or cannot be converted to a number.

Examples:

>>> from dinero.currencies import USD, EUR
>>> usd_amount = Dinero("100", USD)
>>> eur_amount = usd_amount.convert("0.85", EUR)
>>> eur_amount.format()
'85.00'
>>> from dinero.currencies import CLP
>>> clp_amount = usd_amount.convert(750, CLP)
>>> clp_amount.format()
'75,000'

eq(amount) #

Checks whether the value represented by this object equals to other instance.

Examples:

>>> amount_1 = Dinero("2.32", USD)
>>> amount_2 = Dinero("2.32", USD)
>>> amount_1.eq(amount_2)
True
>>> Dinero("2.32", USD) == Dinero("2.32", USD)
True

Parameters:

Name Type Description Default
amount Dinero

The object to compare to.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
BOOL bool

Whether the value represented is equals to the other.

gt(amount) #

Checks whether the value represented by this object is greater or equal other.

Examples:

>>> amount_1 = Dinero(25, USD)
>>> amount_2 = Dinero(24, USD)
>>> amount_1.gt(amount_2)
True
>>> Dinero(25, USD) > Dinero(24, USD)
True

Parameters:

Name Type Description Default
amount Dinero

The object to compare to.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
BOOL bool

Whether the value represented is greater than to the other.

gte(amount) #

Checks whether the value represented by this object is greater than or equal other

Examples:

>>> amount_1 = Dinero(25, USD)
>>> amount_2 = Dinero(24, USD)
>>> amount_1.gte(amount_2)
True
>>> Dinero(25, USD) >= Dinero(24, USD)
True

Parameters:

Name Type Description Default
amount Dinero

The object to compare to.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
BOOL bool

Whether the value represented is greater than or equal to the other.

lt(amount) #

Checks whether the value represented by this object is less than the other.

Examples:

>>> amount_1 = Dinero(24, USD)
>>> amount_2 = Dinero(25, USD)
>>> amount_1.lt(amount_2)
True
>>> Dinero(24, USD) < Dinero(25, USD)
True

Parameters:

Name Type Description Default
amount Dinero

The object to compare to.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
BOOL bool

Whether the value represented is less than to the other.

lte(amount) #

Checks whether the value represented by this object is less than or equal other.

Examples:

>>> amount_1 = Dinero(24, USD)
>>> amount_2 = Dinero(25, USD)
>>> amount_1.lte(amount_2)
True
>>> Dinero(24, USD) <= Dinero(25, USD)
True

Parameters:

Name Type Description Default
amount Dinero

The object to compare to.

required

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
BOOL bool

Whether the value represented is less than or equal to the other.

to_dict(amount_with_format=False) #

Returns the object's data as a Python Dictionary.

Examples:

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

Parameters:

Name Type Description Default
amount_with_format bool

If the amount is formatted. Defaults to False.

False

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
DICT dict[str, Any]

The object's data as a Python Dictionary.

to_json(amount_with_format=False) #

Returns the object's data as a JSON string.

Examples:

>>> Dinero('2,00', USD).to_json()
'{"amount": "3333.20", "currency": {"code": "USD", "base": 10...'
>>> Dinero('2,00', USD).to_json(amount_with_format=True)
'{"amount": "3,333.26", "currency": {"code": "USD", "base": 10...'

Parameters:

Name Type Description Default
amount_with_format bool

If the amount is formatted. Defaults to False.

False

Raises:

Type Description
DifferentCurrencyError

Different currencies where used.

InvalidOperationError

An operation between unsupported types was executed.

Returns:

Name Type Description
STR str

The object's data as JSON.

Value Added Tax (VAT) Module

VAT is a consumption tax applied to goods and services at each stage of production and distribution. It is an indirect tax, meaning it is collected by businesses on behalf of the tax authority and ultimately paid by the end consumer.

Key Concepts
  • VAT is calculated as a percentage of the price of goods or services
  • It is included in the final price paid by consumers (gross amount)
  • Businesses can usually reclaim VAT on their purchases (input VAT)
  • The net amount is the price before VAT is added
  • The gross amount is the total price including VAT
Common Usage
  • Retail pricing: Adding VAT to product prices
  • Business accounting: Calculating VAT for tax returns
  • Financial reporting: Separating net amounts from VAT portions
Example

For a product with a net price of $100 and a VAT rate of 20%: - Net amount: $100.00 (price before VAT) - VAT portion: $20.00 (20% of net amount) - Gross amount: $120.00 (total price including VAT)

This module provides tools for all these VAT-related calculations while maintaining precise decimal arithmetic using the Dinero type system.

calculate_net_amount(amount, vat_rate) #

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

Parameters:

Name Type Description Default
amount Dinero

The gross amount (including VAT).

required
vat_rate int | float

The VAT rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The net amount (excluding VAT).

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the vat_rate argument is not a number

ValueError

If the vat_rate argument is negative

Examples:

>>> 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_vat_portion(amount, vat_rate) #

Calculates the VAT portion from a gross amount (including VAT).

Parameters:

Name Type Description Default
amount Dinero

The gross amount (including VAT).

required
vat_rate int | float

The VAT rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The VAT portion.

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the vat_rate argument is not a number

ValueError

If the vat_rate argument is negative

Examples:

>>> 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_gross_amount(amount, vat_rate) #

Calculates the gross amount (including VAT) from a net amount.

Parameters:

Name Type Description Default
amount Dinero

The net amount (excluding VAT).

required
vat_rate int | float

The VAT rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The gross amount (including VAT).

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the vat_rate argument is not a number

ValueError

If the vat_rate argument is negative

Examples:

>>> 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_percentage(amount, percentage) #

Calculates the percentage of a given Dinero object.

Parameters:

Name Type Description Default
amount Dinero

The amount to calculate the percentage of.

required
percentage int | float

The percentage to calculate.

required

Returns:

Name Type Description
Dinero Dinero

The calculated percentage of the amount.

Raises:

Type Description
InvalidOperationError

If the amount is not an instance of Dinero.

TypeError

If the percentage argument is not a number.

ValueError

If the percentage argument is negative.

Examples:

>>> amount = Dinero("3000", USD)
>>> percentage_amount = calculate_percentage(amount, 15)
>>> percentage_amount.format(symbol=True, currency=True)
'$450.00 USD'

Currency Conversion Module

This module provides functionality to convert Dinero objects between different currencies using specified exchange rates. It maintains the precision and immutability principles of the Dinero library.

Key Features
  • Convert Dinero objects to different currencies
  • Maintain proper decimal precision based on target currency
  • Support for all ISO 4217 currency formats
  • Precise calculations using Decimal type
Example

Converting USD to EUR with an exchange rate of 0.85:

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

# Create a USD amount
usd_amount = Dinero("100", USD)

# Convert to EUR
eur_amount = usd_amount.convert("0.85", EUR)
# Returns: Dinero("85.00", EUR)

convert(dinero_obj, exchange_rate, currency) #

Converts a Dinero object to a different currency using the specified exchange rate.

Parameters:

Name Type Description Default
dinero_obj Dinero

The Dinero object to convert.

required
exchange_rate str | float

The exchange rate to use for conversion.

required
currency Currency

The target currency to convert to.

required

Returns:

Name Type Description
Dinero Dinero

A new Dinero object in the target currency.

Raises:

Type Description
TypeError

If dinero_obj is not a Dinero object or currency is not a Currency obj.

ValueError

If exchange_rate is negative, zero, or cannot be converted to an int.

Examples:

>>> from dinero import Dinero
>>> from dinero.currencies import USD, EUR
>>> usd_amount = Dinero("100", USD)
>>> eur_amount = convert(usd_amount, "0.85", EUR)
>>> eur_amount.format()
'85.00'
>>> from dinero.currencies import CLP
>>> clp_amount = convert(usd_amount, 750, CLP)
>>> clp_amount.format()
'75,000'

Interest calculation tools for working with monetary values.

This module provides tools for calculating both simple and compound interest on monetary amounts. It handles all calculations using the Dinero class to ensure precision in financial computations.

Simple interest is calculated using the formula

I = P * r * t where: - I is the interest earned - P is the principal amount - r is the annual interest rate (as a percentage) - t is the time in years

Compound interest is calculated using the formula

A = P * (1 + r/n)^(n*t) Interest = A - P where: - A is the final amount - P is the principal amount - r is the annual interest rate (as a decimal) - n is the number of times interest is compounded per year - t is the time in years

All monetary values are handled as Dinero instances to maintain precision and proper decimal handling as per currency specifications.

calculate_simple_interest(principal, interest_rate, duration) #

Calculates the simple interest on a loan given the principal, interest rate, and duration. Calculate the total interest using the formula: I = P * r * t

Parameters:

Name Type Description Default
principal Dinero

The principal amount of the loan.

required
interest_rate float

The annual interest rate.

required
duration int

The duration of the loan in years.

required

Raises:

Type Description
InvalidOperationError

If the principal amount is not a Dinero object.

TypeError

If the interest rate is not a number or the duration is not an integer.

ValueError

If the interest rate or duration is negative.

Returns:

Name Type Description
Dinero Dinero

The total interest on the loan.

Examples:

>>> principal = Dinero(1000, USD)
>>> interest_rate = 5
>>> duration = 2
>>> calculate_simple_interest(principal, interest_rate, duration)
Dinero(100)

calculate_compound_interest(principal, interest_rate, duration, compound_frequency) #

Calculates the compound interest on a loan given the principal, interest rate, duration, and compound frequency. Uses the formula A = P * (1 + r/n)^(n*t)

Parameters:

Name Type Description Default
principal Dinero

The principal amount of the loan.

required
interest_rate float

The annual interest rate as a decimal.

required
duration int

The duration of the loan in years.

required
compound_frequency int

The number of times interest is compounded per year.

required

Returns:

Name Type Description
Dinero Dinero

The total interest on the loan.

Raises:

Type Description
InvalidOperationError

If the principal is not a Dinero object.

ValueError

If the interest, duration, or frequency are not positive integers.

Examples:

>>> principal = Dinero(1000, USD)
>>> interest_rate = 5.0
>>> duration = 10
>>> compound_frequency = 12
>>> calculate_compound_interest(principal, interest_rate, duration, compound_frequency)  # noqa
Dinero(648.34)

Markup is a common pricing strategy where a percentage is added to the base cost of a product to determine its selling price. The markup percentage represents the amount added on top of the base cost to cover overhead expenses and generate profit.

Example calculation

Base cost: $100 Markup rate: 15% Markup amount: $15 (15% of base) Final price: $115 (base + markup)

Markup vs Margin: - Markup percentage is calculated from the cost price - Margin percentage is calculated from the selling price - Example: A 50% markup equals a 33.33% margin

Common uses: - Retail pricing - Construction estimates - Manufacturing costs - Wholesale pricing - Service pricing

calculate_base_amount(amount, markup_rate) #

Calculates the base amount (excluding markup) from a final amount (including markup).

Parameters:

Name Type Description Default
amount Dinero

The final amount (including markup).

required
markup_rate int | float

The markup rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The base amount (excluding markup).

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the markup_rate argument is not a number

ValueError

If the markup_rate argument is negative

Examples:

>>> final_amount = Dinero(115, USD)  # Amount including 15% markup
>>> base_amount = calculate_base_amount(final_amount, 15)
>>> base_amount.format(symbol=True, currency=True)
'$100.00 USD'

calculate_markup_portion(amount, markup_rate) #

Calculates the markup portion from a final amount (including markup).

Parameters:

Name Type Description Default
amount Dinero

The final amount (including markup).

required
markup_rate int | float

The markup rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The markup portion.

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the markup_rate argument is not a number

ValueError

If the markup_rate argument is negative

Examples:

>>> final_amount = Dinero(115, USD)  # Amount including 15% markup
>>> markup = calculate_markup_portion(final_amount, 15)
>>> markup.format(symbol=True, currency=True)
'$15.00 USD'

calculate_marked_up_amount(amount, markup_rate) #

Calculates the final amount (including markup) from a base amount.

Parameters:

Name Type Description Default
amount Dinero

The base amount (excluding markup).

required
markup_rate int | float

The markup rate as a percentage.

required

Returns:

Name Type Description
Dinero Dinero

The final amount (including markup).

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the markup_rate argument is not a number

ValueError

If the markup_rate argument is negative

Examples:

>>> 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'

Margin is a pricing strategy where the selling price is determined by the desired profit margin as a percentage of the selling price (unlike markup which is based on cost).

Example calculation

Selling price: $100 Margin rate: 20% Margin amount: $20 (20% of selling price) Cost price: $80 (selling price - margin)

Margin vs Markup: - Margin percentage is calculated from the selling price - Markup percentage is calculated from the cost price - Example: A 33.33% margin equals a 50% markup

Common uses: - Retail pricing strategies - Profit analysis - Sales performance metrics - Business valuation - Financial planning

calculate_cost_amount(amount, margin_rate) #

Calculates the cost amount from a selling price and margin rate.

Parameters:

Name Type Description Default
amount Dinero

The selling price (including margin).

required
margin_rate int | float

The margin rate as a percentage of selling price.

required

Returns:

Name Type Description
Dinero Dinero

The cost amount.

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the margin_rate argument is not a number

ValueError

If the margin_rate argument is negative or >= 100

Examples:

>>> selling_price = Dinero(100, USD)  # Amount including 20% margin
>>> cost_amount = calculate_cost_amount(selling_price, 20)
>>> cost_amount.format(symbol=True, currency=True)
'$80.00 USD'

calculate_margin_portion(amount, margin_rate) #

Calculates the margin portion from a selling price.

Parameters:

Name Type Description Default
amount Dinero

The selling price (including margin).

required
margin_rate int | float

The margin rate as a percentage of selling price.

required

Returns:

Name Type Description
Dinero Dinero

The margin portion.

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the margin_rate argument is not a number

ValueError

If the margin_rate argument is negative or >= 100

Examples:

>>> selling_price = Dinero(100, USD)  # Amount including 20% margin
>>> margin = calculate_margin_portion(selling_price, 20)
>>> margin.format(symbol=True, currency=True)
'$20.00 USD'

calculate_selling_price(amount, margin_rate) #

Calculates the selling price from a cost amount and desired margin rate.

Parameters:

Name Type Description Default
amount Dinero

The cost amount (excluding margin).

required
margin_rate int | float

The desired margin rate as a percentage selling price.

required

Returns:

Name Type Description
Dinero Dinero

The selling price (including margin).

Raises:

Type Description
InvalidOperationError

If the amount is not a Dinero object

TypeError

If the margin_rate argument is not a number

ValueError

If the margin_rate argument is negative or >= 100

Examples:

>>> 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'