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	Describe one event delivered to a checker.
Diagnostic	Describe a structured observation made while supervising a program.
FollowSource	Describe a file to follow while the child process is running.
CheckerSpec	Describe 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

Describe one event delivered to a checker.

Parameters:

• event – Identify the event kind.

• source – Identify the stream or process that produced it.

• line – Preserve the event line when one exists.

• timestamp – Preserve the event timestamp, or generate one when absent.

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

source: str

line: str | None = None

timestamp: str = ''

as_mapping()

Return the checker protocol mapping for this event.

Returns:

The serialized event mapping.

Return type:

dict[str, object]

class httk.workflow.supervision.Diagnostic

Describe a structured observation made while supervising a program.

Parameters:

• code – Name the stable diagnostic code.

• severity – Classify the diagnostic severity.

• summary – Summarize the observation.

• source – Identify the source that produced it.

• evidence – Preserve supporting evidence when present.

• stop – Request termination of the supervised command.

code: str

severity: DiagnosticSeverity

summary: str

source: str

evidence: str | None = None

stop: bool = False

as_mapping()

Return the serialized diagnostic mapping.

Returns:

The diagnostic mapping.

Return type:

dict[str, object]

class httk.workflow.supervision.FollowSource

Describe a file to follow while the child process is running.

Parameters:

• path – Locate the file to follow.

• name – Identify the source in emitted events.

• inactivity_timeout – Stop when no data arrives for this interval.

path: pathlib.Path

name: str | None = None

inactivity_timeout: float | None = None

class httk.workflow.supervision.CheckerSpec

Describe a versioned executable checker.

Parameters:

• argv – Supply the checker command and arguments.

• required – Require the checker to remain available for the run.

• sources – Select files the checker follows.

argv: tuple[str, Ellipsis]

required: bool = True

sources: tuple[FollowSource, Ellipsis] = ()

classmethod from_mapping(value)

Validate and build a checker specification from a mapping.

Parameters:

value (collections.abc.Mapping[str, object]) – Supply the serialized checker specification.

Returns:

The validated checker specification.

Raises:

ValueError – If the mapping has an invalid checker format or source.

Return type:

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.

Parameters:

• argv – Preserve the executed command.

• started_at – Record when execution began.

• finished_at – Record when execution ended.

• returncode – Record the process return code.

• termination – Record why execution ended.

• stdout – Preserve the captured stdout tail.

• stderr – Preserve the captured stderr tail.

• diagnostics – Preserve emitted diagnostics.

• stdout_path – Locate the authoritative stdout file when configured.

• stderr_path – Locate the authoritative stderr file when configured.

• stdout_bytes – Count all stdout bytes produced.

• stderr_bytes – Count all stderr bytes produced.

• stdout_truncated – Indicate that stdout was truncated.

• stderr_truncated – Indicate that stderr was truncated.

• dropped_diagnostics – Count diagnostics dropped from the middle.

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

Report whether the process ended because of a timeout.

Returns:

Whether the termination reason starts with timeout.

Return type:

bool

as_mapping()

Return the serialized process report.

Returns:

The report mapping.

Return type:

dict[str, object]

write(path)

Write the serialized report atomically.

Parameters:

path (str | os.PathLike[str]) – Locate the report file to write.

Returns:

The report path.

Return type:

pathlib.Path

class httk.workflow.supervision.ProcessSupervisor(*, monitors=(), checkers=(), follow=())

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.

Parameters:

• monitors (collections.abc.Sequence[EventMonitor]) – Supply in-process event monitors.

• checkers (collections.abc.Sequence[CheckerSpec]) – Supply executable checker specifications.

• follow (collections.abc.Sequence[FollowSource]) – Supply files to follow during the run.

monitors = ()

checker_specs = ()

follow = ()

run(argv, *, timeout=None, cwd=None, environment=None, termination_grace=10.0, stdout_path=None, stderr_path=None, tick_interval=DEFAULT_TICK_INTERVAL, follow_interval=DEFAULT_FOLLOW_INTERVAL, capture_limit=DEFAULT_CAPTURE_LIMIT, tail_limit=DEFAULT_TAIL_LIMIT, diagnostic_limit=DEFAULT_DIAGNOSTIC_LIMIT)

Run one command to completion and return its structured report.

Parameters:

• argv (collections.abc.Sequence[str]) – Supply the command and arguments.

• timeout (float | None) – Stop the command after this interval.

• cwd (str | os.PathLike[str] | None) – Select the command working directory.

• environment (collections.abc.Mapping[str, str] | None) – Supply the command environment.

• termination_grace (float) – Wait this long after requesting termination.

• stdout_path (str | os.PathLike[str] | None) – Write stdout to this authoritative file.

• stderr_path (str | os.PathLike[str] | None) – Write stderr to this authoritative file.

• tick_interval (float) – Set the interval between tick events.

• follow_interval (float) – Set the interval between followed-file polls.

• capture_limit (int) – Bound retained output without an output file.

• tail_limit (int) – Bound retained output with an output file.

• diagnostic_limit (int) – Bound retained diagnostics.

Returns:

The structured process report.

Raises:

ValueError – If command or supervision limits are invalid.

Return type:

ProcessReport