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