docs modifications + remove None default of the file_sender generator

Author: leszekhanusz

docs/usage/file_upload.rst

@@ -19,7 +19,7 @@ In order to upload a single file, you need to:
 
     transport = AIOHTTPTransport(url='YOUR_URL')
 
-    client = Client(transport=sample_transport)
+    client = Client(transport=transport)
 
     query = gql('''
       mutation($file: Upload!) {
@@ -46,7 +46,7 @@ It is also possible to upload multiple files using a list.
 
     transport = AIOHTTPTransport(url='YOUR_URL')
 
-    client = Client(transport=sample_transport)
+    client = Client(transport=transport)
 
     query = gql('''
       mutation($files: [Upload!]!) {
@@ -69,51 +69,45 @@ It is also possible to upload multiple files using a list.
     f2.close()
 
 
-Aiohttp StreamReader
---------------------
+Streaming
+---------
 
-In order to upload a aiohttp StreamReader, you need to:
+If you use the above methods to send files, then the entire contents of the files
+must be loaded in memory before the files are sent.
+If the files are not too big and you have enough RAM, it is not a problem.
+On another hand if you want to avoid using too much memory, then it is better
+to read the files and send them in small chunks so that the entire file contents
+don't have to be in memory at once.
 
-* get response from aiohttp request and then get StreamReader from `resp.content`
-* provide the StreamReader to the `variable_values` argument of `execute`
-* set the `upload_files` argument to True
+We provide methods to do that for two different uses cases:
 
+* Sending local files
+* Streaming downloaded files from an external URL to the GraphQL API
 
-.. code-block:: python
+Streaming local files
+^^^^^^^^^^^^^^^^^^^^^
 
-   async with ClientSession() as client:
-       async with client.get('YOUR_URL') as resp:
-           transport = AIOHTTPTransport(url='YOUR_URL')
-           client = Client(transport=transport)
-           query = gql('''
-             mutation($file: Upload!) {
-               singleUpload(file: $file) {
-                 id
-               }
-             }
-           ''')
+aiohttp allows to upload files using an asynchronous generator.
+See `Streaming uploads on aiohttp docs`_.
 
-           params = {"file": resp.content}
 
-           result = client.execute(
-               query, variable_values=params, upload_files=True
-           )
+In order to stream local files, instead of providing opened files to the
+`variables_values` argument of `execute`, you need to provide an async generator
+which will provide parts of the files.
 
-Asynchronous Generator
-----------------------
+You can use `aiofiles`_
+to read the files in chunks and create this asynchronous generator.
 
-In order to upload a single file use asynchronous generator(https://docs.aiohttp.org/en/stable/client_quickstart.html#streaming-uploads), you need to:
+.. _Streaming uploads on aiohttp docs: https://docs.aiohttp.org/en/stable/client_quickstart.html#streaming-uploads
+.. _aiofiles: https://github.com/Tinche/aiofiles
 
-* сreate a asynchronous generator
-* set the generator as a variable value in the mutation
-* provide the opened file to the `variable_values` argument of `execute`
-* set the `upload_files` argument to True
+Example:
 
 .. code-block:: python
 
     transport = AIOHTTPTransport(url='YOUR_URL')
 
-    client = Client(transport=sample_transport)
+    client = Client(transport=transport)
 
     query = gql('''
       mutation($file: Upload!) {
@@ -123,7 +117,7 @@ In order to upload a single file use asynchronous generator(https://docs.aiohttp
       }
     ''')
 
-    async def file_sender(file_name=None):
+    async def file_sender(file_name):
         async with aiofiles.open(file_name, 'rb') as f:
             chunk = await f.read(64*1024)
                 while chunk:
@@ -134,4 +128,50 @@ In order to upload a single file use asynchronous generator(https://docs.aiohttp
 
     result = client.execute(
 		query, variable_values=params, upload_files=True
-	)
+	)
+
+Streaming downloaded files
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If the file you want to upload to the GraphQL API is not present locally
+and needs to be downloaded from elsewhere, then it is possible to chain the download
+and the upload in order to limit the amout of memory used.
+
+Because the `content` attribute of an aiohttp response is a `StreamReader`
+(it provides an async iterator protocol), you can chain the download and the upload
+together.
+
+In order to do that, you need to:
+
+* get the response from an aiohttp request and then get the StreamReader instance
+  from `resp.content`
+* provide the StreamReader instance to the `variable_values` argument of `execute`
+
+Example:
+
+.. code-block:: python
+
+    # First request to download your file with aiohttp
+    async with aiohttp.ClientSession() as http_client:
+        async with http_client.get('YOUR_DOWNLOAD_URL') as resp:
+
+            # We now have a StreamReader instance in resp.content
+            # and we provide it to the variable_values argument of execute
+
+            transport = AIOHTTPTransport(url='YOUR_GRAPHQL_URL')
+
+            client = Client(transport=transport)
+
+            query = gql('''
+              mutation($file: Upload!) {
+                singleUpload(file: $file) {
+                  id
+                }
+              }
+            ''')
+
+            params = {"file": resp.content}
+
+            result = client.execute(
+                query, variable_values=params, upload_files=True
+            )

tests/test_aiohttp.py

@@ -641,7 +641,7 @@ async def test_aiohttp_async_generator_upload(event_loop, aiohttp_server):
 
             file_path = test_file.filename
 
-            async def file_sender(file_name=None):
+            async def file_sender(file_name):
                 async with aiofiles.open(file_name, "rb") as f:
                     chunk = await f.read(64 * 1024)
                     while chunk: