\(\newcommand{\B}[1]{ {\bf #1} }\) \(\newcommand{\R}[1]{ {\rm #1} }\) \(\newcommand{\W}[1]{ \; #1 \; }\)

system_command_prc

View page source

Print Run and Check a System Command

Syntax

# result = system_command_prc(
   command                ,
   print_command  = True  ,
   return_stdout  = False ,
   return_stderr  = False ,
   file_stdout    = None  ,
   file_stderr    = None  ,
   write_command  = False ,
# )

Purpose

This routine provides variations on the following steps:

1. Print the system command as it would appear in the shell; i.e., with arguments separated by spaces.

2. Run the system command and wait for it to complete.

3. Check the integer value returned by the system command. If it is non-zero, an assert exception is raised with stderr as the message in the exception.

4. Return the contents of standard out as a python string.

command

is a list with str elements. The first element is the program to execute and the other elements are arguments to the program.

print_command

If this argument is true (false) the command will (will not) be printed before it is executed.

return_stdout

1. If this argument is true, the command’s standard output will be returned.

2. If this argument is false and file_stdout is not None, standard output will be written to a file during the command execution.

3. Otherwise, standard output will be printed during the command execution.

return_stderr

1. If this argument is true, the command’s standard error will be returned.

2. If this argument is false and file_stderr is not None, standard error will be written to a file during the command execution.

3. Otherwise, if an error occurs, an assertion is generated with the command and its standard error in the corresponding message.

file_stdout

If return_stdout is true, this argument must be None. If this argument is not None, it is a file object that is open for writing and standard output will be written to this file.

file_stderr

If return_stderr is true, this argument must be None. If this argument is not None, it is a file object that is open for writing and standard error will be written to this file.

write_command

If write_command is true (false) the command will (will not) be written to file_stdout and file_stderr . If both file_stdout and file_stderr are None, write_command must be false.

result

1. If return_stdout and return stderr are both false, result is None .

2. If return_stdout is true and return_stderr is false, result is a str with the contents of standard output.

3. If return_stderr is true :

   • result.returncode is an int with the command’s return code.

   • result.stderr is an str with the contents of standard error. If the return code is non-zero, the command is included.

   • If return_stdout is also true, result.stdout is an str with the contents of standard output.

Example

Many of the user_example examples use this utility.