Async usage more prominent in the docs

Author: leszekhanusz

README.md

@@ -37,7 +37,7 @@ The complete documentation for GQL can be found at
     * AWS AppSync realtime protocol (experimental)
 * Possibility to [validate the queries locally](https://gql.readthedocs.io/en/latest/usage/validation.html) using a GraphQL schema provided locally or fetched from the backend using an instrospection query
 * Supports GraphQL queries, mutations and [subscriptions](https://gql.readthedocs.io/en/latest/usage/subscriptions.html)
-* Supports [sync or async usage](https://gql.readthedocs.io/en/latest/async/index.html), [allowing concurrent requests](https://gql.readthedocs.io/en/latest/advanced/async_advanced_usage.html#async-advanced-usage)
+* Supports [sync](https://gql.readthedocs.io/en/latest/usage/sync_usage.html) or [async](https://gql.readthedocs.io/en/latest/usage/async_usage.html) usage, [allowing concurrent requests](https://gql.readthedocs.io/en/latest/advanced/async_advanced_usage.html#async-advanced-usage)
 * Supports [File uploads](https://gql.readthedocs.io/en/latest/usage/file_upload.html)
 * Supports [Custom scalars / Enums](https://gql.readthedocs.io/en/latest/usage/custom_scalars_and_enums.html)
 * Supports [Batching requests](https://gql.readthedocs.io/en/latest/advanced/batching_requests.html)

docs/async/async_intro.rst

@@ -6,27 +6,29 @@
 
 async def main():
 
+    # Select your transport with a defined url endpoint
     transport = AIOHTTPTransport(url="https://countries.trevorblades.com/graphql")
 
+    # Create a GraphQL client using the defined transport
+    client = Client(transport=transport)
+
+    # Provide a GraphQL query
+    query = gql(
+        """
+        query getContinents {
+          continents {
+            code
+            name
+          }
+        }
+    """
+    )
+
     # Using `async with` on the client will start a connection on the transport
     # and provide a `session` variable to execute queries on this connection
-    async with Client(
-        transport=transport,
-        fetch_schema_from_transport=True,
-    ) as session:
-
-        # Execute single query
-        query = gql(
-            """
-            query getContinents {
-              continents {
-                code
-                name
-              }
-            }
-        """
-        )
+    async with client as session:
 
+        # Execute the query
         result = await session.execute(query)
         print(result)
 

docs/async/index.rst

@@ -5,7 +5,7 @@
 transport = AIOHTTPTransport(url="https://countries.trevorblades.com/")
 
 # Create a GraphQL client using the defined transport
-client = Client(transport=transport, fetch_schema_from_transport=True)
+client = Client(transport=transport)
 
 # Provide a GraphQL query
 query = gql(

docs/code_examples/aiohttp_async.py

@@ -9,7 +9,6 @@ Contents
 
    intro
    usage/index
-   async/index
    transports/index
    advanced/index
    gql-cli/intro

docs/code_examples/aiohttp_sync.py

@@ -1,17 +1,35 @@
 .. _async_usage:
 
-Async Usage
+Async usage
 ===========
 
+On previous versions of GQL, the code was `sync` only , it means that when you ran
+`execute` on the Client, you could do nothing else in the current Thread and had to wait for
+an answer or a timeout from the backend to continue. The only http library was `requests`, allowing only sync usage.
+
+From the version 3 of GQL, we support `sync` and `async` :ref:`transports <transports>` using `asyncio`_.
+
+With the :ref:`async transports <async_transports>`, there is now the possibility to execute GraphQL requests
+asynchronously, :ref:`allowing to execute multiple requests in parallel if needed <async_advanced_usage>`.
+
+If you don't care or need async functionality, it is still possible, with :ref:`async transports <async_transports>`,
+to run the `execute` or `subscribe` methods directly from the Client
+(as described in the :ref:`Sync Usage <sync_usage>` example) and GQL will execute the request
+in a synchronous manner by running an asyncio event loop itself.
+
+This won't work though if you already have an asyncio event loop running. In that case you should use the async
+methods.
+
+Example
+-------
+
 If you use an :ref:`async transport <async_transports>`, you can use GQL asynchronously using `asyncio`_.
 
 * put your code in an asyncio coroutine (method starting with :code:`async def`)
 * use :code:`async with client as session:` to connect to the backend and provide a session instance
 * use the :code:`await` keyword to execute requests: :code:`await session.execute(...)`
 * then run your coroutine in an asyncio event loop by running :code:`asyncio.run`
 
-Example:
-
 .. literalinclude:: ../code_examples/aiohttp_async.py
 
 IPython

docs/index.rst

@@ -4,7 +4,8 @@ Usage
 .. toctree::
    :maxdepth: 2
 
-   basic_usage
+   sync_usage
+   async_usage
    validation
    subscriptions
    variables

docs/async/async_usage.rst renamed to docs/usage/async_usage.rst

@@ -1,29 +1,76 @@
 Subscriptions
 =============
 
-Using the :ref:`websockets transport <websockets_transport>`, it is possible to execute GraphQL subscriptions:
+Using the :ref:`websockets transport <websockets_transport>`, it is possible to execute GraphQL subscriptions,
+either using the sync or async usage.
+
+The async usage is recommended for any non-trivial tasks (it allows efficient concurrent queries and subscriptions).
+
+See :ref:`Async permanent session <async_permanent_session>`  and :ref:`Async advanced usage <async_advanced_usage>`
+for more advanced examples.
+
+.. note::
+
+    The websockets transport can also execute queries or mutations, it is not restricted to subscriptions.
+
+Sync
+----
 
 .. code-block:: python
 
-    from gql import gql, Client
+    from gql import Client, gql
     from gql.transport.websockets import WebsocketsTransport
 
+    # Select your transport with a defined url endpoint
     transport = WebsocketsTransport(url='wss://your_server/graphql')
 
-    client = Client(
-        transport=transport,
-        fetch_schema_from_transport=True,
-    )
+    # Create a GraphQL client using the defined transport
+    client = Client(transport=transport)
 
+    # Provide a GraphQL subscription query
     query = gql('''
         subscription yourSubscription {
             ...
         }
     ''')
 
+    # Connect and subscribe to the results using a simple 'for'
     for result in client.subscribe(query):
         print (result)
 
-.. note::
+Async
+-----
+
+.. code-block:: python
+
+    import asyncio
+
+    from gql import Client, gql
+    from gql.transport.websockets import WebsocketsTransport
+
+
+    async def main():
+
+        # Select your transport with a defined url endpoint
+        transport = WebsocketsTransport(url='wss://your_server/graphql')
+
+        # Create a GraphQL client using the defined transport
+        client = Client(transport=transport)
+
+        # Provide a GraphQL subscription query
+        query = gql('''
+            subscription yourSubscription {
+                ...
+            }
+        ''')
+
+        # Using `async with` on the client will start a connection on the transport
+        # and provide a `session` variable to execute queries on this connection
+        async with client as session:
+
+            # Then get the results using 'async for'
+            async for result in client.subscribe(query):
+                print (result)
+
 
-    The websockets transport can also execute queries or mutations, it is not restricted to subscriptions
+    asyncio.run(main())

docs/usage/index.rst

@@ -1,9 +1,9 @@
-.. _basic_usage:
+.. _sync_usage:
 
-Basic usage
------------
+Sync usage
+==========
 
-In order to execute a GraphQL request against a GraphQL API:
+To execute a GraphQL request against a GraphQL API:
 
 * create your gql :ref:`transport <transports>` in order to choose the destination url
   and the protocol used to communicate with it
@@ -18,4 +18,3 @@ In order to execute a GraphQL request against a GraphQL API:
     Please note that this basic example won't work if you have an asyncio event loop running. In some
     python environments (as with Jupyter which uses IPython) an asyncio event loop is created for you.
     In that case you should use instead the :ref:`Async Usage example<async_usage>`.
-