result¶

Unified result family for host verbs.

Every @cli_exposed host verb returns a member of this family (except interact(), which returns None): scalar verbs return Result or CommandResult; run() returns Results. The CLI derives its exit code from Result.exit_code.

>>> from otto.utils import Status
>>> r = Result(Status.Success, value=["mod_a"], msg="")
>>> r.is_ok, r.exit_code
(True, 0)
>>> cr = CommandResult(Status.Failed, value="", command="false", retcode=1)
>>> cr.exit_code
1
>>> res = Results.collect([cr])
>>> res.only.command, res.exit_code, bool(res)
('false', 1, False)

class otto.result.Result(status: Status, value: Any | None = None, msg: str = '')¶

Bases: object

Outcome of a host verb: status + optional payload + human diagnostic.

status : Status¶

Aggregate outcome; see Status.

value : Any = None¶

Verb-specific payload (see the per-verb table in the host guide).

msg : str = ''¶

Human diagnostic; empty on success.

property is_ok : bool¶

True when status counts as passing (Success or Skipped).

property exit_code : int¶

The CLI exit code – 0 when ok, otherwise status.value.

class otto.result.CommandResult(status: Status, value: Any | None = None, msg: str = '', command: str = '', retcode: int = -1)¶

Bases: Result

Result of one shell command; value holds the command’s output.

command : str = ''¶

The command that was issued.

retcode : int = -1¶

Shell return code; -1 means the command never ran.

property exit_code : int¶

The ssh-like CLI exit code – the command’s own retcode.

0 when ok; 255 when the command never ran (retcode -1, matching ssh’s connection-error convention); status.value when the command exited 0 but otto marked it failed (e.g. an expect mismatch).

class otto.result.ShellResult(status: Status, value: Any | None = None, msg: str = '', command: str = '', output: str = '')¶

Bases: Result

Result of one AppShell command.

value holds the parsed object (or the raw output when no parser was given); output always keeps the raw, prompt-stripped text for debugging.

command : str = ''¶

The line sent to the application shell.

output : str = ''¶

Raw output between the echoed command and the next prompt.

class otto.result.Results(status: Status, value: Any | None = None, msg: str = '')¶

Bases: Result, Sequence[CommandResult]

Aggregate over per-command results; itself a Result.

Returned by run() only. value is list[CommandResult] in execution order. Build with collect(), which computes the aggregate status: Success when every entry is ok, otherwise the first non-ok entry’s status. Truthiness follows is_ok, not emptiness.

classmethod collect(items: Sequence[CommandResult], msg: str = '') → Results¶

Build a Results from per-command entries, computing the aggregate.

property only : CommandResult¶

The sole entry when exactly one command ran; ValueError otherwise.

property first_failure : CommandResult | None¶

The first non-ok entry, or None when everything passed.

property exit_code : int¶

0 when ok, else the first failing command’s exit_code.