Skip to content

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, delimiter=b'\n', buffer_size=-1, **kwargs) #

Calls a command

Parameters:

Name Type Description Default
command list, tuple or str

command to call

required
kwargs dict

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

required

Returns:

Type Description
Tuple[Optional[int], List[str], List[str]]

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

checked_call(command, **kwargs) #

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

Parameters:

Name Type Description Default
command list, tuple or str

command to call

required
kwargs dict

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

required

Returns:

Type Description
Tuple[int, List[str], List[str]]

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

CommandlineError #

Bases: Exception

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

Parameters:

Name Type Description Default
returncode int

the return code of the command

required
stdout str

the stdout output produced by the command

required
stderr str

the stderr output produced by the command

required

clean_ansi(line) #

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:

Name Type Description Default
line str or bytes

the line to process

required

Returns:

Type Description
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.

Back to top