httk.workflow.supervision

Structured, argv-only process supervision for native runners.

Every event is dispatched to the in-process monitors and to the executable checkers under one supervisor-wide lock, so a monitor is never entered concurrently with itself or with another monitor, and a checker never receives an interleaved line on its stdin. A monitor therefore does not have to be thread-safe, but it must return quickly: it delays the whole event stream.

Attributes

DEFAULT_TICK_INTERVAL	Seconds between the tick events delivered to monitors and checkers.
DEFAULT_FOLLOW_INTERVAL	Seconds between polls of a followed file that produced no new data.
DEFAULT_CAPTURE_LIMIT	Bytes of a stream retained in the report when no output path is given.
DEFAULT_TAIL_LIMIT	Bytes of a stream retained in the report when an output path is given.
DEFAULT_DIAGNOSTIC_LIMIT	Diagnostics retained in one report before the middle is dropped.

Classes

SourceEvent	One event delivered to an in-process or executable checker.
Diagnostic	A structured observation made while supervising a program.
FollowSource	A file to follow while the child process is running.
CheckerSpec	A versioned executable checker.
ProcessReport	The complete result of one supervised command.
ProcessSupervisor	Run one command, stream its output, and terminate its process group safely.

Module Contents

httk.workflow.supervision.DEFAULT_TICK_INTERVAL = 1.0

Seconds between the tick events delivered to monitors and checkers.

httk.workflow.supervision.DEFAULT_FOLLOW_INTERVAL = 0.25

Seconds between polls of a followed file that produced no new data.

httk.workflow.supervision.DEFAULT_CAPTURE_LIMIT = 4194304

Bytes of a stream retained in the report when no output path is given.

httk.workflow.supervision.DEFAULT_TAIL_LIMIT = 65536

Bytes of a stream retained in the report when an output path is given.

httk.workflow.supervision.DEFAULT_DIAGNOSTIC_LIMIT = 512

Diagnostics retained in one report before the middle is dropped.

class httk.workflow.supervision.SourceEvent

One event delivered to an in-process or executable checker.

event: Literal['start', 'line', 'tick', 'source-eof', 'process-exit']

source: str

line: str | None = None

timestamp: str = ''

as_mapping() → dict[str, object]

class httk.workflow.supervision.Diagnostic

A structured observation made while supervising a program.

code: str

severity: DiagnosticSeverity

summary: str

source: str

evidence: str | None = None

stop: bool = False

as_mapping() → dict[str, object]

class httk.workflow.supervision.FollowSource

A file to follow while the child process is running.

path: pathlib.Path

name: str | None = None

inactivity_timeout: float | None = None

class httk.workflow.supervision.CheckerSpec

A versioned executable checker.

argv: tuple[str, Ellipsis]

required: bool = True

sources: tuple[FollowSource, Ellipsis] = ()

classmethod from_mapping(value: collections.abc.Mapping[str, object]) → CheckerSpec

class httk.workflow.supervision.ProcessReport

The complete result of one supervised command.

stdout and stderr are bounded: when an output path was given they hold at most the run’s tail limit and the file named by stdout_path or stderr_path is authoritative; otherwise they hold at most the run’s capture limit. stdout_bytes and stderr_bytes always count every byte the program produced, and stdout_truncated and stderr_truncated say whether anything was dropped from the retained tail.

argv: tuple[str, Ellipsis]

started_at: str

finished_at: str

returncode: int

termination: str

stdout: bytes

stderr: bytes

diagnostics: tuple[Diagnostic, Ellipsis]

stdout_path: str | None = None

stderr_path: str | None = None

stdout_bytes: int = 0

stderr_bytes: int = 0

stdout_truncated: bool = False

stderr_truncated: bool = False

dropped_diagnostics: int = 0

property timed_out: bool

as_mapping() → dict[str, object]

write(path: str | os.PathLike[str]) → pathlib.Path

class httk.workflow.supervision.ProcessSupervisor(*, monitors: collections.abc.Sequence[EventMonitor] = (), checkers: collections.abc.Sequence[CheckerSpec] = (), follow: collections.abc.Sequence[FollowSource] = ())

Run one command, stream its output, and terminate its process group safely.

Monitors and checkers observe the same event stream under one lock, so an in-process monitor does not have to be thread-safe. Whatever happens during a run - including an exception raised by the caller’s monitor - the signal handlers are restored, the child’s process group is terminated and reaped, the reader threads are joined, and the output handles are closed before run() returns or propagates.

monitors = ()

checker_specs = ()

follow = ()

run(argv: collections.abc.Sequence[str], *, timeout: float | None = None, cwd: str | os.PathLike[str] | None = None, environment: collections.abc.Mapping[str, str] | None = None, termination_grace: float = 10.0, stdout_path: str | os.PathLike[str] | None = None, stderr_path: str | os.PathLike[str] | None = None, tick_interval: float = DEFAULT_TICK_INTERVAL, follow_interval: float = DEFAULT_FOLLOW_INTERVAL, capture_limit: int = DEFAULT_CAPTURE_LIMIT, tail_limit: int = DEFAULT_TAIL_LIMIT, diagnostic_limit: int = DEFAULT_DIAGNOSTIC_LIMIT) → ProcessReport

Run one command to completion and return its structured report.