Exchange rate plugin (#5667)

* Add plugin mixin class for supporting exchange rates

* Split some mixin classes out into their own files

- mixins.py is becoming quite bloated!

* Add some new settings for controlling currency updates

* Adds basic plugin implementation

* Refactor existing implementation

- Builtin plugin uses frankfurter.app API
- Better error / edge case handlign

* Add sample plugin for currency exchange

* Allow user to select which plugin to use for plugin updates

* Observe user-configured setting for how often exchange rates are updated

* Updates for some of the sample plugins

* Fix plugin slug

* Add doc page

* Document simple example

* Improve sample

* Add blank page for currency settings info

* More info in "config" page

* Update docs again

* Updated unit tests

* Fill out default settings values when InvenTree runs

* Add log messages

* Significant improvement in default settings speed

- Use bulk create
- Be efficient
- Dont' be inefficient

* More strict checks

* Refactor default values implementation

- Don't run at startup
- Run on list API
- Implement generic @classmethod

docs/docs/extend/plugins.md

@@ -95,6 +95,7 @@ Supported mixin classes are:
 | [APICallMixin](./plugins/api.md) | Perform calls to external APIs |
 | [AppMixin](./plugins/app.md) | Integrate additional database tables |
 | [BarcodeMixin](./plugins/barcode.md) | Support custom barcode actions |
+| [CurrencyExchangeMixin](./plugins/currency.md) | Custom interfaces for currency exchange rates |
 | [EventMixin](./plugins/event.md) | Respond to events |
 | [LabelPrintingMixin](./plugins/label.md) | Custom label printing support |
 | [LocateMixin](./plugins/locate.md) | Locate and identify stock items |

docs/docs/extend/plugins/currency.md

@@ -0,0 +1,45 @@
+---
+title: Currency Exchange Mixin
+---
+
+## CurrencyExchangeMixin
+
+The `CurrencyExchangeMixin` class enabled plugins to provide custom backends for updating currency exchange rate information.
+
+Any implementing classes must provide the `update_exchange_rates` method. A simple example is shown below (with fake data).
+
+```python
+
+from plugin import InvenTreePlugin
+from plugin.mixins import CurrencyExchangeMixin
+
+class MyFirstCurrencyExchangePlugin(CurrencyExchangeMixin, InvenTreePlugin):
+    """Sample currency exchange plugin"""
+
+    ...
+
+    def update_exchange_rates(self, base_currency: str, symbols: list[str]) -> dict:
+        """Update currency exchange rates.
+
+        This method *must* be implemented by the plugin class.
+
+        Arguments:
+            base_currency: The base currency to use for exchange rates
+            symbols: A list of currency symbols to retrieve exchange rates for
+
+        Returns:
+            A dictionary of exchange rates, or None if the update failed
+
+        Raises:
+            Can raise any exception if the update fails
+        """
+
+        rates = {
+            'base_currency': 1.00
+        }
+
+        for sym in symbols:
+            rates[sym] = random.randrange(5, 15) * 0.1
+
+        return rates
+```

docs/docs/extend/plugins/report.md

@@ -31,7 +31,7 @@ from report.models import PurchaseOrderReport
 class SampleReportPlugin(ReportMixin, InvenTreePlugin):
     """Sample plugin which provides extra context data to a report"""
 
-    NAME = "Report Plugin"
+    NAME = "Sample Report Plugin"
     SLUG = "reportexample"
     TITLE = "Sample Report Plugin"
     DESCRIPTION = "A sample plugin which provides extra context data to a report"

docs/docs/settings/currency.md

@@ -0,0 +1,31 @@
+---
+title: Currency Support
+---
+
+## Currency Support
+
+InvenTree provides support for multiple currencies, allowing pricing information to be stored with base currency rates.
+
+### Configuration
+
+To specify which currencies are supported, refer to the [currency configuration](../start/config.md#supported-currencies) section
+
+### Currency Conversion
+
+Currency conversion is provided via the [django-money](https://github.com/django-money/django-money) library. Pricing data can be converted seamlessly between the available currencies.
+
+### Currency Rate Updates
+
+Currency conversion rates are periodically updated, via an external currency exchange server. Out of the box, InvenTree uses the [frankfurter.app](https://www.frankfurter.app/) service, which is an open source currency API made freely available.
+
+#### Custom Rate Updates
+
+If a different currency exchange backend is needed, or a custom implementation is desired, the currency exchange framework can be extended [via plugins](../extend/plugins/currency.md). Plugins which implement custom currency exchange frameworks can be easily integrated into the InvenTree framework.
+
+### Currency Settings
+
+In the [settings screen](./global.md), under the *Pricing* section, the following currency settings are available:
+
+{% with id="currency-settings", url="settings/currency.png", description="Currency Exchange Settings" %}
+{% include 'img.html' %}
+{% endwith %}

docs/docs/start/config.md

@@ -164,13 +164,20 @@ The following email settings are available:
 The "sender" email address is the address from which InvenTree emails are sent (by default) and must be specified for outgoing emails to function:
 
 !!! info "Fallback"
-     If `INVENTREE_EMAIL_SENDER` is not provided, the system will fall back to `INVENTREE_EMAIL_USERNAME` (if the username is a valid email address)
+    If `INVENTREE_EMAIL_SENDER` is not provided, the system will fall back to `INVENTREE_EMAIL_USERNAME` (if the username is a valid email address)
 
 ## Supported Currencies
 
 The currencies supported by InvenTree must be specified in the [configuration file](#configuration-file).
 
-A list of currency codes (e.g. *AUD*, *CAD*, *JPY*, *USD*) can be specified using the `currencies` variable.
+A list of currency codes (e.g. *AUD*, *CAD*, *JPY*, *USD*) can be specified using the `currencies` variable (or using the `INVENTREE_CURRENCIES` environment variable).
+
+| Environment Variable | Configuration File | Description | Default |
+| --- | --- | --- | --- |
+| INVENTREE_CURRENCIES | currencies | List of supported currencies| `AUD`, `CAD`, `CNY`, `EUR`, `GBP`, `JPY`, `NZD`, `USD` |
+
+!!! tip "More Info"
+    Read the [currencies documentation](../settings/currency.md) for more information on currency support in InvenTree
 
 ## Allowed Hosts / CORS
 

docs/mkdocs.yml

@@ -162,6 +162,7 @@ nav:
     - Error Logs: settings/logs.md
     - Email: settings/email.md
     - Background Tasks: settings/tasks.md
+    - Currency Support: settings/currency.md
   - App:
     - InvenTree App: app/app.md
     - Connect: app/connect.md
@@ -202,6 +203,7 @@ nav:
       - API Mixin: extend/plugins/api.md
       - App Mixin: extend/plugins/app.md
       - Barcode Mixin: extend/plugins/barcode.md
+      - Currency Mixin: extend/plugins/currency.md
       - Event Mixin: extend/plugins/event.md
       - Label Printing Mixin: extend/plugins/label.md
       - Locate Mixin: extend/plugins/locate.md