Currency Types (tendril.utils.types.currency)¶

The tendril.utils.types.currency contains classes which allow for easy use and manipulation of currency values. The primary focus is on the primary use cases of Currencies within tendril, i.e. :

• Handling foreign exchange conversions and exchange rates in application code without too much fuss.
• Handling currency arithmetic and comparisons.

This module uses a specific Base Currency, defined by tendril.utils.config.BASE_CURRENCY and tendril.utils.config.BASE_CURRENCY_SYMBOL and available as this module’s native_currency_defn module variable. In case this module is to be used independent of Tendril, at least those configuration options must be defined in tendril.utils.config.

Module Contents

class tendril.utils.types.currency.CurrencyDefinition(code, symbol=None, exchval=None)[source]¶

Bases: object

Instances of this class define a currency.

The minimal requirement to define a currency is a code, which would usually be a standard internationally recognized currency code.

In addition to the code, a currency definition also includes an optional symbol, which is used to create string representations of currency values in that currency. In the absence of a symbol, the code is used in it’s place.

Unless otherwise specified during the instantiation of the class, the exchange rate is obtained from internet services by the _get_exchval() method.

Parameters:	code – Standard currency code. symbol – Symbol to use to represent the currency. Optional. exchval – Exchange rate to use, if not automatic. Optional.

code¶

Returns:	The currency code.
Return type:	str

symbol¶

Returns:	The currency symbol, or code if no symbol.
Return type:	str

exchval¶

Returns:	The exchange rate
Return type:	float

exch_rate¶

The exchange rate in a human-friendly string.

static _get_exchval(code)[source]¶

Obtains the exchange rate of the currency definition’s code using the http://fixer.io JSON API. The native currency is used as the reference.

Parameters:	code (str) – The currency code for which the exchange rate is needed.
Returns:	The exchange rate of currency specified by code vs the native currency.
Return type:	float

__eq__(other)[source]¶

Two instances of CurrencyDefinition will evaluate to be equal only when all three parameters of the instances are equal.

tendril.utils.types.currency.native_currency_defn = <CurrencyDefinition INR ₹ 1>¶

The native currency definition used by the module

This definition uses the code contained in tendril.utils.config.BASE_CURRENCY and symbol tendril.utils.config.BASE_CURRENCY_SYMBOL. Application code should import this definition instead of creating new currency definitions whenever one is needed to represent a native currency value.

class tendril.utils.types.currency.CurrencyValue(val, currency_def)[source]¶

Bases: tendril.utils.types.unitbase.TypedComparisonMixin

Instances of this class define a specific currency value, or a certain sum of money.

The currency_def can either be a CurrencyDefinition instance (recommended), or a string containing the code for the currency.

Parameters:	val – The numerical value. currency_def (CurrencyDefinition or str) – The currency definition within which the value is defined.

Note

Since the exchange rate is obtained at the instantiation of the CurrencyDefinition, using a string instead of a predefined CurrencyDefinition instance may result in instances of the same currency, but with different exchange rates.

Variables:	_currency_def – The currency definition of the source value of the instance. _val – The numerical value in the source currency of the instance.

Arithmetic Operations

__add__(other)	Addition of two CurrencyValue instances returns a CurrencyValue instance with the sum of the two operands, with currency conversion applied if necessary.
__sub__(other)	Subtraction of two CurrencyValue instances returns a CurrencyValue instance with the difference of the two operands, with currency conversion applied if necessary.
__mul__(other)	Multiplication of one CurrencyValue instance with a numerical type results in a CurrencyValue instance, whose value is is the currency type operand’s value multiplied by the numerical operand’s value.
__div__(other)	Division of one CurrencyValue instance with a numerical type results in a CurrencyValue instance, whose value is is the currency type operand’s value divided by the numerical operand’s value.
_cmpkey()	The comparison of two CurrencyValue instances behaves identically to the comparison of the operands’ native_value.

native_value¶

The numerical value of the currency value in the native currency, i.e., that defined by native_currency_defn.

Return type:	float

native_string¶

The string representation of the currency value in the native currency, i.e., that defined by native_currency_defn.

Return type:	str

source_value¶

The numerical value of the currency value in the source currency, i.e., that defined by source_currency.

Return type:	float

source_string¶

The string representation of the currency value in the source currency, i.e., that defined by source_currency.

Return type:	str

source_currency¶

The currency definition of the source currency, i.e, the instance variable _currency_def.

Return type:	CurrencyDefinition

exch_rate¶

The applicable exchange rate in a human-friendly string.

is_foreign¶

Whether the source currency is Foreign (True) or is the native currency (False).

__add__(other)[source]¶

Addition of two CurrencyValue instances returns a CurrencyValue instance with the sum of the two operands, with currency conversion applied if necessary.

If the source_currency of the two operands are equal, the result uses the the same source_currency. If not, the result is uses the native_currency_defn as it’s source_currency.

If the other operand is a numerical type and evaluates to 0, this object is simply returned unchanged.

Addition with all other Types / Classes is not supported.

Return type:	CurrencyValue

__mul__(other)[source]¶

Multiplication of one CurrencyValue instance with a numerical type results in a CurrencyValue instance, whose value is is the currency type operand’s value multiplied by the numerical operand’s value.

The source_currency of the returned CurrencyValue is the same as that of the currency type operand.

Multiplication with all other Types / Classes is not supported.

Return type:	CurrencyValue

__div__(other)[source]¶

Division of one CurrencyValue instance with a numerical type results in a CurrencyValue instance, whose value is is the currency type operand’s value divided by the numerical operand’s value.

The source_currency of the returned CurrencyValue is the same as that of the currency type operand. In this case, the first operand must be a CurrencyValue, and not the reverse.

Division of one CurrencyValue instance by another returns a numerical value, which is obtained by performing the division with the operands’ native_value.

Division with all other Types / Classes is not supported.

Return type:	CurrencyValue

__sub__(other)[source]¶

Subtraction of two CurrencyValue instances returns a CurrencyValue instance with the difference of the two operands, with currency conversion applied if necessary.

If source_currency of the two operands are equal, the result uses the the same source_currency. If not, the result is in the native_currency_defn.

If the other operand is a numerical type and evaluates to 0, this object is simply returned unchanged.

Subtraction with all other Types / Classes is not supported.

Return type:	CurrencyValue

_cmpkey()[source]¶

The comparison of two CurrencyValue instances behaves identically to the comparison of the operands’ native_value.

Comparison with all other Types / Classes is not supported.