Module ExternalProcess

source code

Run external processes with logging of message output.

Usage

To run an external process, e.g. mkmerge, in an "sh" shell, with just error messages logged:

   import wsatools.ExternalProcess as extp
   try:
       extp.run("mkmerge -opt=1 arg")
   except ExternalProcess.Error as error:
     Logger.addExceptionMessage(error)
     raise SystemExit

However, you don't always need to do this and it is faster to not run in an shell. To avoid running the shell, supply the command as a list of strings (with just a single item if there are no arguments):

   extp.run(["mkmerge", "-opt=1", "arg"])

To disable an ExternalProcess.Error exception from being raised if any output is sent to stdErr (i.e. there is an error), just issue this keyword argument:

   raiseOnError=False

This is important for certain CASU programs, for example, that send normal output to stdErr. In this case, stderr is redirected to stdout. Note that ExternalProcess will always raise OSError exceptions when they occur irrespective of this setting.

Turn on various run() options to enhance logging features. The full log as a list of lines is always returned, but doesn't need to be assigned to a variable. If you wish to inspect the program's terminal output, either do:

   output = extp.run("mkmerge -opt=1 arg")

or:

   for line in extp.run("mkmerge -opt=1 arg"):
       Logger.addMessage(line)

The output is always stripped. To get iterable raw output in a direct replacement for os.popen() use the out() method. However, this should only be used when output to stderr does not need to be monitored for exception purposes:

   for line in extp.out("ls"):
       Logger.addMessage(line)

To add/change any environment variables for just this run of the command, issue this keyword argument:

   env={"ENV_VARIABLE": "value", ...}

If you want to parse return codes then both parseStdOut and raiseOnError must be set to False, or else access subprocess.Popen directly. In general, it's better to parse stdErr than return codes, since it contains more information and if a command fails then it generally sends something to stdErr anyway. However, this does depend on your particular command.