plesty.lib.experiment.preflight

Build a rig, check it, and ask the operator when a device is not there.

Every experiment starts the same way: connect the device servers, make sure each one is the device it is supposed to be, and only then run. When a server is down or an address points at the wrong server, the operator must learn it at once — with the device, its address and the variable that set it — and decide: retry after fixing it, abort, or (for a sub-device the experiment can do without) continue without it. connect_rig() is that start, for any composite:

rig, skipped = connect_rig(
    lambda skip: PolPlRig(with_powermeter="pm" not in skip),
    optional={"pm"},
)

Non-interactive processes (no terminal on stdin) do not wait for an answer: the diagnosis is logged and RigNotReadyError is raised.

Exceptions

RigNotReadyError

The rig failed its preflight and the operator did not (or could not) recover it.

Functions

connect_rig(, ask, str]] = None, env_prefix, out, ...)

Build the rig, run its preflight, and ask the operator on a failure.

Module Contents

exception plesty.lib.experiment.preflight.RigNotReadyError(problems: dict[str, str], message: str)

Bases: RuntimeError

The rig failed its preflight and the operator did not (or could not) recover it.

Variables:

problems – Sub-device name → one-line problem.

Parameters:

  • problems (dict[str, str])

  • message (str)

Keep the per-device problems next to the message.

problems
plesty.lib.experiment.preflight.connect_rig(build: collections.abc.Callable[[frozenset[str]], plesty.lib.device.composite_device.CompositeDevice], *, optional: collections.abc.Iterable[str] = (), ask: collections.abc.Callable[[str], str] | None = None, env_prefix: str | None = None, out: collections.abc.Callable[[str], None] = print) → tuple[plesty.lib.device.composite_device.CompositeDevice, frozenset[str]]

Build the rig, run its preflight, and ask the operator on a failure.

Parameters:

  • build (collections.abc.Callable[[frozenset[str]], plesty.lib.device.composite_device.CompositeDevice]) – Factory building the composite without the given (optional) sub-devices; called again on every retry, so an edited .env or a freshly started server is picked up.

  • optional (collections.abc.Iterable[str]) – Sub-devices the experiment can run without; when only these fail, the operator may choose to continue without them.

  • ask (Optional[collections.abc.Callable[[str], str]]) – Reads the operator’s answer to a prompt. Defaults to input when stdin is a terminal, else to no prompt at all (the diagnosis is logged and RigNotReadyError raised).

  • env_prefix (Optional[str]) – Deployment prefix of the <NAME>_ADDRESS variables, for the diagnosis.

  • out (collections.abc.Callable[[str], None]) – Where the diagnosis and the prompt go (print).

Returns:

The ready composite and the set of optional sub-devices skipped.

Raises:

RigNotReadyError – If the operator aborts, or nobody can be asked.

Return type:

tuple[plesty.lib.device.composite_device.CompositeDevice, frozenset[str]]