v0.4.0. Converter, docs.

README.md

@@ -31,28 +31,29 @@ But now it _standalone_ project. Created by myself for steam trading purposes mo
 
 ## Installation
 
-pip
-
 ```shell
 pip install aiosteampy
 ```
 
-pipenv
-
 ```shell
 pipenv install aiosteampy
 ```
 
-poetry
-
 ```shell
 poetry add aiosteampy
 ```
 
+Project have extra [currencies converter](https://aiosteampy.somespecial.one/ext/converter/) with
+target dependency `aiosteampy[converter]`. For instance:
+
+```shell
+poetry add aiosteampy[converter]
+```
+
 <!--install-end-->
 
-> [!TIP] > [Aiohttp docs](https://docs.aiohttp.org/en/stable/#library-installation) recommends installing speedups (`aiodns`
-> , `cchardet`, ...)
+> [!TIP]
+> [aiohttp docs](https://docs.aiohttp.org/en/stable/#installing-all-speedups-in-one-command) recommends installing speedups (`aiodns`, `cchardet`, ...)
 
 <!--intro-start-->
 

aiosteampy/converter.py

@@ -125,14 +125,15 @@ def convert(self, amount: int, currency: Currency, target=Currency.USD) -> int:
         :param currency: passed currency of `amount`
         :param target: target of returned value
         :return: converted amount
+        :raises KeyError: if provided currency is not present in `Converter`
         """
 
-        try:
-            source = self[currency][0]
+        source_rate = self[currency][0] if currency is not Currency.USD else 1
+        target_rate = self[target][0] if target is not Currency.USD else 1
 
-        except KeyError:
-            raise ValueError(f"There is no {currency.name} in rates!")
-
-        else:
-            usd_value = round(amount * round(1 / source, 2))
-            return usd_value if target is Currency.USD else round(source * usd_value, 2)
+        # direct conversion
+        # return round(amount * (target_rate / source_rate))
+        
+        # with USD in middle step
+        usd_amount = round(amount * (1 / source_rate))
+        return round(usd_amount * target_rate)

docs/ext/converter.md

@@ -0,0 +1,74 @@
+# Currencies converter
+
+A dict-like class to handle converting steam currencies.
+
+!!! note ""
+    Instance is an API consumer of [SERT](https://github.com/somespecialone/sert) and use service endpoints.
+
+## Installation
+
+You can install `converter` with `aiosteampy[converter]` install target. For instance:
+
+```shell
+poetry add aiosteampy[converter]
+```
+
+## Creating instance and loading rates
+
+Before start converting rates need to be loaded.
+
+```python
+from aiosteampy.converter import CurrencyConverter
+
+converter = CurrencyConverter()
+await converter.load()
+```
+
+## Converting
+
+Assuming that rates loaded we can convert prices of the items on steam market.
+
+!!! info "Target currency"
+    Default target converted currency is `USD` but You can pass target currency as third argument
+
+```python
+from aiosteampy import Currency
+
+amount_in_usd = converter.convert(14564, Currency.UAH)
+
+# if You need different target currency
+amount_in_eur = converter.convert(14564, Currency.UAH, Currency.EUR)
+```
+
+## Updating rates
+
+Service update rates frequently and to synchronize rates with it You can use `synchronize` method of the instance.
+This will create and run a coroutine wrapped in `asyncio.Task` in the background.
+
+!!! warning "croniter"
+    This functionality requires [croniter](https://github.com/kiorky/croniter) library to work, which will be already installed with `aiosteampy[converter]`
+
+```python
+converter.synchronize()
+```
+
+### Graceful shutdown
+
+In that case You need to `close` instance and handle canceling `_sync_task` before shutdown Your application:
+
+```python
+converter.close()
+```
+
+## Available currencies
+
+You can see available currencies in [converter web app](https://converter.somespecial.one/).
+Just in case You need more or different currencies you can host the service by yourself and pass `api_url` argument to instance.
+
+```python
+from yarl import URL
+
+my_api_url = URL("https://mydomain.com")
+
+converter = CurrencyConverter(api_url=my_api_url)
+```

mkdocs.yml

@@ -72,14 +72,16 @@ markdown_extensions:
 nav:
   - Overview: index.md
   - Install: install.md
-  - 'Getting started 🚀': get_started.md
+  - "Getting started 🚀": get_started.md
   - Client: client.md
   - Market: market.md
   - Trade: trade.md
   - Public: public.md
-  - States&cache: states.md
+  - States&Cache: states.md
+  - Extensions:
+      - Converter: ext/converter.md
   - Examples:
-      - 'states mixin': examples/states.md
-      - 'session persistence': examples/session.md
-      - '3rd party sites auth': examples/auth_3rd_party_site.md
-  - 'Testing 🧪': tests.md
+      - "States mixin": examples/states.md
+      - "Session persistence": examples/session.md
+      - "3rd party sites auth": examples/auth_3rd_party_site.md
+  - "Testing 🧪": tests.md

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "aiosteampy"
-version = "0.3.0"
+version = "0.4.0"
 description = "Simple library to trade and interact with steam market, webapi, guard"
 license = "MIT"
 authors = ["Dmytro Tkachenko <[email protected]>"]