Programs often expect scripts, commands or additional parameters from StdIn or from input files. Executor tries to support many scenarios -- which one is chosen mainly depends on the ExeConfig `pipes` setting in exe_<program>.dat and on the `template` parameter given to Executor.__init__. (Note: Executor loads the ExeConfig instance for the given program `name` into its `self.exe` field.)

no input (default behaviour)

The program only needs command line parameters

Condition:

template == None

input pipe from STDIN (== ``myprogram | 'some input string'``)

Condition:

exe.pipes == 1 / True
template != None ((or f_in points to existing file))

Setup:

`template` points to an existing file:

Executor reads the template file, completes it in memory, and pushes it directly to the program.

`template` points to string that doesn't look like a file name:

Executor completes the string in memory (using `self.template % self.__dict__`) and pushes it directly to the program. This is the fastest option as it avoids file access alltogether.

`template` == None but f_in points to an *existing* file:

Executor will read this file and push it unmodified to the program via StdIn. (kind of an exception, if used at all, f_in usual points to a *non-existing* file that will receive the completed input.)

input from file (== ``myprogram < input_file``)

Condition:

exe.pipes == 0 / False
template != None
push_inp == 1 / True (default)

Setup:

`template` points to an existing file:

Executor reads the template file, completes it in memory, saves the completed file to disc (creating or overriding self.f_in), opens the file and passes the file handle to the program (instead of STDIN).

`template` points to string that doesn't look like a file name:

Same as 3.1, except that the template is not read from disc but directly taken from memory (see 2.2).

input from file passed as argument to the program (== ``myprogram input_file``)

Condition:

exe.pipes == 0 / False

For this it is up to you to provide the correct program argument.

Setup:

Use template completion:

The best option would be to set an explicit file name for `f_in` and include this file name into `args`, Example:

 exe = ExeConfigCache.get('myprogram')
 assert not exe.pipes 

 x = Executor( 'myprogram', args='input.in', f_in='input.in',
           template='/somewhere/input.template', cwd='/tmp' )

Executor create your input file on the fly which is then passed as first argument.

Without template completion:

Similar, just that you don't give a template:

 x = Executor( 'myprogram', args='input.in', f_in='input.in',
           cwd='/tmp' )

It would then be up to you to provide the correct input file in `/tmp/input.in`. You could override the prepare() hook method for creating it.

There are other ways of doing the same thing. Look at generateInp() to see what is actually going on.

References

See also Biskit.IcmCad for an Example of how to overwrite and use Executor.
See also Biskit.ExeConfig for a description of program configuration.

Instance Methods

[hide private]

__init__(self, name, args='', template=None, f_in=None, f_out=None, f_err=None, strict=1, catch_out=1, push_inp=1, catch_err=0, node=None, nice=0, cwd=None, log=None, debug=0, verbose=None, **kw)
Create Executor.

str version(self)
Version of class (at creation).

str, str communicate(self, cmd, inp, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, shell=0, env=None, cwd=None)
Start and communicate with the new process.

int execute(self, inp=None)
Run external command and block until it is finished.

any run(self, inp_mirror=None)
Run the callculation.

str command(self)
Compose command string from binary, arguments, nice, and node.

dict OR None environment(self)
Setup the environment for the process.

prepare(self)
called before running external program, override!

postProcess(self)
called directly after running the external program, override!

cleanup(self)
Clean up after external program has finished (failed or not).

fail(self)
Called if external program failed, override!

finish(self)
Called if external program finished successfully, override!

isFailed(self)
Detect whether external program failed, override!

str fillTemplate(self)
Create complete input string from template with place holders.

str convertInput(self, inp)
Convert the input to a format used by the selected execution method.

str generateInp(self)
Prepare the program input (file or string) from a template (if present, file or string).

Instance Variables

[hide private]

f_in
will be overridden by self.convertInput()

log
Log object for own program messages

runTime
time needed for last run

output
STDOUT returned by process

error
STDERR returned by process

returncode
int status returned by process

pid
process ID

result
set by self.finish()

Method Details

Class Executor

There are two ways of using Executor

Templates

Communicating Input

References

__init__(self, name, args='', template=None, f_in=None, f_out=None, f_err=None, strict=1, catch_out=1, push_inp=1, catch_err=0, node=None, nice=0, cwd=None, log=None, debug=0, verbose=None, **kw) (Constructor)

version(self)

communicate(self, cmd, inp, bufsize=-1, executable=None, stdin=None, stdout=None, stderr=None, shell=0, env=None, cwd=None)

execute(self, inp=None)

run(self, inp_mirror=None)

command(self)

environment(self)

prepare(self)

postProcess(self)

cleanup(self)

fail(self)

finish(self)

isFailed(self)

fillTemplate(self)

convertInput(self, inp)

generateInp(self)

f_in

log

runTime

output

error

returncode

pid

result

init(self, name, args='', template=None, f_in=None, f_out=None, f_err=None, strict=1, catch_out=1, push_inp=1, catch_err=0, node=None, nice=0, cwd=None, log=None, debug=0, verbose=None, **kw)
(Constructor)