exectools

Tools for running external processes.

Functions

level2tag(level)

Classes

BaseOutputHandler([logger])	Base class for output handlers
BaseToolController([logger])	Base class for controlling command line tools.
StringIO	Text I/O implementation using an in-memory buffer.
ToolDescriptor(executable[, args, cwd, env, ...])	Command line tool desctiptor.

exectools.level2tag(level)

class exectools.BaseOutputHandler(logger=None)

Bases: object

Base class for output handlers

close()

Force processing of all buffered data and reset the instance

feed(data)

Feed some data to the parser.

It is processed insofar as it consists of complete elements; incomplete data is buffered until more data is fed or close() is called.

get_line()

Extract complete lines

get_progress()

Search and decode progress patterns

handle_line(data)

Handle output lines.

This method is not meant to be directly called by the user.

The user, anyway, can provide a custom implementation in derived classes.

Parameters:data – an entire output line (including the trailing “end of line” character.

handle_progress(data)

Handle progress data.

This method is not meant to be called by the user.

The user, anyway, can provide a custom implementation in derived classes.

Parameters:data – a list containing an item for each named group in the “progress” regular expression: (pulse, percentage, text) for the default implementation. Each item can be None.

reset()

Reset the handler instance.

Loses all unprocessed data. This is called implicitly at instantiation time.

class exectools.BaseToolController(logger=None)

Bases: object

Base class for controlling command line tools.

A tool controller runs an external tool in controlled way. The output of the child process is handled by the controller and, optionally, notifications can be achieved at sub-process termination.

A tool controller also allows to stop the controlled process.

Note

after the process termination the user can still query both subprocess and stopped for getting info about the executed process.

The user should have care of calling reset() when info n executed process are no more needed or before executing a new process.

connect_output_handlers()

finalize_run(*args, **kwargs)

finalize_run_hook()

Hook method for extra finalization tasks.

This method is always called after finalization and before controller reset.

The user can provide a custom implementation in derived classes in order to perform extra finalization actions.

This method is not meant to be called from the user.

handle_stderr(*args)

handle_stdout(*args)

isbusy

If True then the controller is already running a subprocess.

prerun_hook(cmd)

Hook method for extra pre-run actions.

This method is always called before the controlled subprocess is actually started. The user can provide its own custom implementation in derived classes in order to perform additional actions.

This method is not meant to be called from the user.

reset()

Reset the tool controller instance

run_tool(tool, *args, **kwargs)

stop_tool(force=True)

subprocess = None

the subprocess instance

userstop

If True the process has been stopped by the user.

class exectools.ToolDescriptor(executable, args=None, cwd=None, env=None, stdout_handler=None, stderr_handler=None, output_encoding=None)

Bases: object

Command line tool desctiptor.

A ToolDescriptor instance describes a command line tool (executable), how to run it (args, cwd, env) and how to handle its output (stdout_handler, stderr_handler).

Example:

handler = BaseOutputHandler()
ll = ToolDescriptor(executable='ls', args=['-l'],
                    stdout_handler=handler)
controller.run_tool(ll)

# In this case no executabe is set in the descriptor.
cmd = ToolDescriptor(stdout_handler=handler)

# The executable name is passed at execution time (first argument)
controller.run_tool(cmd, 'ls', '-l')

Parameters:

• executable – full path of the tool executable or just the tool program name if it is in the system search path
• args (list) – default args for command (list of strings)
• cwd – program working directory
• env – environment dictionary
• envmerge – if set to True (default) it is the env dictionaty is used to update the system environment
• stdout_handler – OutputHandler for the stdout of the tool
• stderr_handler – OutputHandler for the stderr of the tool
• output_encoding – output encoding, it is used to decode the subprocess ouput

See also

BaseOutputHandler

args = None

default args for command

cmdline(*args, **kwargs)

Generate the complete command-line for the tool.

This method is meant to be used together with “subprocess” so the “comman-line” actually is a list of strings.

If the executable attribute is not set (evaluate false) then the first non-keyword argument is considered to be the executable tool name.

The command line is build as follows:

executable keyword-arguments args

If you need a command-line in single string form use something like:

' '.join(tool.cmdline(arg1, arg2, arg3))

cwd = None

program working directory

env

the tool environment

envmerge = None

if set to True (default) then the env dictionaty is used to update the system environment

executable = None

full path of the tool executable or just the tool program name

output_encoding = None

output encoding, it is used to decode the subprocess ouput

shell = None

is set to true the external too is executed in a system shell

Warning

some implementation don’t allow to stop a subprocess executed via shell

stderr_handler = None

the OutputHandler for the stderr of the tool

stdout_handler = None

the OutputHandler for the stdout of the tool

See also

BaseOutputHandler