Tasks

A task represent an action done locally or on remote hosts. All tasks are asynchronous.

Abstract Task

class rcontrol.core.Task(session, on_done=None)

Represent an asynchronous task.

Parameters:

• session – the session that is responsible of the task. It it accessible via the session attribute on the instance.
• on_done – if not None, should be a callback that takes the instance task as the parameter. It is called when the task is done (finished or timed out). If defined, error_handled() will return True.

error()

Return an instance of a BaseTaskError or None.

error_handled()

Return True if the error must not be reported while using BaseSession.wait_for_tasks().

By default, the error is handled if on_done was specified in the constructor.

is_running()

Return True if the task is running.

raise_if_error()

Check if an error occured and raise it if any.

wait(raise_if_error=True)

Block and wait until the task is finished.

Parameters:raise_if_error – if True, call raise_if_error() at the end.

CommandTask

class rcontrol.core.CommandTask(session, reader_class, command, expected_exit_code=0, combine_stderr=None, timeout=None, output_timeout=None, on_finished=None, on_timeout=None, on_stdout=None, on_stderr=None, on_done=None, finished_callback=None, timeout_callback=None, stdout_callback=None, stderr_callback=None)

Base class that execute a command in an asynchronous way.

It uses an internal stream reader (a subclass of streamreader.StreamsReader)

Parameters:

• session – the session that run this command
• reader_class – the streamreader.StreamsReader class to use
• command – the command to execute (a string)
• expected_exit_code – the expected exit code of the command. If None, there is no exit code expected.
• combine_stderr – if None, stderr and stdout will be automatically combined unless stderr_callback is defined. You can force to combine stderr or stdout by passing True or False.
• timeout – timeout in seconds for the task. If None, no timeout is set - else timeout_callback is called if the command has not finished in time.
• output_timeout – timeout in seconds for waiting output. If None, no timeout is set - else timeout_callback is called if there is no output in time.
• on_finished – a callable that takes one parameter, the command task instance. Called when the command is finished, but not on timeout.
• on_timeout – a callable that takes one parameter, the command task instance. Called on timeout.
• on_stdout – a callable that takes two parameter, the command task instance and the line read. Called on line read from stdout and possibly from stderr if streams are combined..
• on_stderr – a callable that takes two parameter, the command task instance and the line read. Called on line read from stderr.

error()

Return an instance of Exception if any, else None.

Actually check for a TimeoutError or a ExitCodeError.

exit_code()

Return the exit code of the command, or None if the command is not finished yet.

is_running()

Return True if the command is still running.

timed_out()

Return True if a timeout occured.

SshExec

LocalExec

class rcontrol.local.LocalExec(session, command, **kwargs)

Execute a local command.

The execution starts as soon as the object is created.

Basically extend a CommandTask to pass in a specialized stream reader, ProcessReader.

Parameters:

• session – instance of the LocalSession responsible of this command execution
• command – the command to execute (a string)
• kwargs – list of argument passed to the base class constructor

ThreadableTask

class rcontrol.core.ThreadableTask(session, callable, args, kwargs, on_done=None)

A task ran in a background thread.

Task exceptions

class rcontrol.core.BaseTaskError

Raised on a task error. All tasks errors inherit from this.

class rcontrol.core.TimeoutError(session, task, msg)

Raise on a command timeout error

class rcontrol.core.ExitCodeError(session, task, msg)

Raised when the exit code of a command is unexpected

class rcontrol.core.TaskErrors(errors)

A list of task errors