rox.processes | index

`This module makes it easier to use other programs to process data.
The Process class provides the low-level interface, which you can extend
by subclassing. Processes run in the background, so users can still work
with your application while they are running. If you don't care about that,
you might like to look at Python's builtin popen2 module.
The PipeThroughCommand class extends Process to provide an easy way to
run other commands. It also, optionally, allows a stream of data to be fed
in to the process's standard input, and can collect the output to another
stream. Typical usage:
rox.processes.PipeThroughCommand(('echo', 'hello'), None, file('output', 'w')).wait()
This creates a new process, and execs 'echo hello' in it with output sent
to the file 'output' (any file-like object can be used). The wait() runs a
recursive mainloop, so that your application can still be used while the
command runs, but the wait() itself doesn't return until the command
completes.
Instead of using a tuple for the command, a string may be passed (eg, "echo
hello"). In this case, the shell is used to interpret the command, allowing
pipes, wildcards and so on. Be very careful of escaping in this case (think
about filenames containing spaces, quotes, apostrophes, etc).`

Classes

``

exceptions.Exception
  ChildError
    ChildKilled
Process
  PipeThroughCommand

class ChildError(exceptions.Exception)
`` | `Raised when the child process reports an error.`

Methods defined here:

__init__(self, message)

class ChildKilled(ChildError)
`` | `Raised when child died due to a call to the kill method.`

Methods defined here:

__init__(self)

class PipeThroughCommand(Process)
`` | `A Process that runs a command with given input and output (Python) streams.`

Methods defined here:

__init__(self, command, src, dst)
  `Execute 'command' with src as stdin and writing to stream
  dst. If either stream is not a fileno() stream, temporary files
  will be used as required.
  Either stream may be None if input or output is not required.
  Call the wait() method to wait for the command to finish.
  'command' may be a string (passed to os.system) or a list (os.execvp).`

check_errors(self, errors, status)
  `Raise an exception here if errors (the string the child process wrote to stderr) or
  status (the status from waitpid) seems to warrent it. It will be returned by wait().`

child_died(self, status)

child_run(self)
  `Assigns file descriptors and calls child_run_with_streams.`

child_run_with_streams(self)
  `This is run by the child process. stdin and stdout have already been set up.
  Should call exec() or os._exit() to finish. Default method execs self.command.`

got_error_output(self, data)

kill(self, sig=15)

parent_post_fork(self)

pre_fork(self)

start_error(self)

wait(self)
  `Run a recursive mainloop until the command terminates.
  Raises an exception on error.`

class Process
`` | `This represents another process. You should subclass this and override the various methods. Use this when you want to run another process in the background, but still be able to communicate with it.`

Methods defined here:

__init__(self)

child_died(self, status)
  `Called when the child died (actually, when the child
  closes its end of the stderr pipe). The child process has
  already been reaped at this point; 'status' is the status
  returned by os.waitpid.`

child_post_fork(self)
  `Called in the child after forking. Release the parent
  part of any resources allocated in pre_fork().
  Also called (in the parent) if the fork or pre_fork()
  fails. Default method does nothing.`

child_run(self)
  `Called in the child process (after child_post_fork()).
  Do whatever processing is required (perhaps exec another
  process). If you don't exec, call os._exit(n) when done.
  DO NOT make gtk calls in the child process, as it shares its
  parent's connection to the X server until you exec().`

got_error_output(self, data)
  `Read some characters from the child's stderr stream.
  The default method copies to our stderr. Note that 'data'
  isn't necessarily a complete line; it could be a single
  character, or several lines, etc.`

kill(self, sig=15)
  `Send a signal to all processes in the child's process
  group. The default, SIGTERM, requests all the processes
  terminate. SIGKILL is more forceful.`

parent_post_fork(self)
  `This is called in the parent after forking. Free the
  child part of any resources allocated in pre_fork().
  Also called if the fork or pre_fork() fails.
  Default method does nothing.`

pre_fork(self)
  `This is called in 'start' just before forking into
  two processes. If you want to share a resource between
  both processes (eg, a pipe), create it here.
  Default method does nothing.`

start(self)
  `Create the subprocess. Calls pre_fork() and forks.
  The parent then calls parent_post_fork() and returns,
  while the child calls child_post_fork() and then
  child_run().`

start_error(self)
  `An error occurred before or during the fork (possibly
  in pre_fork(). Clean up. Default method calls
  parent_post_fork() and child_post_fork(). On returning,
  the original exception will be raised.`