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:
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
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
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:
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:
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:
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
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:
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:
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:
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:
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_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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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: