[docs] asyncio.docs: Document subprocess_exec and subprocess_shell (issue 20694)

yselivanov.ml at gmail.com yselivanov.ml at gmail.com
Fri Feb 21 00:47:30 CET 2014


Reviewers: gvanrossum,

Message:
Second patch version is uploaded.


http://bugs.python.org/review/20694/diff/11109/Doc/library/asyncio-eventloop.rst
File Doc/library/asyncio-eventloop.rst (right):

http://bugs.python.org/review/20694/diff/11109/Doc/library/asyncio-eventloop.rst#newcode479
Doc/library/asyncio-eventloop.rst:479: list of strings,
:func:`subprocess_exec` takes multiple string arguments.
On 2014/02/21 00:32:26, gvanrossum wrote:
> Maybe add "similar to os.execl()"?

I think it's too low-level and not really widely used/known to add
reference to it, but up to you.

http://bugs.python.org/review/20694/diff/11109/Doc/library/asyncio-eventloop.rst#newcode503
Doc/library/asyncio-eventloop.rst:503: * *bufsize*: The buffer size to
be used when creating a pipe; this is
On 2014/02/21 00:32:26, gvanrossum wrote:
> I don't actually see a use case for setting this nonzero on any
platform, as
> buffered I/O doesn't mesh well with async I/O. I'd rather not call it
out in the
> argument list, but instead add a note to the next bullet saying
"(however,
> *bufsize* should be omitted or zero)". The same is true for shell and
> universal_newlines -- they are only present in the signature so we can
> explicitly check that they aren't set to different values than what we
need.

OK

> Maybe it makes more sense to give an explicit list of the parameters
that *do*
> make sense to pass to Popen?

Maybe you can draft a list?



Please review this at http://bugs.python.org/review/20694/

Affected files:
  Doc/library/asyncio-eventloop.rst


diff -r cd23d0c3f850 Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst	Thu Feb 20 16:20:44 2014 -0500
+++ b/Doc/library/asyncio-eventloop.rst	Thu Feb 20 17:49:34 2014 -0500
@@ -469,7 +469,47 @@
 
 .. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=False, bufsize=0, \*\*kwargs)
 
-   XXX
+   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_write_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.
+
+   * *bufsize*: The buffer size to be used when creating a pipe; this is
+     passed to :class:`subprocess.Popen`. In the default implementation
+     this defaults to zero, and on Windows it must be zero; these defaults
+     deviate from :class:`subprocess.Popen`.
+
+   * All other keyword arguments are passed to :class:`subprocess.Popen`
+     without interpretation.
+
+   Returns a pair of ``(transport, protocol)``, where *transport* is an
+   instance of :class:`BaseSubprocessTransport`.
 
    This method is a :ref:`coroutine <coroutine>`.
 
@@ -477,7 +517,15 @@
 
 .. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=True, bufsize=0, \*\*kwargs)
 
-   XXX
+   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 arguments.
+
+   Returns a pair of ``(transport, protocol)``, where *transport* is an
+   instance of :class:`BaseSubprocessTransport`.
 
    This method is a :ref:`coroutine <coroutine>`.
 




More information about the docs mailing list