Merge pull request #304 from lzpap/async_docs

docs: update API docs with async

docs/api.rst

@@ -15,8 +15,12 @@ The available methods can be grouped into two categories:**
 |                                    |                                    |
 +------------------------------------+------------------------------------+
 
+**PyOTA supports both synchronous and asynchronous communication with the network,
+therefore the Core and Extended API classes are available in synchronous and
+asynchronous versions.**
+
 To use the API in your Python application or script, declare an
-API instance of any of the two above.
+API instance of any of the API classes.
 **Since the Extended API incorporates the Core API, usually you end up only
 using the Extended API,** but if for some reason you need only the core
 functionality, the library is there to help you.
@@ -25,12 +29,13 @@ functionality, the library is there to help you.
    :linenos:
    :emphasize-lines: 3,4
 
+   # Synchronous API classes
    from iota import Iota, StrictIota
 
-   # This is how you declare an Extended API, use the methods of this object.
+   # This is how you declare a sync Extended API, use the methods of this object.
    api = Iota('adapter-specification')
 
-   # This is how you declare a Core API, use the methods of this object.
+   # This is how you declare a sync Core API, use the methods of this object.
    api = StrictIota('adapter-specification')
 
 .. py:module:: iota
@@ -41,19 +46,48 @@ implementation point of view, :py:class:`Iota` is a subclass of
 :py:class:`StrictIota`, therefore it inherits every method and attribute
 the latter has.
 
-Take a look on the class definitions and notice that :py:class:`Iota`
-has a :py:class:`Seed` attribute. This is becasue the Extended API is able
-to generate private keys, addresses and signatures from your seed.
-**Your seed never leaves the library and your machine!**
+To use the functionally same, but asynchronous API classes, you can do the
+following:
+
+.. code-block::
+   :linenos:
+   :emphasize-lines: 3,4
+
+   # Asynchronous API classes
+   from iota import AsyncIota, AsyncStrictIota
 
-Core API Class
---------------
+   # This is how you declare an async Extended API, use the methods of this object.
+   api = AsyncIota('adapter-specification')
 
+   # This is how you declare an async  Core API, use the methods of this object.
+   api = AsyncStrictIota('adapter-specification')
+
+
+Take a look on the class definitions and notice that :py:class:`Iota` and
+:py:class:`AsyncIota` have a :py:class:`Seed` attribute. This is because the
+Extended API is able to generate private keys, addresses and signatures from
+your seed. **Your seed never leaves the library and your machine!**
+
+Core API Classes
+----------------
+Synchronous
+^^^^^^^^^^^
 .. autoclass:: StrictIota
     :members: set_local_pow
 
-Extended API Class
-------------------
+Asynchronous
+^^^^^^^^^^^^
+.. autoclass:: AsyncStrictIota
+    :members: set_local_pow
 
+Extended API Classes
+--------------------
+Synchronous
+^^^^^^^^^^^
 .. autoclass:: Iota
     :members: set_local_pow
+
+Asynchronous
+^^^^^^^^^^^^
+.. autoclass:: AsyncIota
+    :members: set_local_pow

docs/core_api.rst

@@ -12,76 +12,113 @@ For the full documentation of all the Core API calls, please refer
 to the `official documentation <https://docs.iota.org/docs/node-software/0.1/
 iri/references/api-reference>`__.
 
+.. note::
+    Below you will find the documentation for both the synchronous and
+    asynchronous versions of the Core API methods.
+
+    It should be made clear, that they do exactly the same IOTA related
+    operations, accept the same arguments and return the same structures.
+    Asynchronous API calls are non-blocking, so your application
+    can do other stuff while waiting for the result from the network.
+
+    While synchronous API calls are regular Python methods, their respective
+    asynchronous versions are `Python coroutines`_. You can ``await`` their
+    results, schedule them for execution inside and event loop and much more.
+    PyOTA uses the built-in `asyncio`_ Python module for asynchronous operation.
+    For an overview of what you can do with it, head over to `this article`_.
+
 .. py:currentmodule:: iota
 
 ``add_neighbors``
 -----------------
 .. automethod:: Iota.add_neighbors
+.. automethod:: AsyncIota.add_neighbors
 
 ``attach_to_tangle``
 --------------------
 .. automethod:: Iota.attach_to_tangle
+.. automethod:: AsyncIota.attach_to_tangle
 
 ``broadcast_transactions``
 --------------------------
 .. automethod:: Iota.broadcast_transactions
+.. automethod:: AsyncIota.broadcast_transactions
 
 ``check_consistency``
 ---------------------
 .. automethod:: Iota.check_consistency
+.. automethod:: AsyncIota.check_consistency
 
 ``find_transactions``
 ---------------------
 .. automethod:: Iota.find_transactions
+.. automethod:: AsyncIota.find_transactions
 
 ``get_balances``
 ----------------
 .. automethod:: Iota.get_balances
+.. automethod:: AsyncIota.get_balances
 
 ``get_inclusion_states``
 ------------------------
 .. automethod:: Iota.get_inclusion_states
+.. automethod:: AsyncIota.get_inclusion_states
 
 ``get_missing_transactions``
 ----------------------------
 .. automethod:: Iota.get_missing_transactions
+.. automethod:: AsyncIota.get_missing_transactions
 
 ``get_neighbors``
 -----------------
 .. automethod:: Iota.get_neighbors
+.. automethod:: AsyncIota.get_neighbors
 
 ``get_node_api_configuration``
 ------------------------------
 .. automethod:: Iota.get_node_api_configuration
