asyncio: document the new asyncio.subprocess module

4 files changed, 149 insertions, 3 deletions

diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
index 9a437f8..aac5a94 100644
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -353,6 +353,11 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
 
    This method returns a :ref:`coroutine object <coroutine>`.
 
+.. seealso::
+
+   The :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
+   functions.
+
 
 UNIX signals
 ------------
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
index 52da4e0..9d18baf 100644
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -9,7 +9,7 @@ Streams (high-level API)
 Stream functions
 ================
 
-.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+.. function:: open_connection(host=None, port=None, \*, loop=None, limit=None, **kwds)
 
    A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
    writer) pair.
@@ -32,7 +32,7 @@ Stream functions
 
    This function returns a :ref:`coroutine object <coroutine>`.
 
-.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+.. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
 
    Start a socket server, call back for each client connected.
 
@@ -62,7 +62,7 @@ Stream functions
 StreamReader
 ============
 
-.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
+.. class:: StreamReader(limit=None, loop=None)
 
    .. method:: exception()
 
diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst
new file mode 100644
index 0000000..04610aa
--- /dev/null
+++ b/Doc/library/asyncio-subprocess.rst
@@ -0,0 +1,140 @@
+.. currentmodule:: asyncio
+
+Subprocess
+==========
+
+Create a subproces
+------------------
+
+.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+
+   Run the shell command *cmd* (:class:`str`)`. Return a :class:`Process`
+   instance.
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+
+   Create a subprocess. Return a :class:`Process` instance.
+
+   This function returns a :ref:`coroutine object <coroutine>`.
+
+Use the :meth:`BaseEventLoop.connect_read_pipe` and
+:meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes.
+
+.. seealso::
+
+   The :meth:`BaseEventLoop.subprocess_exec` and
+   :meth:`BaseEventLoop.subprocess_shell` methods.
+
+
+Constants
+---------
+
+.. data:: asyncio.subprocess.PIPE
+
+   Special value that can be used as the *stdin*, *stdout* or *stderr* argument
+   to :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and
+   indicates that a pipe to the standard stream should be opened.
+
+.. data:: asyncio.subprocess.STDOUT
+
+   Special value that can be used as the *stderr* argument to
+   :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and
+   indicates that standard error should go into the same handle as standard
+   output.
+
+.. data:: asyncio.subprocess.DEVNULL
+
+   Special value that can be used as the *stderr* argument to
+   :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and
+   indicates that standard error should go into the same handle as standard
+   output.
+
+
+Process
+-------
+
+.. class:: asyncio.subprocess.Process
+
+   .. attribute:: stdin
+
+      Standard input stream (write), ``None`` if the process was created with
+      ``stdin=None``.
+
+   .. attribute:: stdout
+
+      Standard output stream (read), ``None`` if the process was created with
+      ``stdout=None``.
+
+   .. attribute:: stderr
+
+      Standard error stream (read), ``None`` if the process was created with
+      ``stderr=None``.
+
+   .. attribute:: pid
+
+      The identifier of the process.
+
+      Note that if you set the *shell* argument to ``True``, this is the
+      process identifier of the spawned shell.
+
+   .. attribute:: returncode
+
+      Return code of the process when it exited.  A ``None`` value indicates
+      that the process has not terminated yet.
+
+      A negative value ``-N`` indicates that the child was terminated by signal
+      ``N`` (Unix only).
+
+   .. method:: communicate(input=None)
+
+      Interact with process: Send data to stdin.  Read data from stdout and
+      stderr, until end-of-file is reached.  Wait for process to terminate.
+      The optional *input* argument should be data to be sent to the child
+      process, or ``None``, if no data should be sent to the child.  The type
+      of *input* must be bytes.
+
+      :meth:`communicate` returns a tuple ``(stdoutdata, stderrdata)``.
+
+      Note that if you want to send data to the process's stdin, you need to
+      create the Popen object with ``stdin=PIPE``.  Similarly, to get anything
+      other than ``None`` in the result tuple, you need to give ``stdout=PIPE``
+      and/or ``stderr=PIPE`` too.
+
+      .. note::
+
+         The data read is buffered in memory, so do not use this method if the
+         data size is large or unlimited.
+
+   .. method:: get_subprocess()
+
+      Get the underlying :class:`subprocess.Popen` object.
+
+   .. method:: kill()
+
+      Kills the child. On Posix OSs the function sends :py:data:`SIGKILL` to
+      the child.  On Windows :meth:`kill` is an alias for :meth:`terminate`.
+
+   .. method:: send_signal(signale)
+
+      Sends the signal *signal* to the child process.
+
+      .. note::
+
+         On Windows, :py:data:`SIGTERM` is an alias for :meth:`terminate`.
+         ``CTRL_C_EVENT`` and ``CTRL_BREAK_EVENT`` can be sent to processes
+         started with a *creationflags* parameter which includes
+         ``CREATE_NEW_PROCESS_GROUP``.
+
+   .. method:: terminate()
+
+      Stop the child. On Posix OSs the method sends :py:data:`signal.SIGTERM`
+      to the child. On Windows the Win32 API function
+      :c:func:`TerminateProcess` is called to stop the child.
+
+   .. method:: wait(self):
+
+      Wait for child process to terminate.  Set and return :attr:`returncode`
+      attribute.
+
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index 9787f19..542f476 100644
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -48,6 +48,7 @@ Table of content:
    asyncio-task.rst
    asyncio-protocol.rst
    asyncio-stream.rst
+   asyncio-subprocess.rst
    asyncio-sync.rst
    asyncio-dev.rst