docs/aio.rst
Asyncio Support
===============
This sdk supports `PEP 492 <https://www.python.org/dev/peps/pep-0492/>`_
async/await functionality when running on python 3.5.3+ and
installed with aio extras.
See the relevant `installation section <installation.html#with-asyncio-support>`_
for details on how to install the sdk with aio extras.
The SDK will automatically detect if these conditions are met
when imported, and an asyncio compatible dragonchain client can be
created by awaiting ``dragonchain_sdk.create_aio_client`` with the same
parameters as ``dragonchain_sdk.create_client``.
Why Use Async/Await?
--------------------
Python Async/Await is important for high performance with workloads that
have lots of i/o, as it allows for concurrent code execution.
As communicating over a network is inherantly latent, you can regain
performance for other parts of your application by allowing them to
execute concurrently within an event loop while the dragonchain_sdk may
be waiting on a result from a request to a chain.
For more information on asyncio, async/await, and the python event loop,
read the `Python Documentation <https://docs.python.org/3/library/asyncio.html>`_.
Differences between the regular and async client
------------------------------------------------
There are only a few notable differences between the regular and async client:
1. The async client must be created by awaiting
``dragonchain_sdk.create_aio_client`` instead calling
``dragonchain_sdk.create_client`` (although they take identical parameters,
so reference `create_client <api.html#dragonchain_sdk.create_client>`_ for
arguments)
2. Each function on the client must be awaited
3. When done using the client, its ``.close`` function should be awaited
in order to clean up any persistent network connections. (This function
only exists on async clients)
Other than that, everything else, including function arguments should
be identical.
Usage Example
-------------
The following is a usage example for the async client: creating the client,
making a request to a chain, then closing the client.
.. code:: python3
import asyncio
import dragonchain_sdk
async def main():
# Create our client by awaiting the function
my_client = await dragonchain_sdk.create_aio_client(
dragonchain_id="c2dffKwiGj6AGg4zHkNswgEcyHeQaGr4Cm5SzsFVceVv",
auth_key_id="JSDMWFUJDVTC",
auth_key="n3hlldsFxFdP2De0yMu6A4MFRh1HGzFvn6rJ0ICZzkE",
endpoint="https://35a7371c-a20a-4830-9a59-5d654fcd0a4a.api.dragonchain.com",
)
# Ensure to await all our calls on the client
result = await my_client.get_status()
# Handle the response identically to the regular client
if result["ok"]:
print("Successful call, here is the response from the chain:")
print(result["response"])
else:
print("There was the following error making a call to the dragonchain:")
print(result["response"])
# Make sure to call .close on the client for cleanup when we're done
await my_client.close()
if __name__ == "__main__":
asyncio.get_event_loop().run_until_complete(main())