18.5.6.1.Windows event loop¶

On Windows, the default event loop isSelectorEventLoop which does notsupport subprocesses.ProactorEventLoop should be used instead.Example to use it on Windows:

importasyncio,sysifsys.platform=='win32':loop=asyncio.ProactorEventLoop()asyncio.set_event_loop(loop)

18.5.6.2.Create a subprocess: high-level API using Process¶

coroutineasyncio.create_subprocess_exec(*args,stdin=None,stdout=None,stderr=None,loop=None,limit=None,**kwds)¶

Create a subprocess.

Thelimit parameter sets the buffer limit passed to theStreamReader. SeeAbstractEventLoop.subprocess_exec() for otherparameters.

Return aProcess instance.

This function is acoroutine.

coroutineasyncio.create_subprocess_shell(cmd,stdin=None,stdout=None,stderr=None,loop=None,limit=None,**kwds)¶

Run the shell commandcmd.

Thelimit parameter sets the buffer limit passed to theStreamReader. SeeAbstractEventLoop.subprocess_shell() for otherparameters.

Return aProcess instance.

It is the application’s responsibility to ensure that all whitespace andmetacharacters are quoted appropriately to avoidshell injectionvulnerabilities. Theshlex.quote() function can be used to properlyescape whitespace and shell metacharacters in strings that are going to beused to construct shell commands.

This function is acoroutine.

Use theAbstractEventLoop.connect_read_pipe() andAbstractEventLoop.connect_write_pipe() methods to connect pipes.

18.5.6.3.Create a subprocess: low-level API using subprocess.Popen¶

Run subprocesses asynchronously using thesubprocess module.

coroutineAbstractEventLoop.subprocess_exec(protocol_factory,*args,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,**kwargs)¶

Create a subprocess from one or more string arguments (character strings orbytes strings encoded to thefilesystem encoding), where the first stringspecifies the program to execute, and the remaining strings specify theprogram’s arguments. (Thus, together the string arguments form thesys.argv value of the program, assuming it is a Python script.) This issimilar to the standard librarysubprocess.Popen class called withshell=False and the list of strings passed as the first argument;however, wherePopen takes a single argument which islist of strings,subprocess_exec() takes multiple string arguments.

Theprotocol_factory must instantiate a subclass of theasyncio.SubprocessProtocol class.

Other parameters:

• stdin: Either a file-like object representing the pipe to be connectedto the subprocess’s standard input stream usingconnect_write_pipe(), or the constantsubprocess.PIPE (the default). By default a new pipe will becreated and connected.

• stdout: Either a file-like object representing the pipe to be connectedto the subprocess’s standard output stream usingconnect_read_pipe(), or the constantsubprocess.PIPE (the default). By default a new pipe will becreated and connected.

• stderr: Either a file-like object representing the pipe to be connectedto the subprocess’s standard error stream usingconnect_read_pipe(), or one of the constantssubprocess.PIPE (the default) orsubprocess.STDOUT.By default a new pipe will be created and connected. Whensubprocess.STDOUT is specified, the subprocess’s standard errorstream will be connected to the same pipe as the standard output stream.

• All other keyword arguments are passed tosubprocess.Popenwithout interpretation, except forbufsize,universal_newlines andshell, which should not be specified at all.

Returns a pair of(transport,protocol), wheretransport is aninstance ofBaseSubprocessTransport.

This method is acoroutine.

See the constructor of thesubprocess.Popen class for parameters.

coroutineAbstractEventLoop.subprocess_shell(protocol_factory,cmd,*,stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE,**kwargs)¶

Create a subprocess fromcmd, which is a character string or a bytesstring encoded to thefilesystem encoding,using the platform’s “shell” syntax. This is similar to the standard librarysubprocess.Popen class called withshell=True.

Theprotocol_factory must instantiate a subclass of theasyncio.SubprocessProtocol class.

Seesubprocess_exec() for more details aboutthe remaining arguments.

Returns a pair of(transport,protocol), wheretransport is aninstance ofBaseSubprocessTransport.

It is the application’s responsibility to ensure that all whitespace andmetacharacters are quoted appropriately to avoidshell injectionvulnerabilities. Theshlex.quote() function can be used to properlyescape whitespace and shell metacharacters in strings that are going to beused to construct shell commands.

This method is acoroutine.

18.5.6.4.Constants¶

asyncio.subprocess.PIPE¶

Special value that can be used as thestdin,stdout orstderr argumenttocreate_subprocess_shell() andcreate_subprocess_exec() andindicates that a pipe to the standard stream should be opened.

asyncio.subprocess.STDOUT¶

Special value that can be used as thestderr argument tocreate_subprocess_shell() andcreate_subprocess_exec() andindicates that standard error should go into the same handle as standardoutput.

asyncio.subprocess.DEVNULL¶

Special value that can be used as thestdin,stdout orstderr argumenttocreate_subprocess_shell() andcreate_subprocess_exec() andindicates that the special fileos.devnull will be used.

18.5.6.5.Process¶

classasyncio.subprocess.Process¶

A subprocess created by thecreate_subprocess_exec() or thecreate_subprocess_shell() function.

The API of theProcess class was designed to beclose to the API of thesubprocess.Popen class, but there are somedifferences:

• There is no explicitpoll() method

