(Merge 3.4) Issue #21006: asyncio doc: reorganize subprocess doc
This commit is contained in:
Victor Stinner
commit
acb6c0491c
|
|
@ -450,84 +450,8 @@ Resolve host name
|
|||
:meth:`socket.getnameinfo` function but non-blocking.
|
||||
|
||||
|
||||
Running subprocesses
|
||||
--------------------
|
||||
|
||||
Run subprocesses asynchronously using the :mod:`subprocess` module.
|
||||
|
||||
.. note::
|
||||
|
||||
On Windows, the default event loop uses
|
||||
:class:`selectors.SelectSelector` which only supports sockets. The
|
||||
:class:`ProactorEventLoop` should be used to support subprocesses.
|
||||
|
||||
.. note::
|
||||
|
||||
On Mac OS X older than 10.9 (Mavericks), :class:`selectors.KqueueSelector`
|
||||
does not support character devices like PTY, whereas it is used by the
|
||||
default event loop. The :class:`SelectorEventLoop` can be used with
|
||||
:class:`SelectSelector` or :class:`PollSelector` to handle character devices
|
||||
on Mac OS X 10.6 (Snow Leopard) and later.
|
||||
|
||||
.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
|
||||
|
||||
Create a subprocess from one or more string arguments, where the first string
|
||||
specifies the program to execute, and the remaining strings specify the
|
||||
program's arguments. (Thus, together the string arguments form the
|
||||
``sys.argv`` value of the program, assuming it is a Python script.) This is
|
||||
similar to the standard library :class:`subprocess.Popen` class called with
|
||||
shell=False and the list of strings passed as the first argument;
|
||||
however, where :class:`~subprocess.Popen` takes a single argument which is
|
||||
list of strings, :func:`subprocess_exec` takes multiple string arguments.
|
||||
|
||||
Other parameters:
|
||||
|
||||
* *stdin*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard input stream using
|
||||
:meth:`~BaseEventLoop.connect_write_pipe`, or the constant
|
||||
:const:`subprocess.PIPE` (the default). By default a new pipe will be
|
||||
created and connected.
|
||||
|
||||
* *stdout*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard output stream using
|
||||
:meth:`~BaseEventLoop.connect_read_pipe`, or the constant
|
||||
:const:`subprocess.PIPE` (the default). By default a new pipe will be
|
||||
created and connected.
|
||||
|
||||
* *stderr*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard error stream using
|
||||
:meth:`~BaseEventLoop.connect_read_pipe`, or one of the constants
|
||||
:const:`subprocess.PIPE` (the default) or :const:`subprocess.STDOUT`.
|
||||
By default a new pipe will be created and connected. When
|
||||
:const:`subprocess.STDOUT` is specified, the subprocess's standard error
|
||||
stream will be connected to the same pipe as the standard output stream.
|
||||
|
||||
* All other keyword arguments are passed to :class:`subprocess.Popen`
|
||||
without interpretation, except for *bufsize*, *universal_newlines* and
|
||||
*shell*, which should not be specified at all.
|
||||
|
||||
Returns a pair of ``(transport, protocol)``, where *transport* is an
|
||||
instance of :class:`BaseSubprocessTransport`.
|
||||
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
|
||||
.. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
|
||||
|
||||
Create a subprocess from *cmd*, which is a string using the platform's
|
||||
"shell" syntax. This is similar to the standard library
|
||||
:class:`subprocess.Popen` class called with ``shell=True``.
|
||||
|
||||
See :meth:`~BaseEventLoop.subprocess_exec` for more details about
|
||||
the remaining arguments.
|
||||
|
||||
Returns a pair of ``(transport, protocol)``, where *transport* is an
|
||||
instance of :class:`BaseSubprocessTransport`.
|
||||
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
Connect pipes
|
||||
-------------
|
||||
|
||||
.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
|
||||
|
||||
|
|
@ -553,8 +477,8 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
|||
|
||||
.. seealso::
|
||||
|
||||
The :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
|
||||
functions.
|
||||
The :meth:`BaseEventLoop.subprocess_exec` and
|
||||
:meth:`BaseEventLoop.subprocess_shell` methods.
|
||||
|
||||
|
||||
UNIX signals
|
||||
|
|
|
|||
|
|
@ -3,29 +3,115 @@
|
|||
Subprocess
|
||||
==========
|
||||
|
||||
Create a subprocess
|
||||
-------------------
|
||||
Operating system support
|
||||
------------------------
|
||||
|
||||
On Windows, the default event loop uses :class:`selectors.SelectSelector`
|
||||
which only supports sockets. The :class:`ProactorEventLoop` should be used to
|
||||
support subprocesses.
|
||||
|
||||
On Mac OS X older than 10.9 (Mavericks), :class:`selectors.KqueueSelector`
|
||||
does not support character devices like PTY, whereas it is used by the
|
||||
default event loop. The :class:`SelectorEventLoop` can be used with
|
||||
:class:`SelectSelector` or :class:`PollSelector` to handle character
|
||||
devices on Mac OS X 10.6 (Snow Leopard) and later.
|
||||
|
||||
|
||||
Create a subprocess: high-level API using Process
|
||||
-------------------------------------------------
|
||||
|
||||
.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
|
||||
|
||||
Run the shell command *cmd* given as a string. Return a :class:`~asyncio.subprocess.Process`
|
||||
instance.
|
||||
|
||||
The optional *limit* parameter sets the buffer limit passed to the
|
||||
:class:`StreamReader`.
|
||||
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
|
||||
|
||||
Create a subprocess. Return a :class:`~asyncio.subprocess.Process` instance.
|
||||
|
||||
The optional *limit* parameter sets the buffer limit passed to the
|
||||
:class:`StreamReader`.
|
||||
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
Use the :meth:`BaseEventLoop.connect_read_pipe` and
|
||||
:meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes.
|
||||
|
||||
|
||||
Create a subprocess: low-level API using subprocess.Popen
|
||||
---------------------------------------------------------
|
||||
|
||||
Run subprocesses asynchronously using the :mod:`subprocess` module.
|
||||
|
||||
.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
|
||||
|
||||
Create a subprocess from one or more string arguments, where the first string
|
||||
specifies the program to execute, and the remaining strings specify the
|
||||
program's arguments. (Thus, together the string arguments form the
|
||||
``sys.argv`` value of the program, assuming it is a Python script.) This is
|
||||
similar to the standard library :class:`subprocess.Popen` class called with
|
||||
shell=False and the list of strings passed as the first argument;
|
||||
however, where :class:`~subprocess.Popen` takes a single argument which is
|
||||
list of strings, :func:`subprocess_exec` takes multiple string arguments.
|
||||
|
||||
Other parameters:
|
||||
|
||||
* *stdin*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard input stream using
|
||||
:meth:`~BaseEventLoop.connect_write_pipe`, or the constant
|
||||
:const:`subprocess.PIPE` (the default). By default a new pipe will be
|
||||
created and connected.
|
||||
|
||||
* *stdout*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard output stream using
|
||||
:meth:`~BaseEventLoop.connect_read_pipe`, or the constant
|
||||
:const:`subprocess.PIPE` (the default). By default a new pipe will be
|
||||
created and connected.
|
||||
|
||||
* *stderr*: Either a file-like object representing the pipe to be connected
|
||||
to the subprocess's standard error stream using
|
||||
:meth:`~BaseEventLoop.connect_read_pipe`, or one of the constants
|
||||
:const:`subprocess.PIPE` (the default) or :const:`subprocess.STDOUT`.
|
||||
By default a new pipe will be created and connected. When
|
||||
:const:`subprocess.STDOUT` is specified, the subprocess's standard error
|
||||
stream will be connected to the same pipe as the standard output stream.
|
||||
|
||||
* All other keyword arguments are passed to :class:`subprocess.Popen`
|
||||
without interpretation, except for *bufsize*, *universal_newlines* and
|
||||
*shell*, which should not be specified at all.
|
||||
|
||||
Returns a pair of ``(transport, protocol)``, where *transport* is an
|
||||
instance of :class:`BaseSubprocessTransport`.
|
||||
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
|
||||
.. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
|
||||
|
||||
Create a subprocess from *cmd*, which is a string using the platform's
|
||||
"shell" syntax. This is similar to the standard library
|
||||
:class:`subprocess.Popen` class called with ``shell=True``.
|
||||
|
||||
See :meth:`~BaseEventLoop.subprocess_exec` for more details about
|
||||
the remaining arguments.
|
||||
|
||||
Returns a pair of ``(transport, protocol)``, where *transport* is an
|
||||
instance of :class:`BaseSubprocessTransport`.
|
||||
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The :meth:`BaseEventLoop.subprocess_exec` and
|
||||
:meth:`BaseEventLoop.subprocess_shell` methods.
|
||||
The :meth:`BaseEventLoop.connect_read_pipe` and
|
||||
:meth:`BaseEventLoop.connect_write_pipe` methods.
|
||||
|
||||
|
||||
Constants
|
||||
|
|
|
|||
Loading…
Reference in New Issue