63 lines
2.9 KiB
ReStructuredText
63 lines
2.9 KiB
ReStructuredText
===================================
|
|
:mod:`currency` - Manage currencies
|
|
===================================
|
|
|
|
This module facilitates currencies management. It exposes :class:`Currency` which lets you easily figure out their exchange value.
|
|
|
|
The ``Currency`` class
|
|
======================
|
|
|
|
.. class:: Currency(code=None, name=None)
|
|
|
|
A ``Currency`` instance is created with either a 3-letter ISO code or with a full name. If it's present in the database, an instance will be returned. If not, ``ValueError`` is raised. The easiest way to access a currency instance, however, if by using module-level constants. For example::
|
|
|
|
>>> from hscommon.currency import USD, EUR
|
|
>>> from datetime import date
|
|
>>> USD.value_in(EUR, date.today())
|
|
0.6339119851386843
|
|
|
|
Unless a :class:`currency.RatesDB` global instance is set through :meth:`Currency.set_rate_db` however, only fallback values will be used as exchange rates.
|
|
|
|
.. staticmethod:: Currency.register(code, name, exponent=2, fallback_rate=1)
|
|
|
|
Register a new currency in the currency list.
|
|
|
|
.. staticmethod:: Currency.set_rates_db(db)
|
|
|
|
Sets a new currency ``RatesDB`` instance to be used with all ``Currency`` instances.
|
|
|
|
.. staticmethod:: Currency.set_rates_db()
|
|
|
|
Returns the current ``RatesDB`` instance.
|
|
|
|
.. method:: Currency.rates_date_range()
|
|
|
|
Returns the range of date for which rates are available for this currency.
|
|
|
|
.. method:: Currency.value_in(currency, date)
|
|
|
|
Returns the value of this currency in terms of the other currency on the given date.
|
|
|
|
.. method:: Currency.set_CAD_value(value, date)
|
|
|
|
Sets currency's value in CAD on the given date.
|
|
|
|
The ``RatesDB`` class
|
|
=====================
|
|
|
|
.. class:: RatesDB(db_or_path=':memory:')
|
|
|
|
A sqlite database that stores currency/date/value pairs, "value" being the value of the currency in CAD at the given date. Currencies are referenced by their 3-letter ISO code in the database and it its arguments (so ``currency_code`` arguments must be 3-letter strings).
|
|
|
|
.. method:: RatesDB.date_range(currency_code)
|
|
|
|
Returns a tuple ``(start_date, end_date)`` representing dates covered in the database for currency ``currency_code``. If there are gaps, they are not accounted for (subclasses that automatically update themselves are not supposed to introduce gaps in the db).
|
|
|
|
.. method:: RatesDB.get_rate(date, currency1_code, currency2_code)
|
|
|
|
Returns the exchange rate between currency1 and currency2 for date. The rate returned means '1 unit of currency1 is worth X units of currency2'. The rate of the nearest date that is smaller than 'date' is returned. If there is none, a seek for a rate with a higher date will be made.
|
|
|
|
.. method:: RatesDB.set_CAD_value(date, currency_code, value)
|
|
|
|
Sets the CAD value of ``currency_code`` at ``date`` to ``value`` in the database.
|