host.host

otto.host.host.getLoggingCommandOutputEnabled()
Return type:

bool

otto.host.host.isDryRun()

Return True if dry-run mode is enabled globally.

Return type:

bool

otto.host.host.setDryRun(enabled=True)

Enable or disable global dry-run mode.

Return type:

None

class otto.host.host.ShellCommand(cmd, expects=None, timeout=None)

Bases: object

A command plus the per-command options that should be used to run it.

Fields left as None inherit from the run-level kwargs on Host.run(). A scalar Expect value is accepted for expects for ergonomics; it is normalized to a one-element list before execution.

cmd : --is-rst--:py:class:`str`

Command string to execute.

expects : --is-rst--:py:class:`tuple`\ \[:py:class:`str` | :py:class:`~re.Pattern`\ \[:py:class:`str`], :py:class:`str`] | :py:class:`list`\ \[:py:class:`tuple`\ \[:py:class:`str` | :py:class:`~re.Pattern`\ \[:py:class:`str`], :py:class:`str`]] | :py:obj:`None`

Per-command expects. None inherits the run-level expects value.

timeout : --is-rst--:py:class:`float` | :py:obj:`None`

Per-command timeout cap. None inherits the run-level timeout value.

In list form, the effective timeout is always bounded by the remaining cumulative budget.

class otto.host.host.RunResult(status, statuses)

Bases: object

Unified result of Host.run() regardless of how many commands ran.

statuses always has one entry per issued command. status is the aggregate: Status.Success when every entry is ok, otherwise the first non-ok status encountered (matching the old tuple-form semantics).

status : --is-rst--:py:class:`~otto.utils.Status`

Aggregate status across all commands.

statuses : --is-rst--:py:class:`list`\ \[:py:class:`~otto.utils.CommandStatus`]

Per-command statuses in execution order.

property only : CommandStatus

Return the sole CommandStatus when exactly one command ran.

Raises ValueError otherwise — useful for single-command call sites that want to read fields directly without unpacking.

class otto.host.host.Host(*args, **kwargs)

Bases: Protocol

log : --is-rst--:py:class:`bool`

Determines whether this host should log its output to stdout and log files.

interact()
Return type:

None

async run(cmds, expects=None, timeout=None)
Return type:

RunResult

async oneshot(cmd, timeout=None)
Return type:

CommandStatus

async open_session(name)
Return type:

HostSession

async send(text)
Return type:

None

async expect(pattern, timeout=30.0)
Return type:

str

async get(src_files, dest_dir)
Return type:

tuple[Status, str]

async put(src_files, dest_dir)
Return type:

tuple[Status, str]

async close()
Return type:

None

class otto.host.host.BaseHost

Bases: ABC

name : --is-rst--:py:class:`str`
async interact()

Open an interactive shell bridged to the local terminal.

Subclasses implement _interact() to do the actual protocol work. This wrapper exists so CLI and SDK callers have a single public entry point.

Return type:

None

async run(cmds, expects=None, timeout=None)

Execute one or more commands on the host via the persistent shell session.

The session is stateful: working directory changes (cd), exported environment variables, and other shell state persist between calls, just as they would in an interactive terminal.

Parameters:

  • cmds – A single command (str or ShellCommand) or a sequence of commands. Strings and ShellCommand objects may be mixed. For single-command calls, read the result via result.only (or result.statuses[0]).

  • expects – Default (pattern, response) pair(s) for interactive prompts. Accepts a single Expect tuple or a list of them. Each command inherits this value unless its own ShellCommand.expects is set.

  • timeout – For a single command, the per-command timeout. For a sequence, a cumulative timeout shared across all commands — each command receives the remaining budget; when exhausted, remaining commands are skipped with Status.Error. ShellCommand.timeout caps the per-command value but is still bounded by the remaining budget.

Return type:

RunResult

Returns:

RunResult with the aggregate Status and a list of per-command CommandStatus entries.

See also

oneshot(): stateless, concurrent-safe alternative for one-off commands.

async oneshot(cmd, timeout=None)
Return type:

CommandStatus

async open_session(name)
Return type:

HostSession

async send(text)
Return type:

None

async expect(pattern, timeout=30.0)
Return type:

str

async get(src_files, dest_dir)
Return type:

tuple[Status, str]

async put(src_files, dest_dir)
Return type:

tuple[Status, str]

async close()
Return type:

None

start_repeat(name, cmds, interval, times=-1, duration=datetime.timedelta(days=999999999, seconds=86399, microseconds=999999), until=datetime.datetime(9999, 12, 31, 23, 59, 59, 999999), on_result=None, max_history=1000)
Return type:

None

async stop_repeat(name)
Return type:

None

async stop_all_repeats()
Return type:

None

repeat_results(name)
Return type:

list[tuple[datetime, list[CommandStatus]]]

class otto.host.host.HostFilter(name='')

Bases: Filter

Filter log records based on whether command output logging is globally enabled.

host : --is-rst--:py:class:`~otto.host.host.Host` | :py:obj:`None`
filter(record)

Determine if the specified record is to be logged.

Returns True if the record should be logged, or False otherwise. If deemed appropriate, the record may be modified in-place.

Return type:

bool

class otto.host.host.SuppressCommandOutput(host=None)

Bases: object

Suppress command/output logging for one host or globally.

On enter, the prior state is snapshotted; on exit it is restored. That makes nesting safe — an inner context cannot clobber an outer one — and makes concurrent per-host suppressions race-free, since each context only touches its own host’s log attribute.

The no-host (global) path still mutates shared module state, so overlapping global contexts across async tasks can still step on each other. Prefer the per-host form when suppressing work that runs concurrently.

host : --is-rst--:py:data:`~typing.Optional`\ \[:py:class:`~otto.host.host.Host`] = None

Host object to suppress. If not provided, all host output is affected.