docs/asyncio.rst
Asyncio support
===============
The library has full support of asyncio, though you need to be aware it has some limitations.
Example
-------
A very basic example on how to do raw API call:
.. code-block:: python
import asyncio
from grapheneapi.aio.websocket import Websocket
import logging
logger = logging.getLogger('websockets')
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler())
loop = asyncio.get_event_loop()
ws = Websocket('wss://eu.nodes.bitshares.ws', loop=loop)
props = loop.run_until_complete(ws.get_dynamic_global_properties())
print(props)
Limitations
-----------
* Most of the classes requires async init because during instantiation some API calls has to be performed:
.. code-block:: python
await Amount('10 FOO')
* Several math operations are not available for :class:`graphenecommon.aio.Amount`, :class:`graphenecommon.aio.Price`
objects. This includes multiplication, division etc. This limitation is due to unability to define python magic
methods (``__mul__``, ``__div__``, etc) as async coroutines
Concurrent RPC calls
--------------------
When using async version, you can perform multiple RPC calls from different coroutines concurrently. The library will
send requests immediately in non-blocking manner. Incoming responses will be properly matched with queries by using "id"
field of json-rpc query.
Subscriptions
-------------
In asyncio version subscription notifications are not handled in callback-based manner. Instead, they are available in
`self.notifications` queue which is :class:`asyncio.Queue`.
Debugging
---------
To enable debugging on RPC level, you can raise loglevel on following loggers (don't forget to set formatter as well):
.. code-block:: python
log = logging.getLogger("websockets")
log.setLevel(logging.DEBUG)
log = logging.getLogger("grapheneapi")
log.setLevel(logging.DEBUG)
Tests
-----
Current testsuite uses pre-populated object cache, so it doesn't cover lots of functionality. Asyncio-specific tests
could be run via ``pytest -v tests/test_*aio*.py``