+.. automethod:: AsyncIota.get_node_api_configuration
 
 ``get_node_info``
 -----------------
 .. automethod:: Iota.get_node_info
+.. automethod:: AsyncIota.get_node_info
 
 ``get_tips``
 ------------
 .. automethod:: Iota.get_tips
+.. automethod:: AsyncIota.get_tips
 
 ``get_transactions_to_approve``
 -------------------------------
 .. automethod:: Iota.get_transactions_to_approve
+.. automethod:: AsyncIota.get_transactions_to_approve
 
 ``get_trytes``
 --------------
 .. automethod:: Iota.get_trytes
+.. automethod:: AsyncIota.get_trytes
 
 ``interrupt_attaching_to_tangle``
 ---------------------------------
 .. automethod:: Iota.interrupt_attaching_to_tangle
+.. automethod:: AsyncIota.interrupt_attaching_to_tangle
 
 ``remove_neighbors``
 --------------------
 .. automethod:: Iota.remove_neighbors
+.. automethod:: AsyncIota.remove_neighbors
 
 ``store_transactions``
 ----------------------
 .. automethod:: Iota.store_transactions
+.. automethod:: AsyncIota.store_transactions
 
 ``were_addresses_spent_from``
 -----------------------------
-.. automethod:: Iota.were_addresses_spent_from
+.. automethod:: Iota.were_addresses_spent_from
+.. automethod:: AsyncIota.were_addresses_spent_from
+
+.. _Python coroutines: https://docs.python.org/3/library/asyncio-task.html
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
+.. _this article: https://realpython.com/async-io-python/

docs/extended_api.rst

@@ -4,77 +4,114 @@ Extended API Methods
 The Extended API includes a number of "high level" commands to perform
 tasks such as sending and receiving transfers.
 
+.. note::
+    Below you will find the documentation for both the synchronous and
+    asynchronous versions of the Extebded API methods.
+
+    It should be made clear, that they do exactly the same IOTA related
+    operations, accept the same arguments and return the same structures.
+    Asynchronous API calls are non-blocking, so your application
+    can do other stuff while waiting for the result from the network.
+
+    While synchronous API calls are regular Python methods, their respective
+    asynchronous versions are `Python coroutines`_. You can ``await`` their
+    results, schedule them for execution inside and event loop and much more.
+    PyOTA uses the built-in `asyncio`_ Python module for asynchronous operation.
+    For an overview of what you can do with it, head over to `this article`_.
+
+
 .. py:currentmodule:: iota
 
 ``broadcast_and_store``
 -----------------------
 .. automethod:: Iota.broadcast_and_store
+.. automethod:: AsyncIota.broadcast_and_store
 
 ``broadcast_bundle``
 --------------------
 .. automethod:: Iota.broadcast_bundle
+.. automethod:: AsyncIota.broadcast_bundle
 
 ``find_transaction_objects``
 ----------------------------
 .. automethod:: Iota.find_transaction_objects
+.. automethod:: AsyncIota.find_transaction_objects
 
 ``get_account_data``
 --------------------
 .. automethod:: Iota.get_account_data
+.. automethod:: AsyncIota.get_account_data
 
 ``get_bundles``
 ---------------
 .. automethod:: Iota.get_bundles
+.. automethod:: AsyncIota.get_bundles
 
 ``get_inputs``
 --------------
 .. automethod:: Iota.get_inputs
+.. automethod:: AsyncIota.get_inputs
 
 ``get_latest_inclusion``
 ------------------------
 .. automethod:: Iota.get_latest_inclusion
+.. automethod:: AsyncIota.get_latest_inclusion
 
 ``get_new_addresses``
 ---------------------
 .. automethod:: Iota.get_new_addresses
+.. automethod:: AsyncIota.get_new_addresses
 
 ``get_transaction_objects``
 ---------------------------
 .. automethod:: Iota.get_transaction_objects
+.. automethod:: AsyncIota.get_transaction_objects
 
 ``get_transfers``
 -----------------
 .. automethod:: Iota.get_transfers
+.. automethod:: AsyncIota.get_transfers
 
 ``is_promotable``
 -----------------
 .. automethod:: Iota.is_promotable
+.. automethod:: AsyncIota.is_promotable
 
 ``is_reattachable``
 -------------------
 .. automethod:: Iota.is_reattachable
+.. automethod:: AsyncIota.is_reattachable
 
 ``prepare_transfer``
 --------------------
 .. automethod:: Iota.prepare_transfer
+.. automethod:: AsyncIota.prepare_transfer
 
 ``promote_transaction``
 -----------------------
 .. automethod:: Iota.promote_transaction
+.. automethod:: AsyncIota.promote_transaction
 
 ``replay_bundle``
 -----------------
 .. automethod:: Iota.replay_bundle
+.. automethod:: AsyncIota.replay_bundle
 
 ``send_transfer``
 -----------------
 .. automethod:: Iota.send_transfer
+.. automethod:: AsyncIota.send_transfer
 
 ``send_trytes``
 ---------------
 .. automethod:: Iota.send_trytes
+.. automethod:: AsyncIota.send_trytes
 
 ``traverse_bundle``
 -------------------
 .. automethod:: Iota.traverse_bundle
+.. automethod:: AsyncIota.traverse_bundle
 
+.. _Python coroutines: https://docs.python.org/3/library/asyncio-task.html
+.. _asyncio: https://docs.python.org/3/library/asyncio.html
+.. _this article: https://realpython.com/async-io-python/