Exec

Run a command with separate arguments, or use shell for shell syntax. Both methods discard stdout and stderr by default. Set capture_output=True to return them as bytes. See Quickstart for checked command output.

class rmote.tools.exec.Exec

Bases: Tool

Run commands and shell expressions on the remote host.

Capture binary output and inspect nonzero exit codes without a shell:

>>> import asyncio
>>> import sys
>>> result = asyncio.run(Exec.command(sys.executable, "-c", "print('hello')", capture_output=True))
>>> result.returncode, result.stdout
(0, b'hello\n')
>>> asyncio.run(Exec.command(sys.executable, "-c", "raise SystemExit(3)", check=False)).returncode
3
>>> asyncio.run(Exec.shell("printf '%s' hello", capture_output=True)).stdout
b'hello'

async static command(*args, check=True, env=None, cwd=None, stdin=None, capture_output=False)

Run a command with explicit argument list.

Parameters:

• *args (Text) – Command and its arguments (e.g. "ls", "-la").

• check (bool) – Raise subprocess.CalledProcessError on non-zero exit, with stdout and stderr when capture_output is enabled.

• env (WSGIEnvironment[Text, Text] | None) – Override environment variables for the subprocess.

• cwd (None | Text | Path) – Working directory; defaults to the remote process’s cwd.

• stdin (None | Text | bytes) – Data written to stdin before the command reads it.

• capture_output (bool) – Capture stdout and stderr as bytes. By default, discard both streams on the remote host.

Return type:

CompletedProcess[bytes | None]

Returns:

subprocess.CompletedProcess with returncode, stdout, and stderr. Output fields contain bytes when captured, or None when capture_output is False.

async static shell(expression, check=True, env=None, cwd=None, stdin=None, capture_output=False)

Run expression through the remote shell (/bin/sh -c).

Parameters:

• expression (Text) – Shell expression, including pipes, redirects, etc.

• check (bool) – Raise subprocess.CalledProcessError on non-zero exit, with stdout and stderr when capture_output is enabled.

• env (WSGIEnvironment[Text, Text] | None) – Override environment variables for the subprocess.

• cwd (None | Text | Path) – Working directory; defaults to the remote process’s cwd.

• stdin (None | Text | bytes) – Data written to stdin before the command reads it.

• capture_output (bool) – Capture stdout and stderr as bytes. By default, discard both streams on the remote host.

Return type:

CompletedProcess[bytes | None]

Returns:

subprocess.CompletedProcess with returncode, stdout, and stderr. Output fields contain bytes when captured, or None when capture_output is False.