Coverage for /media/ldata/code/tendril/tendril/utils/types/currency.py : 96%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# Copyright (C) 2015 Chintalagiri Shashank # # This file is part of Tendril. # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU Affero General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Affero General Public License for more details. # # You should have received a copy of the GNU Affero General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>. Currency Types (:mod:`tendril.utils.types.currency`) ====================================================
The :mod:`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 :const:`tendril.utils.config.BASE_CURRENCY` and :const:`tendril.utils.config.BASE_CURRENCY_SYMBOL` and available as this module's :data:`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 :mod:`tendril.utils.config`.
.. rubric:: Module Contents
.. autosummary::
native_currency_defn CurrencyDefinition CurrencyValue
.. seealso:: :mod:`tendril.utils.types`, for an overview applicable to most types defined in Tendril.
.. todo:: The core numbers in this module need to switched to :class:`decimal.Decimal`.
"""
""" Instances of this class define a currency.
The minimal requirement to define a currency is a :attr:`code`, which would usually be a standard internationally recognized currency code.
In addition to the :attr:`code`, a currency definition also includes an optional :attr:`symbol`, which is used to create string representations of currency values in that currency. In the absence of a :attr:`symbol`, the :attr:`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 :meth:`_get_exchval` method.
:param code: Standard currency code. :param symbol: Symbol to use to represent the currency. Optional. :param exchval: Exchange rate to use, if not automatic. Optional.
""" else:
def code(self): """
:return: The currency code. :rtype: str
"""
def symbol(self): """
:return: The currency symbol, or code if no symbol. :rtype: str
""" else:
def exchval(self): """ :return: The exchange rate :rtype: float
"""
def _get_exchval(code): """ Obtains the exchange rate of the currency definition's :attr:`code` using the `<http://fixer.io>`_ JSON API. The native currency is used as the reference.
:param code: The currency code for which the exchange rate is needed. :type code: str :return: The exchange rate of currency specified by code vs the native currency. :rtype: float
"""
'symbols': code}
""" Two instances of :class:`CurrencyDefinition` will evaluate to be equal only when all three parameters of the instances are equal. """ return False return False return False
#: The native currency definition used by the module #: #: This definition uses the code contained in #: :const:`tendril.utils.config.BASE_CURRENCY` and symbol #: :const:`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.
""" Instances of this class define a specific currency value, or a certain sum of money.
The `currency_def` can either be a :class:`CurrencyDefinition` instance (recommended), or a string containing the code for the currency.
:param val: The numerical value. :param currency_def: The currency definition within which the value is defined. :type currency_def: :class:`CurrencyDefinition` or str
.. note:: Since the exchange rate is obtained at the instantiation of the :class:`CurrencyDefinition`, using a string instead of a predefined :class:`CurrencyDefinition` instance may result in instances of the same currency, but with different exchange rates.
:ivar _currency_def: The currency definition of the source value of the instance. :ivar _val: The numerical value in the source currency of the instance.
.. rubric:: Arithmetic Operations
.. autosummary::
__add__ __sub__ __mul__ __div__ _cmpkey
""" else:
def native_value(self): """ The numerical value of the currency value in the native currency, i.e., that defined by :data:`native_currency_defn`.
:rtype: float
"""
def native_string(self): """ The string representation of the currency value in the native currency, i.e., that defined by :data:`native_currency_defn`.
:rtype: str
"""
def source_value(self): """ The numerical value of the currency value in the source currency, i.e., that defined by :attr:`source_currency`.
:rtype: float
"""
def source_string(self): """ The string representation of the currency value in the source currency, i.e., that defined by :attr:`source_currency`.
:rtype: str
"""
def source_currency(self): """ The currency definition of the source currency, i.e, the instance variable :data:`_currency_def`.
:rtype: :class:`CurrencyDefinition`
"""
""" Addition of two :class:`CurrencyValue` instances returns a :class:`CurrencyValue` instance with the sum of the two operands, with currency conversion applied if necessary.
If the :attr:`source_currency` of the two operands are equal, the result uses the the same :attr:`source_currency`. If not, the result is uses the :data:`native_currency_defn` as it's :attr:`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.
:rtype: :class:`CurrencyValue` """ self.source_value + other.source_value, self.source_currency ) else: self.native_value + other.native_value, native_currency_defn )
else:
""" Multiplication of one :class:`CurrencyValue` instance with a numerical type results in a :class:`CurrencyValue` instance, whose value is is the currency type operand's value multiplied by the numerical operand's value.
The :attr:`source_currency` of the returned :class:`CurrencyValue` is the same as that of the currency type operand.
Multiplication with all other Types / Classes is not supported.
:rtype: :class:`CurrencyValue` """ self.source_value * other, self.source_currency ) else:
""" Division of one :class:`CurrencyValue` instance with a numerical type results in a :class:`CurrencyValue` instance, whose value is is the currency type operand's value divided by the numerical operand's value.
The :attr:`source_currency` of the returned :class:`CurrencyValue` is the same as that of the currency type operand. In this case, the first operand must be a :class:`CurrencyValue`, and not the reverse.
Division of one :class:`CurrencyValue` instance by another returns a numerical value, which is obtained by performing the division with the operands' :attr:`native_value`.
Division with all other Types / Classes is not supported.
:rtype: :class:`CurrencyValue` """ self.source_value / other, self.source_currency ) else:
return self.__div__(other)
""" Subtraction of two :class:`CurrencyValue` instances returns a :class:`CurrencyValue` instance with the difference of the two operands, with currency conversion applied if necessary.
If :attr:`source_currency` of the two operands are equal, the result uses the the same :attr:`source_currency`. If not, the result is in the :data:`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.
:rtype: :class:`CurrencyValue` """ else:
""" The comparison of two :class:`CurrencyValue` instances behaves identically to the comparison of the operands' :attr:`native_value`.
Comparison with all other Types / Classes is not supported. """ |