Errors

UnknownProgramError

Bases: LookupError

Raised when a program is not present in the catalogue allowlist.

class ForbiddenProgramError(
    program: Program,
    *,
    restricted_state: bool,
) -> None

Bases: ContextError, PermissionError

Raised when attempting to run a program not in the current allowlist.

class TimeoutExpired(
    *,
    cmd: cabc.Sequence[str] | object,
    timeout: float,
    output: str | bytes | None = None,
    stderr: str | bytes | None = None,
) -> None

Bases: TimeoutError

Raised when command execution exceeds the configured timeout.

stdout: str | bytes | None

StdinSourceError

Bases: Exception

Raised when a streaming stdin producer or its encoder fails.

A caller who supplies a StdinStream sees failures from three sources wrapped in this type: the producer raising while being pulled, the producer yielding a value that is neither str nor bytes, and the incremental encoder rejecting a str chunk. The original exception is chained as __cause__, so the caller can still inspect it.

The child is terminated before this is raised, and the run's stdin writer and pipe are finalized, so catching this type is enough to know that no writer outlives the run. Cancellation is *not* wrapped: an asyncio.CancelledError propagates unchanged, because it is a control-flow signal rather than a source failure.

class SignalAfterExitError(
    exit_code: int,
    pid: int | None = None,
) -> None

Bases: ProcessLookupError

Raised when a signal is requested for a child that has already exited.

A caller coordinating several signals cannot avoid racing the child's own exit, so this is an ordinary outcome rather than a misuse: the handle reports it with the exit code it recorded, letting the caller decide whether the command's ending already satisfies them.

Subclasses ProcessLookupError because that is exactly what the operating system reports once the child is gone, and a caller that already tolerates a lost process keeps working when the handle names the condition.

class UnsupportedSignalError(
    signal_number: int,
    platform_name: str,
) -> None

Bases: RuntimeError

Raised when the platform cannot deliver a caller-named signal.

Distinct from SignalAfterExitError because the remedy differs: no retry can help here, and a caller that needs to stop a child on such a platform has to reach for the handle's terminate or kill operations, which use the platform's own signals.