panosl/django-currencies — 97 Stars

Topics

Language breakdown

No language data available.

▸ Files click to expand

README

django-currencies =================

.. image:: https://travis-ci.org/panosl/django-currencies.svg?branch=master :target: https://travis-ci.org/panosl/django-currencies .. image:: https://codecov.io/gh/panosl/django-currencies/branch/master/graph/badge.svg :target: https://codecov.io/gh/panosl/django-currencies

django-currencies allows you to define different currencies, and includes template tags/filters to allow easy conversion between them.

For more details, see the documentation <https://django-currencies.readthedocs.org/en/latest/>_ at Read The Docs.

Authored by Panos Laganakos <https://panoslaganakos.com/>_, and some great contributors <https://github.com/panosl/django-currencies/contributors>_.

Installation

Either clone this repository into your project, or install with `pip:


   .. code-block:: shell
pip install django-currencies

#. You'll need to add currencies to INSTALLED_APPS in your project's settings file:


.. code-block:: python
import django
INSTALLED_APPS += (            'currencies',        )
if django.VERSION < (1, 7):            INSTALLED_APPS += (                'south',            )

#. Either have the currencies.context_processors.currencies processor:


.. code-block:: python
TEMPLATECONTEXTPROCESSORS += (            'django.core.context_processors.request',  # must be enabled            'currencies.context_processors.currencies',        )

#. Or use the template tag currency_context:


.. code-block:: html+django
{% load currency %}        {% currency_context %}

#. Update your urls.py file :


.. code-block:: python
urlpatterns += patterns('',            url(r'^currencies/', include('currencies.urls')),        )

Then run ./manage.py migrate to create the required database tables


Upgrading from 0.3.3 ~~~~
Upgrading from 0.3.3 is likely to cause problems trying to apply a migration when the tables already exist. In this case a fake migration needs to be applied:
.. code-block:: shell
./manage.py migrate currencies 0001 --fake
Configuration

django-currencies has built-in integration with openexchangerates.org _, Yahoo Finance _ and Currency ISO _.


Management Commands

You can use the management commands currencies and updatecurrencies to maintain the currencies in the database. The former will import any currencies that are defined on the selected source into the database. This includes information like the currency code, name, symbol, and any other info provided. The latter will update all the database currency rates from the source. Any currency missing on the source will be untouched.


You can selectively import currencies, for example the commands below will import USD and EUR currencies only, or use a variable from the settings that points to an iterable respectively:
.. code-block:: shell
./manage.py currencies --import=USD --import=EUR     ./manage.py currencies -i SHOP_CURRENCIES

The command automatically looks for variables CURRENCIES or SHOP_CURRENCIES in settings if -i is not specified. For more information on the additional switches --force and --verbosity try ./manage.py help currencies.

updatecurrencies can automatically change the base rate of the imported exchange rates by specifying the --base switch like so:


.. code-block:: shell
./manage.py updatecurrencies oxr --base=USD     ./manage.py updatecurrencies yahoo -b SHOPDEFAULTCURRENCY

The command automatically looks for variables CURRENCIES_BASE or SHOPDEFAULTCURRENCY in settings if -b is not specified.


OpenExchangeRates

This is the default source or select it specifically using oxr as positional argument to either command.


You will need to specify your API key in your settings file:
.. code-block:: python
OPENEXCHANGERATESAPPID = "c2b2efcb306e075d9c2f2d0b614119ea"

Requirements: requests __ (python3-compatible fork of OpenExchangeRatesClient _ is integrated due to abandoned project)


Yahoo Finance
.. attention::

Yahoo integration is now deprecated due to withdrawal of the service around 6 Feb 2018 due to purchase by Verizon. The cached currency json file will continue to be available through the currencies command however.

Select this source by specifying yahoo as positional argument.

Requirements: BeautifulSoup4 _ and requests __


Currency ISO

Select this source by specifying iso as positional argument.

Requirements: requests __


===========  ==========  =============  ==========  ========== Integration                    Live Feeds -----------  ------------------------------------------------- ..           Currencies      Rates       Symbols    Other Info ===========  ==========  =============  ==========  ==========     oxr          ✅            ✅            ✅ *    yahoo         ✅            ✘            ✅           ✅     iso          ✅                                     ✅ ===========  ==========  =============  ==========  ==========
.. |T| unicode:: U+2705 .. ticked

| \* Symbols are imported from the file currencies.json because it is not | supported by the service. Other info includes ISO4217 number and exponent, | country and city names, and alternative currency names.


Usage

First of all, load the currency in every template where you want to use it:


.. code-block:: html+django
{% load currency %}
Use:
.. code-block:: html+django
{% changecurrency [price] [currencycode] %}
for example:
.. code-block:: html+django
{% change_currency product.price "USD" %}

 {% change_currency product.price CURRENCY.code %}


or use the filter:
.. code-block:: html+django
{{ [price]|currency:[currency_code] }}
for example:
.. code-block:: html+django
{{ product.price|currency:"USD" }}

or set the CURRENCY_CODE context variable with a POST to the included view:


.. code-block:: html+django
{% url 'currenciessetcurrency' [currency_code] %}

or use the template tag currency_context:


.. code-block:: html+django
{% currency_context %}

which gives the three context variables: CURRENCIES, CURRENCY_CODE and CURRENCY.


Template

Included is a template for a Bootstrap 3 & fontawesome compatible navbar currency chooser. The navbar item will display if there are more than 1 active currencies. There is a navbar parameter dropdownextraclass which is used to supply extra classes to the dropdown:


.. code-block:: html+django
{% block navbar-nav %}         ...         <ul class="nav navbar-nav navbar-right">             ...             {% with dropdownextraclass="collapsed-nav" %}             {% include "currencies/navbar/currency-chooser-bs3fa.html" %}             {% endwith %}
.. attention::
The currency choice may not be reflected on the navbar if your view is not re-rendered.     This may be the case if you are viewing a default page in Django CMS for example.     This is due to the context processor not being triggered because the RequestContext     is not re-generated.
License

django-currencies` is released under the BSD license.

🔗 More in this category