qiBuild documentation

qisys.command - Launch processes

Calling process

qisys.command.check_is_in_path(executable, env=None)

Check that the given executable is to be found in %PATH%

qisys.command.find_program(executable, env=None, raises=False)

Get the full path of an executable by looking at PATH environment variable (and PATHEXT on windows)

Returns:None if program was not found, the full path to executable otherwise
qisys.command.call(cmd, cwd=None, env=None, ignore_ret_code=False, quiet=False)

Execute a command line.

If ignore_ret_code is False:
raise CommandFailedException if returncode is None.
Else:
simply returns the returncode of the process

Note: first arg of the cmd is assumed to be something inside %PATH%. (or in env[PATH] if env is not None)

Note: the shell= argument of the subprocess.Popen call will always be False.

can raise:
  • CommandFailedException if ignore_ret_code is False and returncode is non zero
  • NotInPath if first arg of cmd is not in %PATH%
  • And a normal exception if cwd is given and is not an existing directory.
qisys.command.check_output(*popenargs, **kwargs)

Run command with arguments and return its output as a byte string.

If the exit code was non-zero it raises a CommandFailedException. The CommandFailedException object will have the return code in the returncode attribute, output in the stdout attribute and error in the stderr attribute.

The arguments are the same as for the Popen constructor. Example:

>>> check_output(["ls", "-l", "/dev/null"])
'crw-rw-rw- 1 root root 1, 3 Oct 18  2007 /dev/null\n'

The stdout argument is not allowed as it is used internally. To capture standard error in the result, use stderr=STDOUT.

>>> check_output(["/bin/sh", "-c",
...               "ls -l non_existent_file ; exit 0"],
...              stderr=STDOUT)
'ls: non_existent_file: No such file or directory\n'
qisys.command.check_output_error(*popenargs, **kwargs)

Run command with arguments and return its output and error as a byte string.

If the exit code was non-zero it raises a CalledProcessError. The CalledProcessError object will have the return code in the returncode attribute and error concatenated at the end of output in the output attribute.

The arguments are the same as for the Popen constructor. Examples:

>>> check_output_error(["tar", "tf", "foo.tbz2"])
('./\n./usr/\n./usr/bin/\n./usr/bin/foo\n',
'\nbzip2: (stdin): trailing garbage after EOF ignored\n')

>>> try:
...     qisys.command.check_output_error(['tar', '--bzip2', '-tf', 'foo.tar.gz'])
... except subprocess.CalledProcessError as e:
...     print e
The following command failed
['tar', '--bzip2', '-tf', 'foo.tar.gz']
Return code is 2
Working dir was /tmp
Stdout:
    <nothing>
Stderr:
    bzip2: (stdin) is not a bzip2 file.
    tar: Child returned status 2
    tar: Error is not recoverable: exiting now

The stdout and stderr arguments are not allowed as they are used internally.

Notes about call()

Finding the executable to run

When using call(cmd, ...), check_is_in_path() is always call with cmd[0] as argument, then replaced with the result of find_program().

This way, on Windows:

qisys.command.call(["cmake", ...])

works as soon as cmake.exe is in PATH

Behavior

subprocess.Popen is always called with shell=False, for security reasons.

Unless explicitly told not to, CommandFailedException is raised when the return code of the command is not zero.

Running process in the background

qisys.command.call_background(*args, **kwds)

To be used in a “with” statement:

with call_background(...):
   do_stuff()

do_other_stuff()

Process is run in the background, then do_stuff() is called.

By the time you are executing do_other_stuff(), you know that the process has been killed, better yet, if an exception has occurred during do_stuff, this exception is re-raised after the process has been killed.

class qisys.command.Process(cmd, cwd=None, env=None, capture=True)

A simple way to run commands.

Command will be started by run according to timeout parameter (not specified == no timeout). If it firstly send a SIGTERM signal to the process and wait 5 seconds for it to terminate alone (timeout). If it doesn’t stop by itself, it will kill the group of process (created with subprocess) to exterminate it. Process is then considered to be a zombie.

You can then use Process.return_type to know the state of the process: Possible values:

  • Process.OK (exit code is zero)
  • Process.FAILED (exit code is > 0)
  • Process.TIME_OUT (process timed out)
  • Process.INTERRUPTED (exit code is < 0)
  • Process.NOT_RUN (could not start the process)
  • Process.ZOMBIE (could not kill process after it timed out)

Exceptions

class qisys.command.CommandFailedException
class qisys.command.ProcessCrashedError
class qisys.command.NotInPath