• Thecommunicate() andwait() methods don’t take atimeout parameter:use thewait_for() function

• Theuniversal_newlines parameter is not supported (only bytes stringsare supported)

• Thewait() method oftheProcess class is asynchronous whereas thewait() method of thePopenclass is implemented as a busy loop.

This class isnot thread safe. See also theSubprocess and threads section.

coroutinewait()¶

Wait for child process to terminate. Set and returnreturncodeattribute.

This method is acoroutine.

Note

This will deadlock when usingstdout=PIPE orstderr=PIPE andthe child process generates enough output to a pipe such that itblocks waiting for the OS pipe buffer to accept more data. Use thecommunicate() method when using pipes to avoid that.

coroutinecommunicate(input=None)¶

Interact with process: Send data to stdin. Read data from stdout andstderr, until end-of-file is reached. Wait for process to terminate.The optionalinput argument should be data to be sent to the childprocess, orNone, if no data should be sent to the child. The typeofinput must be bytes.

communicate() returns a tuple(stdout_data,stderr_data).

If aBrokenPipeError orConnectionResetError exception israised when writinginput into stdin, the exception is ignored. Itoccurs when the process exits before all data are written into stdin.

Note that if you want to send data to the process’s stdin, you need tocreate the Process object withstdin=PIPE. Similarly, to get anythingother thanNone in the result tuple, you need to givestdout=PIPEand/orstderr=PIPE too.

This method is acoroutine.

Note

The data read is buffered in memory, so do not use this method if thedata size is large or unlimited.

Changed in version 3.4.2:The method now ignoresBrokenPipeError andConnectionResetError.

send_signal(signal)¶

Sends the signalsignal to the child process.

Note

On Windows,SIGTERM is an alias forterminate().CTRL_C_EVENT andCTRL_BREAK_EVENT can be sent to processesstarted with acreationflags parameter which includesCREATE_NEW_PROCESS_GROUP.

terminate()¶

Stop the child. On Posix OSs the method sendssignal.SIGTERMto the child. On Windows the Win32 API functionTerminateProcess() is called to stop the child.

kill()¶

Kills the child. On Posix OSs the function sendsSIGKILL tothe child. On Windowskill() is an alias forterminate().

stdin¶

Standard input stream (StreamWriter),None if the processwas created withstdin=None.

stdout¶

Standard output stream (StreamReader),None if the processwas created withstdout=None.

stderr¶

Standard error stream (StreamReader),None if the processwas created withstderr=None.

Warning

Use thecommunicate() method rather than.stdin.write,.stdout.read or.stderr.readto avoid deadlocks due to streams pausing reading or writing and blockingthe child process.

pid¶

The identifier of the process.

Note that for processes created by thecreate_subprocess_shell()function, this attribute is the process identifier of the spawned shell.

returncode¶

Return code of the process when it exited. ANone value indicatesthat the process has not terminated yet.

A negative value-N indicates that the child was terminated by signalN (Unix only).

18.5.6.6.Subprocess and threads¶

asyncio supports running subprocesses from different threads, but thereare limits:

• An event loop must run in the main thread

• The child watcher must be instantiated in the main thread, before executingsubprocesses from other threads. Call theget_child_watcher()function in the main thread to instantiate the child watcher.

Theasyncio.subprocess.Process class is not thread safe.

18.5.6.7.Subprocess examples¶

importasyncioimportsysclassDateProtocol(asyncio.SubprocessProtocol):def__init__(self,exit_future):self.exit_future=exit_futureself.output=bytearray()defpipe_data_received(self,fd,data):self.output.extend(data)defprocess_exited(self):self.exit_future.set_result(True)@asyncio.coroutinedefget_date(loop):code='import datetime; print(datetime.datetime.now())'exit_future=asyncio.Future(loop=loop)# Create the subprocess controlled by the protocol DateProtocol,# redirect the standard output into a pipecreate=loop.subprocess_exec(lambda:DateProtocol(exit_future),sys.executable,'-c',code,stdin=None,stderr=None)transport,protocol=yield fromcreate# Wait for the subprocess exit using the process_exited() method# of the protocolyield fromexit_future# Close the stdout pipetransport.close()# Read the output which was collected by the pipe_data_received()# method of the protocoldata=bytes(protocol.output)returndata.decode('ascii').rstrip()ifsys.platform=="win32":loop=asyncio.ProactorEventLoop()asyncio.set_event_loop(loop)else:loop=asyncio.get_event_loop()date=loop.run_until_complete(get_date(loop))print("Current date:%s"%date)loop.close()

importasyncio.subprocessimportsys@asyncio.coroutinedefget_date():code='import datetime; print(datetime.datetime.now())'# Create the subprocess, redirect the standard output into a pipecreate=asyncio.create_subprocess_exec(sys.executable,'-c',code,stdout=asyncio.subprocess.PIPE)proc=yield fromcreate# Read one line of outputdata=yield fromproc.stdout.readline()line=data.decode('ascii').rstrip()# Wait for the subprocess exityield fromproc.wait()returnlineifsys.platform=="win32":loop=asyncio.ProactorEventLoop()asyncio.set_event_loop(loop)else:loop=asyncio.get_event_loop()date=loop.run_until_complete(get_date())print("Current date:%s"%date)loop.close()