Capture API¶

The capture module executes commands and captures their output.

Overview¶

from bugsafe.capture.runner import run_command, CaptureConfig

# Run with default settings
result = run_command(["python", "script.py"])
print(result.exit_code)
print(result.stdout)

# Run with custom config
config = CaptureConfig(timeout=60, max_output_bytes=1_000_000)
result = run_command(["python", "script.py"], config)

CaptureConfig¶

Configuration for command capture.

`bugsafe.capture.runner.CaptureConfig` `dataclass` ¶

Configuration for command capture.

Attributes:

Name	Type	Description
`timeout`	`int`	Maximum execution time in seconds.
`max_output_bytes`	`int`	Maximum bytes per stream (stdout/stderr).
`max_total_bytes`	`int`	Maximum total bytes for bundle.
`encoding`	`str`	Text encoding for output.
`encoding_errors`	`str`	How to handle encoding errors.
`preserve_ansi`	`bool`	Whether to preserve ANSI escape codes.
`strip_cr`	`bool`	Whether to normalize \r\n to \n.
`cwd`	`Path \| None`	Working directory for command execution.
`env_passthrough`	`frozenset[str]`	Environment variables to pass through.

CaptureResult¶

Result of command execution.

`bugsafe.capture.runner.CaptureResult` `dataclass` ¶

Result of command capture.

Attributes:

Name	Type	Description
`command`	`list[str]`	The executed command.
`stdout`	`str`	Captured standard output.
`stderr`	`str`	Captured standard error.
`exit_code`	`int`	Process exit code (-1 for errors, -2 for timeout).
`duration_ms`	`int`	Execution duration in milliseconds.
`signal_num`	`int \| None`	Signal number if process was killed.
`timed_out`	`bool`	Whether the process timed out.
`truncated_stdout`	`bool`	Whether stdout was truncated.
`truncated_stderr`	`bool`	Whether stderr was truncated.
`encoding_errors_count`	`int`	Number of encoding errors encountered.
`is_binary_stdout`	`bool`	Whether stdout is binary (base64 encoded).
`is_binary_stderr`	`bool`	Whether stderr is binary (base64 encoded).
`error_message`	`str \| None`	Error message if command failed to start.

run_command¶

Execute a command and capture output.

`bugsafe.capture.runner.run_command(cmd, config=None)` ¶

Execute a command and capture its output.

Parameters:

Name	Type	Description	Default
`cmd`	`Sequence[str]`	Command and arguments to execute.	required
`config`	`CaptureConfig \| None`	Capture configuration options.	`None`

Returns:

Type	Description
`CaptureResult`	CaptureResult with captured output and metadata.

Raises:

Type	Description
`KeyboardInterrupt`	If interrupted by user (after cleanup).