scriptharness.commands module

Commands, largely through subprocess.

scriptharness.commands.LOGGER_NAME

str

default logging.Logger name.

scriptharness.commands.STRINGS

dict

Strings for logging.

class scriptharness.commands.Command(command, logger=None, detect_error_cb=None, **kwargs)

Bases: object

Basic command: run and log output. Stdout and stderr are interleaved depending on the timing of the message. Because we’re logging output, we’re expecting text/non-binary output only. For binary output, use the scriptharness.commands.Output object.

command

list or string

The command to send to subprocess.Popen

logger

logging.Logger

logger to log with.

detect_error_cb

function

this function determines whether the command was successful.

history

dict

This dictionary holds the timestamps and status of the command.

kwargs

dict

These kwargs will be passed to subprocess.Popen, except for the optional ‘output_timeout’ and ‘timeout’, which are processed by Command. output_timeout is how long a command can run without outputting anything to the screen/log. timeout is how long the command can run, total.

strings

dict

Strings to log.

add_line(line)

Log the output. Here for subclassing.

Parameters:line (str) – a line of output
finish_process()

Here for subclassing.

static fix_env(env)

Windows environments are fiddly.

Parameters:env (dict) – the environment we’ll be passing to subprocess.Popen.
log_env(env)

Log environment variables. Here for subclassing.

Parameters:env (dict) – the environment we’ll be passing to subprocess.Popen.
log_start()

Log the start of the command, also checking for the existence of cwd if defined.

Raises:scriptharness.exceptions.ScriptHarnessException – if cwd is defined and doesn’t exist.
run()

Run the command.

Raises:scriptharness.exceptions.ScriptHarnessError on error –
class scriptharness.commands.Output(*args, **kwargs)

Bases: scriptharness.commands.Command

Run the command and capture stdout and stderr to separate files. The output can be binary or text.

strings

dict

Strings to log.

stdout

NamedTemporaryFile

file to log stdout to

stderr

NamedTemporaryFile

file to log stderr to

+ all of the attributes in scriptharness.commands.Command
cleanup()

Best effort cleanup of stdout and stderr temp files.

finish_process()

Close the filehandles.

get_output(handle_name=u'stdout', text=True)

Get output from file. This reads the output into memory, so this is not appropriate for large amounts of output.

Parameters:
  • handle_name (Optional[“stdout” or “stderr”]) – the handle to read from. Defaults to “stdout”
  • text (Optional[bool]) – whether the output is text. If so, run output through to_unicode() and rstrip(). Defaults to True.
run()
class scriptharness.commands.ParsedCommand(command, error_list=None, parser=None, **kwargs)

Bases: scriptharness.commands.Command

Parse each line of output for errors.

This class could have easily subclassed both OutputParser and Command; that may have been slightly cleaner. However, people have subclassed OutputParser in mozharness for various purposes; keeping the two objects separate may encourage that behavior.

add_line(line)

Send the line to the parser.

Parameters:line (str) – a line of output
scriptharness.commands.check_output(command, logger_name=u'scriptharness.commands.check_output', level=20, log_output=True, **kwargs)

Wrap subprocess.check_output with logging

Parameters:
  • command (str or list) – The command to run.
  • logger_name (Optional[str]) – the logger name to log with.
  • level (Optional[int]) – the logging level to log with. Defaults to logging.INFO
  • log_output (Optional[bool]) – When true, log the output of the command. Defaults to True.
  • **kwargs – sent to subprocess.check_output()
scriptharness.commands.detect_errors(command)

Very basic detect_errors_cb for Command.

This looks in the command.history for return_value. If this is set to 0 or other null value other than None, the command is successful. Otherwise it’s unsuccessful.

Parameters:command (Command obj) –
scriptharness.commands.detect_parsed_errors(command)

Very basic detect_errors_cb for ParsedCommand.

This looks in the command.history for num_errors. If this is set to 0, the command is successful. Otherwise it’s unsuccessful.

Parameters:command (Command obj) –
scriptharness.commands.get_output(*args, **kwds)

Run command and yield the Output cmd object. The stdout and stderr file paths can be retrieved through cmd.stdout and cmd.stderr, respectively.

The output is not logged, and is written as byte data, so this can work for both binary or text. If text, get_text_output is preferred for full logging, unless the output is either sensitive in nature or so verbose that logging it would be more harmful than useful. Also, if text, most likely the consumer will want to pass the output through scriptharness.unicode.to_unicode().

Parameters:
  • command (list or str) – the command to use in subprocess.Popen
  • halt_on_failure (Optional[bool]) – raise ScriptHarnessFatal on error if True. Default: False
  • **kwargs – kwargs to send to scriptharness.commands.Output
Yields:

cmd (scriptharness.commands.Output)
Raises:

scriptharness.exceptions.ScriptHarnessFatal – when halt_on_failure is True and we hit an error or timeout.
scriptharness.commands.get_text_output(command, level=20, **kwargs)

Run command and return the raw stdout from that command. Because we log the output, we’re assuming the output is text.

Parameters:
  • command (list or str) – command for subprocess.Popen
  • level (int) – logging level
  • **kwargs – kwargs to send to scriptharness.commands.Output
Returns:

output – the stdout from the command.
Return type:

text
scriptharness.commands.parse(command, **kwargs)

Shortcut for running a ParsedCommand.

Not entirely sure if this should also catch ScriptHarnessFatal, as those are explicitly trying to kill the script.

Parameters:
  • command (list or str) – Command line to run.
  • **kwargs – kwargs for run/ParsedCommand.
Returns:

command exit code (int)
Raises:

scriptharness.exceptions.ScriptHarnessFatal – on fatal error
scriptharness.commands.run(command, cmd_class=<class 'scriptharness.commands.Command'>, halt_on_failure=False, *args, **kwargs)

Shortcut for running a Command.

Not entirely sure if this should also catch ScriptHarnessFatal, as those are explicitly trying to kill the script.

Parameters:
  • command (list or str) – Command line to run.
  • cmd_class (Optional[Command subclass]) – the class to instantiate. Defaults to scriptharness.commands.Command.
  • halt_on_failure (Optional[bool]) – raise ScriptHarnessFatal on error if True. Default: False
  • **kwargs – kwargs for subprocess.Popen.
Returns:

command exit code (int)
Raises:

scriptharness.exceptions.ScriptHarnessFatal – on fatal error