Add subprocess section

Author: vinmic

examples/subprocess_command.py

@@ -0,0 +1,23 @@
+import asyncio
+
+
+async def run_command(*args):
+    # Create subprocess
+    process = await asyncio.create_subprocess_exec(
+        *args,
+        # stdout must a pipe to be accessible as process.stdout
+        stdout=asyncio.subprocess.PIPE)
+    # Wait for the subprocess to finish
+    stdout, stderr = await process.communicate()
+    # Return stdout
+    return stdout.decode().strip()
+
+
+loop = asyncio.get_event_loop()
+# Gather uname and date commands
+commands = asyncio.gather(run_command('uname'), run_command('date'))
+# Run the commands
+uname, date = loop.run_until_complete(commands)
+# Print a report
+print('uname: {}, date: {}'.format(uname, date))
+loop.close()

examples/subprocess_echo.py

@@ -0,0 +1,27 @@
+import asyncio
+
+
+async def echo(msg):
+    # Run an echo subprocess
+    process = await asyncio.create_subprocess_exec(
+        'cat',
+        # stdin must a pipe to be accessible as process.stdin
+        stdin=asyncio.subprocess.PIPE,
+        # stdout must a pipe to be accessible as process.stdout
+        stdout=asyncio.subprocess.PIPE)
+    # Write message
+    print('Writing {!r} ...'.format(msg))
+    process.stdin.write(msg.encode() + b'\n')
+    # Read reply
+    data = await process.stdout.readline()
+    reply = data.decode().strip()
+    print('Received {!r}'.format(reply))
+    # Stop the subprocess
+    process.terminate()
+    code = await process.wait()
+    print('Terminated with code {}'.format(code))
+
+
+loop = asyncio.get_event_loop()
+loop.run_until_complete(echo('hello!'))
+loop.close()

index.rst

@@ -24,6 +24,7 @@ Chapter 2: Advanced topics
 
    tcp_echo.rst
    threads.rst
+   subprocess.rst
    producer_consumer.rst
    debug_mode.rst
 
@@ -66,4 +67,3 @@ Contributing
    :maxdepth: 2
 
    README.rst
-

subprocess.rst

@@ -0,0 +1,28 @@
+++++++++++
+Subprocess
+++++++++++
+
+Run a subprocess and read its output
+====================================
+
+A simple example to run commands in a subprocess using
+`asyncio.create_subprocess_exec
+<https://docs.python.org/3.6/library/asyncio-subprocess.html#asyncio.create_subprocess_exec>`_
+and get the output using `process.communicate
+<https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.communicate>`_:
+
+.. literalinclude:: examples/subprocess_command.py
+
+
+Communicate with a subprocess using standard streams
+====================================================
+
+A simple example to communicate with an echo subprocess using `process.stdin
+<https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.stdin>`_
+and `process.stdout
+<https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.stdout>`_:
+
+.. literalinclude:: examples/subprocess_echo.py
+
+For more information, see the `asyncio subprocess documentation
+<https://docs.python.org/3/library/asyncio-subprocess.html>`_.