diff -r 7cca663a72eb Doc/library/asyncio-eventloop.rst --- a/Doc/library/asyncio-eventloop.rst Fri Mar 21 11:56:40 2014 +0100 +++ b/Doc/library/asyncio-eventloop.rst Fri Mar 21 12:09:17 2014 +0100 @@ -448,136 +448,6 @@ 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 `. - - 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 `. - - See the constructor of the :class:`subprocess.Popen` class for parameters. - -.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe) - - Register read pipe in eventloop. - - *protocol_factory* should instantiate object with :class:`Protocol` - interface. pipe is file-like object already switched to nonblocking. - Return pair (transport, protocol), where transport support - :class:`ReadTransport` interface. - - This method is a :ref:`coroutine `. - -.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe) - - Register write pipe in eventloop. - - *protocol_factory* should instantiate object with :class:`BaseProtocol` - interface. Pipe is file-like object already switched to nonblocking. - Return pair (transport, protocol), where transport support - :class:`WriteTransport` interface. - - This method is a :ref:`coroutine `. - -.. seealso:: - - The :func:`create_subprocess_exec` and :func:`create_subprocess_shell` - functions. - - -UNIX signals ------------- - -Availability: UNIX only. - -.. method:: BaseEventLoop.add_signal_handler(signum, callback, \*args) - - Add a handler for a signal. - - Raise :exc:`ValueError` if the signal number is invalid or uncatchable. - Raise :exc:`RuntimeError` if there is a problem setting up the handler. - -.. method:: BaseEventLoop.remove_signal_handler(sig) - - Remove a handler for a signal. - - Return ``True`` if a signal handler was removed, ``False`` if not. - -.. seealso:: - - The :mod:`signal` module. - - Executor -------- diff -r 7cca663a72eb Doc/library/asyncio-subprocess.rst --- a/Doc/library/asyncio-subprocess.rst Fri Mar 21 11:56:40 2014 +0100 +++ b/Doc/library/asyncio-subprocess.rst Fri Mar 21 12:09:17 2014 +0100 @@ -3,20 +3,40 @@ 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 `. .. 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 `. Use the :meth:`BaseEventLoop.connect_read_pipe` and @@ -28,6 +48,127 @@ Use the :meth:`BaseEventLoop.connect_rea :meth:`BaseEventLoop.subprocess_shell` methods. +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 `. + + 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 `. + + See the constructor of the :class:`subprocess.Popen` class for parameters. + + +Connect pipes +------------- + +.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe) + + Register read pipe in eventloop. + + *protocol_factory* should instantiate object with :class:`Protocol` + interface. pipe is file-like object already switched to nonblocking. + Return pair (transport, protocol), where transport support + :class:`ReadTransport` interface. + + This method is a :ref:`coroutine `. + +.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe) + + Register write pipe in eventloop. + + *protocol_factory* should instantiate object with :class:`BaseProtocol` + interface. Pipe is file-like object already switched to nonblocking. + Return pair (transport, protocol), where transport support + :class:`WriteTransport` interface. + + This method is a :ref:`coroutine `. + +.. seealso:: + + The :func:`create_subprocess_exec` and :func:`create_subprocess_shell` + functions. + + +UNIX signals +------------ + +Availability: UNIX only. + +.. method:: BaseEventLoop.add_signal_handler(signum, callback, \*args) + + Add a handler for a signal. + + Raise :exc:`ValueError` if the signal number is invalid or uncatchable. + Raise :exc:`RuntimeError` if there is a problem setting up the handler. + +.. method:: BaseEventLoop.remove_signal_handler(sig) + + Remove a handler for a signal. + + Return ``True`` if a signal handler was removed, ``False`` if not. + +.. seealso:: + + The :mod:`signal` module. + + + Constants ---------