octoprint.util.commandline

CommandlineCaller()

The CommandlineCaller is a utility class that allows running command line commands while logging their stdout and stderr via configurable callback functions.

Callbacks are expected to have a signature matching

.. code-block:: python

def callback(*lines): do_something_with_the_passed_lines()

The class utilizes sarge underneath.

Example:

.. code-block:: python

from octoprint.util.commandline import CommandLineCaller, CommandLineError

def log(prefix, *lines): for line in lines: print("{} {}".format(prefix, line))

def log_stdout(lines): log(">>>", lines)

def log_stderr(lines): log("!!!", lines)

def log_call(lines) log("---", lines)

caller = CommandLineCaller() caller.on_log_call = log_call caller.on_log_stdout = log_stdout caller.on_log_stderr = log_stderr

try: caller.checked_call(["some", "command", "with", "parameters"]) except CommandLineError as err: print("Command returned {}".format(err.returncode)) else: print("Command finished successfully")

on_log_call = lambda : None instance-attribute

Callback for the called command line

on_log_stderr = lambda : None instance-attribute

Callback for stderr output

on_log_stdout = lambda : None instance-attribute

Callback for stdout output

call(command: Union[str, List[str], Tuple[str]], delimiter: bytes = b'\n', buffer_size: int = -1, logged: bool = True, **kwargs: bool) -> Tuple[Optional[int], List[str], List[str]]

Calls a command

Parameters:

• command ((list, tuple or str)) –

  command to call

• kwargs (dict) –

  additional keyword arguments to pass to the sarge run call (note that _async, stdout and stderr will be overwritten)

Returns:

• Tuple[Optional[int], List[str], List[str]] –

  (tuple) a 3-tuple of return code, full stdout and full stderr output

checked_call(command: Union[str, List[str], Tuple[str]], **kwargs: Union[str, List[str], Tuple[str]]) -> Tuple[int, List[str], List[str]]

Calls a command and raises an error if it doesn't return with return code 0

Parameters:

• command ((list, tuple or str)) –

  command to call

• kwargs (dict) –

  additional keyword arguments to pass to the sarge run call (note that _async, stdout and stderr will be overwritten)

Returns:

• Tuple[int, List[str], List[str]] –

  (tuple) a 3-tuple of return code, full stdout and full stderr output

CommandlineError(returncode, stdout, stderr)

Bases: Exception

Raised by func:~octoprint.util.commandline.CommandLineCaller.checked_call on non zero return codes

Parameters:

• returncode (int) –

  the return code of the command

• stdout (str) –

  the stdout output produced by the command

• stderr (str) –

  the stderr output produced by the command

clean_ansi(line: Union[str, bytes]) -> Union[str, bytes]

Removes ANSI control codes from line.

Note: This function also still supports an input of bytes, leading to an output of bytes. This if for reasons of backwards compatibility only, should no longer be used and considered to be deprecated and to be removed in a future version of OctoPrint. A warning will be logged.

Parameters:

• line (str or bytes) –

  the line to process

Returns:

• Union[str, bytes] –

  (str or bytes) The line without any ANSI control codes

.. versionchanged:: 1.8.0

Usage as clean_ansi(line: bytes) -> bytes is now deprecated and will be removed in a future version of OctoPrint.