Transport

proc.run_cli()

Run a CLI command to completion and return its stdout.

Usage

proc.run_cli(
    argv,
    *,
    input=None,
    timeout=30,
    env=None,
    cwd=None,
)

Parameters

argv: list[str]: The command and its arguments.
input: str | None = None: Text delivered to the process over stdin.
timeout: int = 30: Seconds to wait before the process is killed.
env: dict[str, str] | None = None: Environment for the process; None inherits the current environment.
cwd: str | None = None: Working directory for the process.

Returns

str: The decoded stdout.

Raises

subprocess.CalledProcessError: On a nonzero exit code, with the argv, exit code, and stdout/stderr tails attached as notes.
subprocess.TimeoutExpired: When the process outlives timeout.

proc.arun_cli()

Run a CLI command asynchronously and return its stdout.

Usage

Source

proc.arun_cli(argv, *, input=None, env=None, cwd=None, stderr_tee=None)

Parameters

argv: list[str]: The command and its arguments.
input: str | None = None: Text delivered to the process over stdin.
env: dict[str, str] | None = None: Environment for the process; None inherits the current environment.
cwd: str | None = None: Working directory for the process.
stderr_tee: Callable[[bytes], None] | None = None: Callback invoked with each stderr chunk as it arrives.

Returns

bytes: The raw stdout bytes.

Raises

subprocess.CalledProcessError: On a nonzero exit code.

proc.capture_cli()

Run a CLI command to completion and capture its full outcome.

Usage

Source

proc.capture_cli(
    argv, *, input=None, timeout=180, env=None, cwd=None, stdout_path=None
)

Unlike run_cli, a nonzero exit does not raise; the stdout, stderr, and exit code come back intact so callers can inspect failures and 0-exit error envelopes.

Parameters

argv: list[str]: The command and its arguments.
input: str | None = None: Text delivered to the process over stdin.
timeout: int = 180: Seconds to wait before the process is killed.
env: dict[str, str] | None = None: Environment for the process; None inherits the current environment.
cwd: str | None = None: Working directory for the process.
stdout_path: str | None = None: When set, the child writes stdout to this file (a regular fd) instead of a pipe; the file is read back into RunResult.stdout. A file makes a Node child’s stdout writes synchronous, so a large single-blob write is not truncated when the process exits.

Returns

RunResult: The captured stdout, stderr, and exit code.

Raises

subprocess.TimeoutExpired: When the process outlives timeout.

proc.acapture_cli()

Run a CLI command asynchronously and capture its full outcome.

Usage

Source

proc.acapture_cli(
    argv, *, input=None, env=None, cwd=None, timeout=None, stdout_path=None
)

Unlike arun_cli, a nonzero exit does not raise; the stdout, stderr, and exit code come back intact so callers can inspect failures and 0-exit error envelopes.

Parameters

argv: list[str]: The command and its arguments.
input: str | None = None: Text delivered to the process over stdin.
env: dict[str, str] | None = None: Environment for the process; None inherits the current environment.
cwd: str | None = None: Working directory for the process.
timeout: int | None = None: Seconds to wait before the wait is abandoned; None waits forever.
stdout_path: str | None = None: When set, the child writes stdout to this file (a regular fd) instead of a pipe; the file is read back into RunResult.stdout. A file makes a Node child’s stdout writes synchronous, so a large single-blob write is not truncated when the process exits before the async pipe write drains.

Returns

RunResult: The captured stdout, stderr, and exit code.

Raises

TimeoutError: When the process outlives timeout.

proc.collect_process()

Drain a subprocess’s stdout and stderr concurrently and wait for it to exit.

Usage

Source

proc.collect_process(proc, *, stderr_tee=None)

Parameters

proc: asyncio.subprocess.Process: A process created with stderr piped and stdout either piped or redirected to a file. A file-backed stdout (a None pipe) is not drained here and comes back empty for the caller to read from the file.
stderr_tee: Callable[[bytes], None] | None = None: Callback invoked with each stderr chunk as it arrives.

Returns

tuple[bytes, bytes, int]: A (stdout, stderr, returncode) tuple.

proc.map_concurrent()

Map an async function over items with bounded concurrency.

Usage

Source

proc.map_concurrent(items, fn, *, limit, on_done=None)

Parameters

items: Sequence[T]: The inputs to process.
fn: Callable[[T], Awaitable[R]]: Async function applied to each item.
limit: int: Maximum number of in-flight calls.
on_done: Callable[[int], None] | None = None: Progress callback invoked with 1 as each item completes.

Returns

list[R]: The results, in input order.

proc.RunResult

The raw outcome of a CLI invocation.

Usage

Source

proc.RunResult(stdout, stderr, returncode)

Attributes

stdout: str: The decoded stdout.
stderr: str: The decoded stderr.
returncode: int: The process exit code.