Sub-Process I/O — kaa.base v0.6.0 documentation

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »

# 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 `finished` signal (not the `exited` signal).

  #### Synopsis

  Class Hierarchy

  `kaa.Object`
  └─ `kaa.Process`

  Methods

  `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.
  `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

  `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.

    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; see `stop_command`) – 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:

    > 1. The stop command is written (or invoked) if one is specified, and up to wait seconds is given for the child to terminate.
    > 2. A SIGTERM is issued to the child process, and, again, we wait up to wait seconds for the child to terminate.
    > 3. 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 callback) 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.

  `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, ...)`

      Parameters: | chunk (str) – data read from the child’s stdout or stderr.

    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, ...)`

      Parameters: | line (str) – line read from the child’s stdout or stderr.

    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, ...)`

      Parameters: | exitcode – the exit code of the child

    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, ...)`

      Parameters: | exitcode – the exit code of the child

    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`.

### Navigation

- index
- next |
- previous |
- kaa.base v0.6.0 documentation »
- The Core Framework »