From: Victor Stinner Date: Sun, 2 Feb 2014 21:43:39 +0000 (+0100) Subject: asyncio: document the new asyncio.subprocess module X-Git-Tag: v3.4.0rc1~118 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=084443809f278ae433cc383225afc4d459d58661;p=python asyncio: document the new asyncio.subprocess module --- diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 9a437f8d02..aac5a9451a 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 `. +.. 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 52da4e0c5e..9d18baf8ad 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 `. -.. 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 0000000000..04610aa0f9 --- /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 `. + +.. 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 `. + +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 9787f191c1..542f476d6a 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