Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 1 | .. currentmodule:: asyncio |
| 2 | |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 3 | .. _asyncio-subprocess: |
| 4 | |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 5 | Subprocess |
| 6 | ========== |
| 7 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 8 | Windows event loop |
| 9 | ------------------ |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 10 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 11 | On Windows, the default event loop is :class:`SelectorEventLoop` which does not |
| 12 | support subprocesses. :class:`ProactorEventLoop` should be used instead. |
| 13 | Example to use it on Windows:: |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 14 | |
Victor Stinner | aea8229 | 2014-07-08 23:42:38 +0200 | [diff] [blame] | 15 | import asyncio, os |
| 16 | |
| 17 | if os.name == 'nt': |
| 18 | loop = asyncio.ProactorEventLoop() |
| 19 | asyncio.set_event_loop(loop) |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 20 | |
Victor Stinner | 778015b | 2014-07-11 12:13:39 +0200 | [diff] [blame] | 21 | .. seealso:: |
| 22 | |
| 23 | :ref:`Available event loops <asyncio-event-loops>` and :ref:`Platform |
| 24 | support <asyncio-platform-support>`. |
| 25 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 26 | |
| 27 | Create a subprocess: high-level API using Process |
| 28 | ------------------------------------------------- |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 29 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 30 | .. coroutinefunction:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 31 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 32 | Create a subprocess. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 33 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 34 | The *limit* parameter sets the buffer limit passed to the |
| 35 | :class:`StreamReader`. See :meth:`BaseEventLoop.subprocess_exec` for other |
| 36 | parameters. |
| 37 | |
| 38 | Return a :class:`~asyncio.subprocess.Process` instance. |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 39 | |
Victor Stinner | 2fb3b82 | 2014-03-13 10:58:03 +0100 | [diff] [blame] | 40 | This function is a :ref:`coroutine <coroutine>`. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 41 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 42 | .. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds) |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 43 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 44 | Run the shell command *cmd*. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 45 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 46 | The *limit* parameter sets the buffer limit passed to the |
| 47 | :class:`StreamReader`. See :meth:`BaseEventLoop.subprocess_shell` for other |
| 48 | parameters. |
| 49 | |
| 50 | Return a :class:`~asyncio.subprocess.Process` instance. |
| 51 | |
| 52 | It is the application's responsibility to ensure that all whitespace and |
| 53 | metacharacters are quoted appropriately to avoid `shell injection |
| 54 | <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_ |
| 55 | vulnerabilities. The :func:`shlex.quote` function can be used to properly |
| 56 | escape whitespace and shell metacharacters in strings that are going to be |
| 57 | used to construct shell commands. |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 58 | |
Victor Stinner | 2fb3b82 | 2014-03-13 10:58:03 +0100 | [diff] [blame] | 59 | This function is a :ref:`coroutine <coroutine>`. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 60 | |
| 61 | Use the :meth:`BaseEventLoop.connect_read_pipe` and |
| 62 | :meth:`BaseEventLoop.connect_write_pipe` methods to connect pipes. |
| 63 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 64 | |
| 65 | Create a subprocess: low-level API using subprocess.Popen |
| 66 | --------------------------------------------------------- |
| 67 | |
| 68 | Run subprocesses asynchronously using the :mod:`subprocess` module. |
| 69 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 70 | .. coroutinemethod:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs) |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 71 | |
Victor Stinner | 6bfd854 | 2014-06-19 12:50:27 +0200 | [diff] [blame] | 72 | Create a subprocess from one or more string arguments (character strings or |
| 73 | bytes strings encoded to the :ref:`filesystem encoding |
| 74 | <filesystem-encoding>`), where the first string |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 75 | specifies the program to execute, and the remaining strings specify the |
| 76 | program's arguments. (Thus, together the string arguments form the |
| 77 | ``sys.argv`` value of the program, assuming it is a Python script.) This is |
| 78 | similar to the standard library :class:`subprocess.Popen` class called with |
| 79 | shell=False and the list of strings passed as the first argument; |
| 80 | however, where :class:`~subprocess.Popen` takes a single argument which is |
| 81 | list of strings, :func:`subprocess_exec` takes multiple string arguments. |
| 82 | |
Victor Stinner | 3c95062 | 2014-10-14 00:02:10 +0200 | [diff] [blame] | 83 | The *protocol_factory* must instanciate a subclass of the |
| 84 | :class:`asyncio.SubprocessProtocol` class. |
| 85 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 86 | Other parameters: |
| 87 | |
| 88 | * *stdin*: Either a file-like object representing the pipe to be connected |
| 89 | to the subprocess's standard input stream using |
| 90 | :meth:`~BaseEventLoop.connect_write_pipe`, or the constant |
| 91 | :const:`subprocess.PIPE` (the default). By default a new pipe will be |
| 92 | created and connected. |
| 93 | |
| 94 | * *stdout*: Either a file-like object representing the pipe to be connected |
| 95 | to the subprocess's standard output stream using |
| 96 | :meth:`~BaseEventLoop.connect_read_pipe`, or the constant |
| 97 | :const:`subprocess.PIPE` (the default). By default a new pipe will be |
| 98 | created and connected. |
| 99 | |
| 100 | * *stderr*: Either a file-like object representing the pipe to be connected |
| 101 | to the subprocess's standard error stream using |
| 102 | :meth:`~BaseEventLoop.connect_read_pipe`, or one of the constants |
| 103 | :const:`subprocess.PIPE` (the default) or :const:`subprocess.STDOUT`. |
| 104 | By default a new pipe will be created and connected. When |
| 105 | :const:`subprocess.STDOUT` is specified, the subprocess's standard error |
| 106 | stream will be connected to the same pipe as the standard output stream. |
| 107 | |
| 108 | * All other keyword arguments are passed to :class:`subprocess.Popen` |
| 109 | without interpretation, except for *bufsize*, *universal_newlines* and |
| 110 | *shell*, which should not be specified at all. |
| 111 | |
| 112 | Returns a pair of ``(transport, protocol)``, where *transport* is an |
| 113 | instance of :class:`BaseSubprocessTransport`. |
| 114 | |
| 115 | This method is a :ref:`coroutine <coroutine>`. |
| 116 | |
| 117 | See the constructor of the :class:`subprocess.Popen` class for parameters. |
| 118 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 119 | .. coroutinemethod:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs) |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 120 | |
Victor Stinner | 6bfd854 | 2014-06-19 12:50:27 +0200 | [diff] [blame] | 121 | Create a subprocess from *cmd*, which is a character string or a bytes |
| 122 | string encoded to the :ref:`filesystem encoding <filesystem-encoding>`, |
| 123 | using the platform's "shell" syntax. This is similar to the standard library |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 124 | :class:`subprocess.Popen` class called with ``shell=True``. |
| 125 | |
Victor Stinner | 3c95062 | 2014-10-14 00:02:10 +0200 | [diff] [blame] | 126 | The *protocol_factory* must instanciate a subclass of the |
| 127 | :class:`asyncio.SubprocessProtocol` class. |
| 128 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 129 | See :meth:`~BaseEventLoop.subprocess_exec` for more details about |
| 130 | the remaining arguments. |
| 131 | |
| 132 | Returns a pair of ``(transport, protocol)``, where *transport* is an |
| 133 | instance of :class:`BaseSubprocessTransport`. |
| 134 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 135 | It is the application's responsibility to ensure that all whitespace and |
| 136 | metacharacters are quoted appropriately to avoid `shell injection |
| 137 | <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_ |
| 138 | vulnerabilities. The :func:`shlex.quote` function can be used to properly |
| 139 | escape whitespace and shell metacharacters in strings that are going to be |
| 140 | used to construct shell commands. |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 141 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 142 | This method is a :ref:`coroutine <coroutine>`. |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 143 | |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 144 | .. seealso:: |
| 145 | |
Victor Stinner | 984600f | 2014-03-25 09:40:26 +0100 | [diff] [blame] | 146 | The :meth:`BaseEventLoop.connect_read_pipe` and |
| 147 | :meth:`BaseEventLoop.connect_write_pipe` methods. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 148 | |
| 149 | |
| 150 | Constants |
| 151 | --------- |
| 152 | |
| 153 | .. data:: asyncio.subprocess.PIPE |
| 154 | |
| 155 | Special value that can be used as the *stdin*, *stdout* or *stderr* argument |
| 156 | to :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and |
| 157 | indicates that a pipe to the standard stream should be opened. |
| 158 | |
| 159 | .. data:: asyncio.subprocess.STDOUT |
| 160 | |
| 161 | Special value that can be used as the *stderr* argument to |
| 162 | :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and |
| 163 | indicates that standard error should go into the same handle as standard |
| 164 | output. |
| 165 | |
| 166 | .. data:: asyncio.subprocess.DEVNULL |
| 167 | |
Victor Stinner | 7280486 | 2014-03-21 11:44:49 +0100 | [diff] [blame] | 168 | Special value that can be used as the *stdin*, *stdout* or *stderr* argument |
| 169 | to :func:`create_subprocess_shell` and :func:`create_subprocess_exec` and |
| 170 | indicates that the special file :data:`os.devnull` will be used. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 171 | |
| 172 | |
| 173 | Process |
| 174 | ------- |
| 175 | |
| 176 | .. class:: asyncio.subprocess.Process |
| 177 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 178 | A subprocess created by the :func:`create_subprocess_exec` or the |
| 179 | :func:`create_subprocess_shell` function. |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 180 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 181 | The API of the :class:`~asyncio.subprocess.Process` class was designed to be |
R David Murray | 2249d9f | 2015-05-14 08:50:38 -0400 | [diff] [blame] | 182 | close to the API of the :class:`subprocess.Popen` class, but there are some |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 183 | differences: |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 184 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 185 | * There is no explicit :meth:`~subprocess.Popen.poll` method |
| 186 | * The :meth:`~subprocess.Popen.communicate` and |
| 187 | :meth:`~subprocess.Popen.wait` methods don't take a *timeout* parameter: |
| 188 | use the :func:`wait_for` function |
| 189 | * The *universal_newlines* parameter is not supported (only bytes strings |
| 190 | are supported) |
| 191 | * The :meth:`~asyncio.subprocess.Process.wait` method of |
| 192 | the :class:`~asyncio.subprocess.Process` class is asynchronous whereas the |
| 193 | :meth:`~subprocess.Popen.wait` method of the :class:`~subprocess.Popen` |
| 194 | class is implemented as a busy loop. |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 195 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 196 | This class is :ref:`not thread safe <asyncio-multithreading>`. See also the |
| 197 | :ref:`Subprocess and threads <asyncio-subprocess-threads>` section. |
| 198 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 199 | .. coroutinemethod:: wait() |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 200 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 201 | Wait for child process to terminate. Set and return :attr:`returncode` |
| 202 | attribute. |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 203 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 204 | This method is a :ref:`coroutine <coroutine>`. |
Victor Stinner | b79eb05 | 2014-02-03 23:08:14 +0100 | [diff] [blame] | 205 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 206 | .. note:: |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 207 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 208 | This will deadlock when using ``stdout=PIPE`` or ``stderr=PIPE`` and |
| 209 | the child process generates enough output to a pipe such that it |
| 210 | blocks waiting for the OS pipe buffer to accept more data. Use the |
| 211 | :meth:`communicate` method when using pipes to avoid that. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 212 | |
Victor Stinner | bdd574d | 2015-02-12 22:49:18 +0100 | [diff] [blame] | 213 | .. coroutinemethod:: communicate(input=None) |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 214 | |
| 215 | Interact with process: Send data to stdin. Read data from stdout and |
| 216 | stderr, until end-of-file is reached. Wait for process to terminate. |
| 217 | The optional *input* argument should be data to be sent to the child |
| 218 | process, or ``None``, if no data should be sent to the child. The type |
| 219 | of *input* must be bytes. |
| 220 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 221 | :meth:`communicate` returns a tuple ``(stdout_data, stderr_data)``. |
| 222 | |
Victor Stinner | d55b54d | 2014-07-17 13:12:03 +0200 | [diff] [blame] | 223 | If a :exc:`BrokenPipeError` or :exc:`ConnectionResetError` exception is |
| 224 | raised when writing *input* into stdin, the exception is ignored. It |
| 225 | occurs when the process exits before all data are written into stdin. |
Victor Stinner | cc996b5 | 2014-07-17 12:25:27 +0200 | [diff] [blame] | 226 | |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 227 | Note that if you want to send data to the process's stdin, you need to |
Victor Stinner | 0c3949c | 2014-02-09 02:51:40 +0100 | [diff] [blame] | 228 | create the Process object with ``stdin=PIPE``. Similarly, to get anything |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 229 | other than ``None`` in the result tuple, you need to give ``stdout=PIPE`` |
| 230 | and/or ``stderr=PIPE`` too. |
| 231 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 232 | This method is a :ref:`coroutine <coroutine>`. |
| 233 | |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 234 | .. note:: |
| 235 | |
| 236 | The data read is buffered in memory, so do not use this method if the |
| 237 | data size is large or unlimited. |
| 238 | |
Victor Stinner | cc996b5 | 2014-07-17 12:25:27 +0200 | [diff] [blame] | 239 | .. versionchanged:: 3.4.2 |
Victor Stinner | d55b54d | 2014-07-17 13:12:03 +0200 | [diff] [blame] | 240 | The method now ignores :exc:`BrokenPipeError` and |
| 241 | :exc:`ConnectionResetError`. |
Victor Stinner | cc996b5 | 2014-07-17 12:25:27 +0200 | [diff] [blame] | 242 | |
Brian Curtin | a1afeec | 2014-02-08 18:36:14 -0600 | [diff] [blame] | 243 | .. method:: send_signal(signal) |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 244 | |
| 245 | Sends the signal *signal* to the child process. |
| 246 | |
| 247 | .. note:: |
| 248 | |
| 249 | On Windows, :py:data:`SIGTERM` is an alias for :meth:`terminate`. |
| 250 | ``CTRL_C_EVENT`` and ``CTRL_BREAK_EVENT`` can be sent to processes |
| 251 | started with a *creationflags* parameter which includes |
| 252 | ``CREATE_NEW_PROCESS_GROUP``. |
| 253 | |
| 254 | .. method:: terminate() |
| 255 | |
| 256 | Stop the child. On Posix OSs the method sends :py:data:`signal.SIGTERM` |
| 257 | to the child. On Windows the Win32 API function |
| 258 | :c:func:`TerminateProcess` is called to stop the child. |
| 259 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 260 | .. method:: kill() |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 261 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 262 | Kills the child. On Posix OSs the function sends :py:data:`SIGKILL` to |
| 263 | the child. On Windows :meth:`kill` is an alias for :meth:`terminate`. |
Victor Stinner | 0844438 | 2014-02-02 22:43:39 +0100 | [diff] [blame] | 264 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 265 | .. attribute:: stdin |
| 266 | |
| 267 | Standard input stream (:class:`StreamWriter`), ``None`` if the process |
| 268 | was created with ``stdin=None``. |
| 269 | |
| 270 | .. attribute:: stdout |
| 271 | |
| 272 | Standard output stream (:class:`StreamReader`), ``None`` if the process |
| 273 | was created with ``stdout=None``. |
| 274 | |
| 275 | .. attribute:: stderr |
| 276 | |
| 277 | Standard error stream (:class:`StreamReader`), ``None`` if the process |
| 278 | was created with ``stderr=None``. |
| 279 | |
| 280 | .. warning:: |
| 281 | |
| 282 | Use the :meth:`communicate` method rather than :attr:`.stdin.write |
| 283 | <stdin>`, :attr:`.stdout.read <stdout>` or :attr:`.stderr.read <stderr>` |
| 284 | to avoid deadlocks due to streams pausing reading or writing and blocking |
| 285 | the child process. |
| 286 | |
| 287 | .. attribute:: pid |
| 288 | |
| 289 | The identifier of the process. |
| 290 | |
| 291 | Note that for processes created by the :func:`create_subprocess_shell` |
| 292 | function, this attribute is the process identifier of the spawned shell. |
| 293 | |
| 294 | .. attribute:: returncode |
| 295 | |
| 296 | Return code of the process when it exited. A ``None`` value indicates |
| 297 | that the process has not terminated yet. |
| 298 | |
| 299 | A negative value ``-N`` indicates that the child was terminated by signal |
| 300 | ``N`` (Unix only). |
Victor Stinner | 7bdf786 | 2014-03-16 21:29:31 +0100 | [diff] [blame] | 301 | |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 302 | |
Victor Stinner | 399c59d | 2015-01-09 01:32:02 +0100 | [diff] [blame] | 303 | .. _asyncio-subprocess-threads: |
| 304 | |
| 305 | Subprocess and threads |
| 306 | ====================== |
| 307 | |
| 308 | asyncio supports running subprocesses from different threads, but there |
| 309 | are limits: |
| 310 | |
| 311 | * An event loop must run in the main thread |
| 312 | * The child watcher must be instantiated in the main thread, before executing |
| 313 | subprocesses from other threads. Call the :func:`get_child_watcher` |
| 314 | function in the main thread to instantiate the child watcher. |
| 315 | |
Victor Stinner | 8370496 | 2015-02-25 14:24:15 +0100 | [diff] [blame] | 316 | The :class:`asyncio.subprocess.Process` class is not thread safe. |
| 317 | |
Victor Stinner | 399c59d | 2015-01-09 01:32:02 +0100 | [diff] [blame] | 318 | .. seealso:: |
| 319 | |
| 320 | The :ref:`Concurrency and multithreading in asyncio |
| 321 | <asyncio-multithreading>` section. |
| 322 | |
| 323 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 324 | Subprocess examples |
| 325 | =================== |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 326 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 327 | Subprocess using transport and protocol |
| 328 | --------------------------------------- |
| 329 | |
| 330 | Example of a subprocess protocol using to get the output of a subprocess and to |
| 331 | wait for the subprocess exit. The subprocess is created by the |
| 332 | :meth:`BaseEventLoop.subprocess_exec` method:: |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 333 | |
| 334 | import asyncio |
| 335 | import sys |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 336 | |
| 337 | class DateProtocol(asyncio.SubprocessProtocol): |
| 338 | def __init__(self, exit_future): |
| 339 | self.exit_future = exit_future |
| 340 | self.output = bytearray() |
| 341 | |
| 342 | def pipe_data_received(self, fd, data): |
| 343 | self.output.extend(data) |
| 344 | |
| 345 | def process_exited(self): |
| 346 | self.exit_future.set_result(True) |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 347 | |
| 348 | @asyncio.coroutine |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 349 | def get_date(loop): |
| 350 | code = 'import datetime; print(datetime.datetime.now())' |
| 351 | exit_future = asyncio.Future(loop=loop) |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 352 | |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 353 | # Create the subprocess controlled by the protocol DateProtocol, |
| 354 | # redirect the standard output into a pipe |
| 355 | create = loop.subprocess_exec(lambda: DateProtocol(exit_future), |
| 356 | sys.executable, '-c', code, |
| 357 | stdin=None, stderr=None) |
| 358 | transport, protocol = yield from create |
| 359 | |
| 360 | # Wait for the subprocess exit using the process_exited() method |
| 361 | # of the protocol |
| 362 | yield from exit_future |
| 363 | |
| 364 | # Close the stdout pipe |
| 365 | transport.close() |
| 366 | |
| 367 | # Read the output which was collected by the pipe_data_received() |
| 368 | # method of the protocol |
| 369 | data = bytes(protocol.output) |
| 370 | return data.decode('ascii').rstrip() |
| 371 | |
| 372 | if sys.platform == "win32": |
Victor Stinner | 6bc2396 | 2014-03-21 11:56:40 +0100 | [diff] [blame] | 373 | loop = asyncio.ProactorEventLoop() |
| 374 | asyncio.set_event_loop(loop) |
| 375 | else: |
| 376 | loop = asyncio.get_event_loop() |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 377 | |
| 378 | date = loop.run_until_complete(get_date(loop)) |
| 379 | print("Current date: %s" % date) |
| 380 | loop.close() |
| 381 | |
| 382 | |
| 383 | Subprocess using streams |
| 384 | ------------------------ |
| 385 | |
| 386 | Example using the :class:`~asyncio.subprocess.Process` class to control the |
| 387 | subprocess and the :class:`StreamReader` class to read from the standard |
| 388 | output. The subprocess is created by the :func:`create_subprocess_exec` |
| 389 | function:: |
| 390 | |
| 391 | import asyncio.subprocess |
| 392 | import sys |
| 393 | |
| 394 | @asyncio.coroutine |
| 395 | def get_date(): |
| 396 | code = 'import datetime; print(datetime.datetime.now())' |
| 397 | |
| 398 | # Create the subprocess, redirect the standard output into a pipe |
| 399 | create = asyncio.create_subprocess_exec(sys.executable, '-c', code, |
| 400 | stdout=asyncio.subprocess.PIPE) |
| 401 | proc = yield from create |
| 402 | |
| 403 | # Read one line of output |
| 404 | data = yield from proc.stdout.readline() |
| 405 | line = data.decode('ascii').rstrip() |
| 406 | |
| 407 | # Wait for the subprocess exit |
| 408 | yield from proc.wait() |
| 409 | return line |
| 410 | |
| 411 | if sys.platform == "win32": |
| 412 | loop = asyncio.ProactorEventLoop() |
| 413 | asyncio.set_event_loop(loop) |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 414 | else: |
Victor Stinner | 3989205 | 2014-10-14 00:52:07 +0200 | [diff] [blame] | 415 | loop = asyncio.get_event_loop() |
| 416 | |
| 417 | date = loop.run_until_complete(get_date()) |
| 418 | print("Current date: %s" % date) |
Victor Stinner | e48d4db | 2014-02-03 23:26:28 +0100 | [diff] [blame] | 419 | loop.close() |