From a707538e5b128e84c98ec438c04b3378a297c5a3 Mon Sep 17 00:00:00 2001
From: Oliver <oliver.henry.walters@gmail.com>
Date: Fri, 3 Feb 2023 12:22:31 +1100
Subject: [PATCH] Python currency support (#437)
* Adds page for python currency support docs
* Currency docs
* Add info on manual currency update
---
docs/api/python/currency.md | 56 +++++++++++++++++++++++++++++++++++++
mkdocs.yml | 1 +
2 files changed, 57 insertions(+)
create mode 100644 docs/api/python/currency.md
diff --git a/docs/api/python/currency.md b/docs/api/python/currency.md
new file mode 100644
index 0000000..388e223
--- /dev/null
+++ b/docs/api/python/currency.md
@@ -0,0 +1,56 @@
+---
+title: Python Currency Support
+---
+
+## Currency Support
+
+InvenTree provides native support for multiple currencies, which can mean that data require conversion between these currencies, at defined exchange rates.
+
+The InvenTree server maintains a set of exchange rates, which are updated periodically. These exchange rates are available via the [InvenTree API](../api.md), and can be used by the Python bindings.
+
+### CurrencyManager Class
+
+The Python bindings provide the `CurrencyManager` class, which takes care of retrieving currency exchange data from the server. This class can be instantiated as shown below:
+
+```python
+from inventree.currency import CurrencyManager
+
+# The manager class must be passed a valid InvenTreeAPI instance
+manager = CurrencyManager(api)
+
+# Access the 'base currency' data
+base_currency = manager.getBaseCurrency()
+
+# Access the 'exchange rate' data
+rates = manager.getExchangeRates()
+```
+
+### Currency Conversion
+
+Currency conversion is performed by passing the value of currency, as well as the *source* and *target* currency codes to the currency manager.
+
+!!! warning "Missing Currency Data"
+ The currency conversion only works if the manager class has valid information on both the *source* and *target* currency exchange rates!
+
+```python
+from inventree.currency import CurrencyManager
+
+manager = CurrencyManager(api)
+
+# Convert from AUD to CAD
+cad = manager.convertCurrency(12.54, 'AUD', 'CAD')
+
+# Convert from NZD to USD
+usd = manager.convertCurrency(99.99, 'NZD', 'USD')
+```
+
+### Exchange Rate Update
+
+To request a manual update of currency data (from the server), run the following command:
+
+```python
+from inventree.currency import CurrencyManager
+
+manager = CurrencyManager(api)
+manager.refreshExchangeRates()
+```
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index c083c17..ddf7459 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -143,6 +143,7 @@ nav:
- Interactive API: api/browse.md
- Python Interface:
- Overview: api/python/python.md
+ - Currency Support: api/python/currency.md
- Examples: api/python/examples.md
- Barcodes:
- Overview: barcodes/barcodes.md