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 an other object.

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.

`equals_to(amount)` #

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

Examples:

>>> amount_1 = Dinero("2.32", USD)
>>> amount_2 = Dinero("2.32", USD)
>>> amount_1.equals_to(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.

`greater_than(amount)` #

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

Examples:

>>> amount_1 = Dinero(25, USD)
>>> amount_2 = Dinero(24, USD)
>>> amount_1.greater_than(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.

`greater_than_or_equal(amount)` #

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

Examples:

>>> amount_1 = Dinero(25, USD)
>>> amount_2 = Dinero(24, USD)
>>> amount_1.greater_than_or_equal(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.

`less_than(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.less_than(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.

`less_than_or_equal(amount)` #

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

Examples:

>>> amount_1 = Dinero(24, USD)
>>> amount_2 = Dinero(25, USD)
>>> amount_1.less_than_or_equal(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 or not. 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 or not. 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.

`calculate_vat(amount, vat_rate)` #

Calculates the VAT amount of a given Dinero object.

Parameters:

Name	Type	Description	Default
`amount`	`Dinero`	The amount to calculate the VAT for.	required
`vat_rate`	`int \| float`	The VAT rate as a percentage.	required

Returns:

Name	Type	Description
`Dinero`	`Dinero`	The VAT amount.

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:

>>> amount = Dinero(100, USD)
>>> vat_amount = calculate_vat(amount, 7.25)
>>> vat_amount.format(symbol=True, currency=True)
'$6.76 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'

`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)

`calculate_markup(cost, markup)` #

Calculates the markup of a given Dinero object.

Parameters:

Name	Type	Description	Default
`cost`	`Dinero`	The cost to calculate the markup of.	required
`markup`	`int \| float`	The markup to calculate.	required

Returns:

Name	Type	Description
`Dinero`	`Dinero`	The calculated markup of the cost.

Raises:

Type	Description
`InvalidOperationError`	If the cost is not an instance of Dinero.
`TypeError`	If the markup argument is not a number.
`ValueError`	If the markup argument is negative.

Examples:

>>> cost = Dinero("3000", USD)
>>> markup_amount = calculate_markup(cost, 15)
>>> markup_amount.format(symbol=True, currency=True)
'$3,450.00 USD'

API: Dinero Methods#

format(symbol=False, currency=False) #

add(amount) #

subtract(amount) #

multiply(amount) #

divide(amount) #

equals_to(amount) #

greater_than(amount) #

greater_than_or_equal(amount) #

less_than(amount) #

less_than_or_equal(amount) #

to_dict(amount_with_format=False) #

to_json(amount_with_format=False) #

calculate_vat(amount, vat_rate) #

calculate_percentage(amount, percentage) #

calculate_simple_interest(principal, interest_rate, duration) #

calculate_compound_interest(principal, interest_rate, duration, compound_frequency) #

calculate_markup(cost, markup) #

`format(symbol=False, currency=False)` #

`add(amount)` #

`subtract(amount)` #

`multiply(amount)` #

`divide(amount)` #

`equals_to(amount)` #

`greater_than(amount)` #

`greater_than_or_equal(amount)` #

`less_than(amount)` #

`less_than_or_equal(amount)` #

`to_dict(amount_with_format=False)` #

`to_json(amount_with_format=False)` #

`calculate_vat(amount, vat_rate)` #

`calculate_percentage(amount, percentage)` #

`calculate_simple_interest(principal, interest_rate, duration)` #

`calculate_compound_interest(principal, interest_rate, duration, compound_frequency)` #

`calculate_markup(cost, markup)` #