asyncio: document the new asyncio.subprocess module
This commit is contained in:
parent
9a3424b72e
commit
084443809f
|
@ -353,6 +353,11 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
||||||
|
|
||||||
This method returns a :ref:`coroutine object <coroutine>`.
|
This method returns a :ref:`coroutine object <coroutine>`.
|
||||||
|
|
||||||
|
.. seealso::
|
||||||
|
|
||||||
|
The :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
|
||||||
|
functions.
|
||||||
|
|
||||||
|
|
||||||
UNIX signals
|
UNIX signals
|
||||||
------------
|
------------
|
||||||
|
|
|
@ -9,7 +9,7 @@ Streams (high-level API)
|
||||||
Stream functions
|
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,
|
A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
|
||||||
writer) pair.
|
writer) pair.
|
||||||
|
@ -32,7 +32,7 @@ Stream functions
|
||||||
|
|
||||||
This function returns a :ref:`coroutine object <coroutine>`.
|
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.
|
Start a socket server, call back for each client connected.
|
||||||
|
|
||||||
|
@ -62,7 +62,7 @@ Stream functions
|
||||||
StreamReader
|
StreamReader
|
||||||
============
|
============
|
||||||
|
|
||||||
.. class:: StreamReader(limit=_DEFAULT_LIMIT, loop=None)
|
.. class:: StreamReader(limit=None, loop=None)
|
||||||
|
|
||||||
.. method:: exception()
|
.. method:: exception()
|
||||||
|
|
||||||
|
|
|
@ -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.
|
||||||
|
|
|
@ -48,6 +48,7 @@ Table of content:
|
||||||
asyncio-task.rst
|
asyncio-task.rst
|
||||||
asyncio-protocol.rst
|
asyncio-protocol.rst
|
||||||
asyncio-stream.rst
|
asyncio-stream.rst
|
||||||
|
asyncio-subprocess.rst
|
||||||
asyncio-sync.rst
|
asyncio-sync.rst
|
||||||
asyncio-dev.rst
|
asyncio-dev.rst
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue