Sub-Process I/O¶

class kaa.Process(cmd, shell=False, dumpfile=None)¶

Create a Process object. The subprocess is not started until start() is called.

Parameters:

cmd (string or list of strings) – the command to be executed.
shell (bool) – True if the command should be executed through a shell. This allows for shell-like syntax (redirection, pipes, etc.), but in this case cmd must be a string.
dumpfile (None, string (path to filename), file object, IOChannel) – File to which all child stdout and stderr will be dumped, or None to disable output dumping.

Process objects passed to kaa.inprogress() return a InProgress that corresponds to the exited signal (not the finished signal).

Synopsis

Class Hierarchy

kaa.Object
└─ kaa.Process

Methods

`communicate()`	One-time interaction with the process, sending the given input, and receiving all output from the child.
`read()`	Reads a chunk of data from either stdout or stderr of the process.
`readline()`	Reads a line from either stdout or stderr, whichever is available first.
`start()`	Starts the process with the given arguments.
`stop()`	Stops the child process.
`write()`	Write data to child’s stdin.

Properties

`delimiter`	read/write	String used to split data for use with `readline()`.
`exitcode`	read-only	The child’s exit code once it has terminated.
`pid`	read-only	The child’s pid when it is running (or stopping), or None when it is not.
`readable`	read-only	True if it is possible to read data from the child.
`running`	read-only	True if the child process is running.
`stderr`	read-only	`IOChannel` of child process’s stderr.
`stdin`	read-only	`IOChannel` of child process’s stdin.
`stdout`	read-only	`IOChannel` of child process’s stdout.
`stop_command`	read/write	Stop command for this process.
`stopping`	read-only	True if the child process is currently being shut down.
`writable`	read-only	True if it is possible to write data to the child.

Signals

`read`	Emitted for each chunk of data read from either stdout or stderr of the child process.
`readline`	Emitted for each line read from either stdout or stderr of the child process.
`finished`	Emitted when the child is dead and all data from stdout and stderr has been consumed.
`exited`	Emitted when the child process has terminated.

Methods

communicate(input=None)¶

One-time interaction with the process, sending the given input, and receiving all output from the child.

Parameters:	input (str) – the data to send to the child’s stdin
Returns:	an `InProgress`, which will be finished with a 2-tuple (stdoutdata, stderrdata)

If the process has not yet been started, start() will be called implicitly.

Any data previously written to the child with write() will be flushed and the pipe to the child’s stdin will be closed. All subsequent data from the child’s stdout and stderr will be read until EOF. The child will be terminated before returning.

This method is modeled after Python’s standard library call subprocess.Popen.communicate().

read()¶

Reads a chunk of data from either stdout or stderr of the process.

There is no way to determine from which (stdout or stderr) the data was read; if you require this, use the stdout or stderr attributes directly (however see warning below).

Returns:	A `InProgress`, finished with the data read. If it is finished the empty string, it means the child’s stdout and stderr were both closed (which is almost certainly because the process exited) and no data was available.

No exception is raised if the child is not readable. Like Socket.read(), it is therefore possible to busy-loop by reading on a dead child:

while True:
    data = yield process.read()
    # Or: data = process.read().wait()

So the return value of read() should be tested for non-None. Alternatively, the readable property could be tested:

while process.readable:
    data = yield process.read()

Warning

You can read directly from stdout or stderr. However, beware of this code, which is wrong:

while process.readable:
    data = yield process.stdout.read()

In the above incorrect example, process.readable may be True even though process.stdout is closed (because process.stderr may not be closed). In this case, process.stdout.read() will finish immediately with None, resulting in a busy loop. The solution is to test the process.stdout.readable property instead:

while process.stdout.readable:
    data = yield process.stdout.read()

readline()¶

Reads a line from either stdout or stderr, whichever is available first.

If finished with None or the empty string, it means that no data was read and the process exited.

Returns:	A `InProgress`, finished with the data read. If it is finished the empty string, it means the child’s stdout and stderr were both closed (which is almost certainly because the process exited) and no data was available.

Like read(), it is possible busy-loop with this method, so you should test its output or test the readable property calling.

start(args='')¶

Starts the process with the given arguments.

Parameters:	args (string or list of strings) – additional arguments when invoking the child, appended to any arguments specified to the initializer.
Returns:	An `InProgress` object, finished with the exitcode when the child process terminates (when the `exited` signal is emitted).

The Process is registered with a global supervisor which holds a strong reference to the Process object while the child process remains active.

Warning

If timeout() is called on the returned InProgress and the timeout occurs, the InProgress returned by start() will be finished with a TimeoutException even though the child process isn’t actually dead. You can always test the running property, or use the finished signal, which doesn’t emit until the child process is genuinely dead.

stop(cmd=None, wait=3.0)¶

Stops the child process.

Parameters:	cmd (string or callable) – stop command used to attempt to terminate the child gracefully; overrides the `stop_command` property if specified. wait (float) – number of seconds to wait between termination steps (see below).
Returns:	A `InProgress`, finished (with None) when the child terminates. If the child refuses to terminate (even with a SIGKILL) an SystemError exception is thrown to the InProgress.

The child process is terminated using the following steps:

The stop command is written (or invoked) if one is specified, and up to wait seconds is given for the child to terminate.

A SIGTERM is issued to the child process, and, again, we wait up to wait seconds for the child to terminate.

A SIGKILL is issued to the child process, and this time we wait up to wait*2 seconds.

If after step 3 the child is still not dead, a SystemError exception is thrown to the InProgress, as well to the InProgress returned by start() and the finished signal will be emitted with the value None.

write(data)¶

Write data to child’s stdin.

Returns an InProgress, which is finished when the data has actually been written to the child’s stdin.

Parameters:	data (string) – the data to be written to the channel.
Returns:	An `InProgress` object, which is finished when the data has actually been written to the child’s stdin. If the channel closes unexpectedly before the data was written, an IOError is thrown to the InProgress.

This is a convenience function, as the caller could do process.stdin.write().

Properties

delimiter¶: String used to split data for use with readline().

exitcode¶

The child’s exit code once it has terminated.

If the child is still running or it has not yet been started, this value will be None.

pid¶: The child’s pid when it is running (or stopping), or None when it is not.

readable¶

True if it is possible to read data from the child.

The child is readable if either the child’s stdout or stderr channels are still open, or if they are both closed but a read call would succeed anyway due to data remaining in the read queue.

This doesn’t necessarily mean the child is still running: a terminated child may still be read from (there may be data buffered in its stdout or stderr channels). Use the running property if you want to see if the child is still running.

running¶

True if the child process is running.

A child that is currently stopping is still considered running. When the running property is False, it means start() may safely be called.

To test whether read() or write() may be called, use the readable and writable properties respectively.

stderr¶

IOChannel of child process’s stderr.

This object is valid even when the child is not running, although it is obviously not readable until the child is started.

stdin¶

IOChannel of child process’s stdin.

This object is valid even when the child is not running.

stdout¶

IOChannel of child process’s stdout.

This object is valid even when the child is not running, although it is obviously not readable until the child is started.

stop_command¶

Stop command for this process.

The command can be either a callable or a string. The command is invoked (if it is a callable) or the command is written to the child’s stdin (if cmd is a string or unicode) when the process is being terminated with a call to stop().

Shutdown handlers for the process should be set with this property.

stopping¶

True if the child process is currently being shut down.

True when stop() was called and the process is not stopped yet.

writable¶

True if it is possible to write data to the child.

If the child process is writable, write() may safely be called. A child that is in the process of stopping is not writable.

Signals

read¶

Emitted for each chunk of data read from either stdout or stderr of the child process.

def callback(chunk, ...)

Param chunk:	data read from the child’s stdout or stderr.
Type chunk:	str

When a callback is connected to the read signal, data is automatically read from the child as soon as it becomes available, and the signal is emitted.

It is allowed to have a callback connected to the read signal and simultaneously use the read() and readline() methods.

readline¶

Emitted for each line read from either stdout or stderr of the child process.

def callback(line, ...)

Param line:	line read from the child’s stdout or stderr.
Type line:	str

It is not allowed to have a callback connected to the readline signal and simultaneously use the readline() method.

Refer to readline() for more details.

finished¶

Emitted when the child is dead and all data from stdout and stderr has been consumed.

def callback(exitcode, ...)

Param exitcode:	the exit code of the child
Type expected:	int

Due to buffering, a child process may be terminated, but the pipes to its stdout and stderr still open possibly containing buffered data yet to be read. This signal emits only when the child has exited and all data has been consumed (or stdout and stderr explicitly closed).

After this signal emits, the readable property will be False.

exited¶

Emitted when the child process has terminated.

def callback(exitcode, ...)

Param exitcode:	the exit code of the child
Type expected:	int

Unlike the finished signal, this signal emits when the child is dead (and has been reaped), however the Process may or may not still be readable.

Sub-Process I/O¶

Synopsis

Methods

Properties

Signals

Previous topic

Next topic

This Page

Navigation

Sub-Process I/O¶

Synopsis

Methods

Properties

Signals

Previous topic

Next topic

This Page

Quick search

Navigation