benchmesh 0.1.0__py3-none-any.whl

benchmesh/__init__.py

@@ -0,0 +1,53 @@
+"""Python client for BenchMesh, one cockpit for lab instruments.
+
+>>> import benchmesh
+>>> bench = benchmesh.connect()             # the BenchMesh app on this computer
+>>> psu = bench["tenma-72-2540"]
+>>> psu.set("voltage", 5.0)
+>>> psu.read("VOUT")
+4.94
+
+See https://benchmesh.online
+"""
+
+from ._version import __version__
+from .bench import Bench, connect
+from .errors import (
+    AuthenticationError,
+    BadRequest,
+    BenchMeshError,
+    FingerprintMismatch,
+    InstrumentError,
+    InstrumentUnavailable,
+    NotFound,
+    Refused,
+    ServerNotRunning,
+    TLSError,
+)
+from .flows import Flow, RunStatus
+from .instrument import Instrument, Operation
+from .recordings import Recording, Series
+from .signals import Signal
+
+__all__ = [
+    "AuthenticationError",
+    "BadRequest",
+    "Bench",
+    "BenchMeshError",
+    "FingerprintMismatch",
+    "Flow",
+    "Instrument",
+    "InstrumentError",
+    "InstrumentUnavailable",
+    "NotFound",
+    "Operation",
+    "Recording",
+    "Refused",
+    "RunStatus",
+    "Series",
+    "ServerNotRunning",
+    "Signal",
+    "TLSError",
+    "__version__",
+    "connect",
+]

benchmesh/_validate.py

@@ -0,0 +1,42 @@
+"""Argument checks done before anything is sent."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+#: The instrument classes the BenchMesh bench knows (other three-letter classes are allowed).
+KNOWN_CLASSES = ("PSU", "DMM", "ELL", "AWG", "OSC", "LCR", "SAL")
+
+_CLASS = re.compile(r"^[A-Z]{3}$")
+
+
+def check_class(cls: Any) -> str:
+    """``"psu"`` -> ``"PSU"``; anything but three letters raises ``ValueError``."""
+    if not isinstance(cls, str):
+        raise TypeError(f"class must be a str such as 'PSU', not {type(cls).__name__}")
+    c = cls.strip().upper()
+    if not _CLASS.match(c):
+        raise ValueError(
+            f"invalid instrument class {cls!r}: three letters such as {', '.join(KNOWN_CLASSES)}"
+        )
+    return c
+
+
+def check_channel(ch: Any) -> int:
+    """Channel number 1-9."""
+    if isinstance(ch, bool) or not isinstance(ch, int):
+        raise TypeError(f"channel must be an int 1-9, not {type(ch).__name__}")
+    if not 1 <= ch <= 9:
+        raise ValueError(f"channel must be 1-9, not {ch}")
+    return ch
+
+
+def check_name(kind: str, name: Any) -> str:
+    """A non-empty identifier (device id, operation, status field)."""
+    if not isinstance(name, str):
+        raise TypeError(f"{kind} must be a str, not {type(name).__name__}")
+    n = name.strip()
+    if not n or "/" in n:
+        raise ValueError(f"invalid {kind} {name!r}")
+    return n

benchmesh/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

benchmesh/bench.py

@@ -0,0 +1,203 @@
+"""The bench: entry point to everything the server offers."""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Callable, Dict, Iterator, List, Mapping, Optional, Tuple, Union
+
+from . import flows as _flows
+from ._validate import check_class, check_name
+from .errors import BenchMeshError, NotFound
+from .flows import Flow, RunStatus
+from .instrument import Instrument
+from .recordings import Recording
+from .signals import SignalSpec, to_signals
+from .transport import DEFAULT_URL, Transport
+from .watch import watch as _watch
+
+
+class Bench:
+    """A connection to one BenchMesh server. Create it with :func:`benchmesh.connect`."""
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    @property
+    def url(self) -> str:
+        return self._t.url
+
+    @property
+    def transport(self) -> Transport:
+        return self._t
+
+    def __repr__(self) -> str:
+        return f"<Bench {self.url}>"
+
+    def __enter__(self) -> Bench:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Sign out of remote access (nothing to do on this computer)."""
+        self._t.logout()
+
+    def version(self) -> Dict[str, Any]:
+        """The server's version, e.g. ``{"version": "0.1.11", ...}``."""
+        return self._t.get("/version")
+
+    # ---- instruments ---------------------------------------------------------------
+
+    def instruments(self, cls: Optional[str] = None) -> List[Instrument]:
+        """Configured instruments, optionally only those of one class (``"PSU"``, ``"DMM"`` ...)."""
+        if cls is None:
+            data = self._t.get("/instruments")
+        else:
+            try:
+                data = self._t.get(f"/instruments/{check_class(cls)}")
+            except NotFound:
+                return []  # no instrument of that class
+        return [Instrument.from_json(d, self._t) for d in data or [] if isinstance(d, dict)]
+
+    def instrument(self, id: str) -> Instrument:
+        """The instrument with this config id, e.g. ``"tenma-72-2540"``."""
+        id = check_name("instrument id", id)
+        found = self.instruments()
+        for inst in found:
+            if inst.id == id:
+                return inst
+        raise NotFound(f"no instrument {id!r}; configured: {[i.id for i in found]}")
+
+    def __getitem__(self, id: str) -> Instrument:
+        return self.instrument(id)
+
+    def watch(
+        self,
+        signals: Mapping[str, SignalSpec],
+        interval: float = 0.5,
+        duration: Optional[float] = None,
+    ) -> Iterator[Tuple[float, Dict[str, Any]]]:
+        """Yield ``(time_s, {label: value})`` whenever a watched reading is updated.
+
+        ``signals``: ``{"v": ("owon-xdm1241", "DMM", "MEAS"), "i": ("owon-oel1515", "ELL", "IIN")}``
+        (a fourth tuple item is the channel).
+        """
+        return _watch(self._t, signals, interval, duration)
+
+    # ---- recordings ------------------------------------------------------------------
+
+    def recordings(self) -> List[Recording]:
+        """All recordings, newest first."""
+        return [
+            Recording.from_json(d, self._t) for d in self._t.get("/recordings") or [] if isinstance(d, dict)
+        ]
+
+    def recording(self, id: int) -> Recording:
+        if isinstance(id, bool) or not isinstance(id, int):
+            raise TypeError("recording id must be an int")
+        return Recording.from_json(self._t.get(f"/recordings/{id}"), self._t)
+
+    def record(
+        self,
+        name: str,
+        signals: Mapping[str, SignalSpec],
+        interval_s: int = 1,
+        description: Optional[str] = None,
+    ) -> Recording:
+        """Start a recording of ``signals`` (``{label: (device_id, class, field[, channel])}``).
+
+        The server samples every ``interval_s`` whole seconds (1-3600). Use the result as a
+        context manager to stop it at the end of the block.
+        """
+        if not isinstance(name, str) or not name.strip() or len(name.strip()) > 100:
+            raise ValueError("name must be 1-100 characters")
+        if isinstance(interval_s, bool) or not isinstance(interval_s, int) or not 1 <= interval_s <= 3600:
+            raise ValueError("interval_s must be an int 1-3600")
+        sig = to_signals(signals)
+        body: Dict[str, Any] = {"name": name.strip(), "interval_s": interval_s}
+        if description is not None:
+            body["description"] = str(description)
+        rec = Recording.from_json(self._t.post("/recordings", body), self._t)
+        try:
+            for label, s in sig.items():
+                rec.add(label, s)
+        except BaseException:
+            # do not leave a half-made recording behind
+            try:
+                rec.stop()
+                rec.delete()
+            except BenchMeshError:
+                pass
+            raise
+        return rec
+
+    # ---- automation --------------------------------------------------------------------
+
+    def flows(self) -> List[Flow]:
+        """Saved flows."""
+        return _flows.list_flows(self._t)
+
+    def flow(self, id: str) -> Dict[str, Any]:
+        """A saved flow document (``benchmesh.flow/v1``)."""
+        return _flows.get_flow(self._t, check_name("flow id", id))
+
+    def run_flow(
+        self,
+        flow: Union[str, Mapping[str, Any]],
+        params: Optional[Mapping[str, Any]] = None,
+        *,
+        arm: bool = False,
+        wait: bool = True,
+        timeout: Optional[float] = None,
+        on_event: Optional[Callable[[Dict[str, Any]], None]] = None,
+    ) -> RunStatus:
+        """Run a saved flow (by id) or a flow document.
+
+        ``arm=True`` is required for flows that can switch outputs on. With ``wait`` it
+        returns when the run has ended (check ``.ok``); ``timeout`` aborts it; Ctrl-C aborts
+        it too. ``on_event`` gets every log event as it arrives.
+        """
+        return _flows.run_flow(
+            self._t, flow, params=params, arm=arm, wait=wait, timeout=timeout, on_event=on_event
+        )
+
+    def run_status(self) -> RunStatus:
+        """The current or last run."""
+        return _flows.run_status(self._t)
+
+    def abort_run(self) -> None:
+        """Abort the running flow (its cleanup still runs)."""
+        _flows.abort_run(self._t)
+
+    def continue_run(self) -> None:
+        """Continue a run waiting at a ``prompt`` step."""
+        _flows.continue_run(self._t)
+
+
+def connect(
+    url: Optional[str] = None,
+    *,
+    password: Optional[str] = None,
+    fingerprint: Optional[str] = None,
+    timeout: float = 30.0,
+) -> Bench:
+    """Connect to a BenchMesh server and check that it answers.
+
+    ``url``: default ``$BENCHMESH_URL`` or ``http://127.0.0.1:57666`` (the app on this
+    computer). For remote access use ``https://<address>:57667`` with the ``password`` and
+    the certificate ``fingerprint`` shown in the app (or ``$BENCHMESH_PASSWORD`` /
+    ``$BENCHMESH_FINGERPRINT``).
+    """
+    url = url or os.environ.get("BENCHMESH_URL") or DEFAULT_URL
+    if url.strip().lower().startswith("https://"):
+        password = password if password is not None else os.environ.get("BENCHMESH_PASSWORD") or None
+        fingerprint = (
+            fingerprint if fingerprint is not None else os.environ.get("BENCHMESH_FINGERPRINT") or None
+        )
+    t = Transport(url, password=password, fingerprint=fingerprint, timeout=timeout)
+    if password is not None:
+        t.login()
+    bench = Bench(t)
+    bench.version()
+    return bench

benchmesh/errors.py

@@ -0,0 +1,75 @@
+"""Exceptions raised by the client.
+
+Every error from the server is a :class:`BenchMeshError` with the HTTP ``status`` and the
+server's ``detail`` message. Wrong arguments found before anything is sent raise the standard
+``ValueError`` / ``TypeError``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class BenchMeshError(Exception):
+    """An error reported by (or while talking to) the BenchMesh server."""
+
+    def __init__(self, detail: str, status: Optional[int] = None, body: Any = None) -> None:
+        super().__init__(detail if status is None else f"{status}: {detail}")
+        self.detail = detail
+        self.status = status
+        #: The decoded JSON error body (may carry more keys, e.g. ``energizes`` or ``issues``).
+        self.body = body
+
+
+class ServerNotRunning(BenchMeshError):
+    """No BenchMesh server answers at the address."""
+
+
+class TLSError(BenchMeshError):
+    """The HTTPS connection to remote access could not be trusted."""
+
+
+class FingerprintMismatch(TLSError):
+    """The server's certificate does not match the pinned fingerprint."""
+
+
+class AuthenticationError(BenchMeshError):
+    """Sign-in failed or the session is not allowed to do this (401 / 403)."""
+
+
+class BadRequest(BenchMeshError):
+    """The server refused the arguments (400 / 422), e.g. a value outside the setter's range."""
+
+
+class NotFound(BenchMeshError):
+    """Unknown instrument, class, channel, operation, field, recording or flow (404)."""
+
+
+class Refused(BenchMeshError):
+    """A precondition is not met (409): parked instrument, busy run, flow needs ``arm``, ..."""
+
+
+class InstrumentError(BenchMeshError):
+    """The instrument answered something the definition could not parse (502)."""
+
+
+class InstrumentUnavailable(BenchMeshError):
+    """The instrument is not connected or did not answer in time (503 / 504)."""
+
+
+_BY_STATUS = {
+    400: BadRequest,
+    401: AuthenticationError,
+    403: AuthenticationError,
+    404: NotFound,
+    409: Refused,
+    422: BadRequest,
+    502: InstrumentError,
+    503: InstrumentUnavailable,
+    504: InstrumentUnavailable,
+}
+
+
+def error_for(status: int, detail: str, body: Any = None) -> BenchMeshError:
+    """The exception for an HTTP error status."""
+    return _BY_STATUS.get(status, BenchMeshError)(detail, status, body)

benchmesh/flows.py

@@ -0,0 +1,173 @@
+"""Automation flows: list saved flows, run one, follow the run until it ends.
+
+The server runs one flow at a time. A flow that can switch outputs on needs ``arm=True``;
+without it the server refuses the run (:class:`~benchmesh.errors.Refused`, the operations
+are in ``error.body["energizes"]``). A failed or aborted run switches off what it switched on.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Mapping, Optional, Union
+
+from .errors import Refused
+from .transport import Transport, segment
+
+ACTIVE_STATES = ("running", "waiting", "cleanup")
+
+
+@dataclass(frozen=True)
+class Flow:
+    """A saved flow (``GET /automation/flows``)."""
+
+    id: str
+    name: str
+    description: str = ""
+    updated_at: Optional[int] = None
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> Flow:
+        return cls(
+            id=str(d.get("id", "")),
+            name=str(d.get("name") or d.get("id") or ""),
+            description=str(d.get("description") or ""),
+            updated_at=d.get("updated_at"),
+        )
+
+
+@dataclass
+class RunStatus:
+    """State of the current (or last) run."""
+
+    id: Optional[int]
+    #: ``idle``, ``running``, ``waiting`` (at a prompt), ``cleanup``, ``finished``, ``failed``, ``aborted``.
+    state: str
+    flow_name: str = ""
+    error: Optional[str] = None
+    prompt: Optional[str] = None
+    vars: Dict[str, Any] = field(default_factory=dict)
+    recording_id: Optional[int] = None
+    #: Log events ``{"seq", "t", "level", "path", "msg"}``.
+    events: List[Dict[str, Any]] = field(default_factory=list)
+    raw: Dict[str, Any] = field(default_factory=dict, repr=False)
+
+    @property
+    def active(self) -> bool:
+        return self.state in ACTIVE_STATES
+
+    @property
+    def ok(self) -> bool:
+        """Finished successfully."""
+        return self.state == "finished"
+
+    @property
+    def last_seq(self) -> int:
+        return int(self.raw.get("last_seq") or 0)
+
+    @classmethod
+    def from_json(cls, d: Mapping[str, Any]) -> RunStatus:
+        flow = d.get("flow") if isinstance(d.get("flow"), dict) else {}
+        return cls(
+            id=d.get("id"),
+            state=str(d.get("state") or "idle"),
+            flow_name=str(flow.get("name") or ""),
+            error=d.get("error"),
+            prompt=d.get("prompt"),
+            vars=dict(d.get("vars") or {}),
+            recording_id=d.get("recording_id"),
+            events=[e for e in d.get("events") or [] if isinstance(e, dict)],
+            raw=dict(d),
+        )
+
+
+def list_flows(t: Transport) -> List[Flow]:
+    return [Flow.from_json(d) for d in t.get("/automation/flows") or [] if isinstance(d, dict)]
+
+
+def get_flow(t: Transport, flow_id: str) -> Dict[str, Any]:
+    return t.get(f"/automation/flows/{segment(flow_id)}")
+
+
+def run_status(t: Transport, after: int = 0) -> RunStatus:
+    return RunStatus.from_json(t.get("/automation/run", after=after))
+
+
+def abort_run(t: Transport) -> None:
+    t.post("/automation/run/abort")
+
+
+def continue_run(t: Transport) -> None:
+    t.post("/automation/run/continue")
+
+
+def run_flow(
+    t: Transport,
+    flow: Union[str, Mapping[str, Any]],
+    *,
+    params: Optional[Mapping[str, Any]] = None,
+    arm: bool = False,
+    wait: bool = True,
+    timeout: Optional[float] = None,
+    poll: float = 0.25,
+    on_event: Optional[Callable[[Dict[str, Any]], None]] = None,
+) -> RunStatus:
+    """Start a run and (with ``wait``) follow it to its end; returns the final status."""
+    if isinstance(flow, str):
+        if not flow.strip():
+            raise ValueError("flow id must not be empty")
+        body: Dict[str, Any] = {"flow_id": flow}
+    elif isinstance(flow, Mapping):
+        body = {"flow": dict(flow)}
+    else:
+        raise TypeError("flow must be a saved flow id (str) or a flow document (dict)")
+    if params is not None:
+        if not isinstance(params, Mapping):
+            raise TypeError("params must be a dict")
+        body["params"] = dict(params)
+    if not isinstance(arm, bool):
+        raise TypeError("arm must be True or False")
+    if arm:
+        body["arm"] = True
+    if timeout is not None and timeout <= 0:
+        raise ValueError("timeout must be positive")
+    if poll <= 0:
+        raise ValueError("poll must be positive")
+
+    status = RunStatus.from_json(t.post("/automation/run", body))
+    if not wait:
+        return status
+    run_id, events, seq = status.id, list(status.events), status.last_seq
+    for e in events:
+        _emit(on_event, e)
+    deadline = None if timeout is None else time.monotonic() + timeout
+    try:
+        while status.active:
+            if deadline is not None and time.monotonic() > deadline:
+                _abort_quietly(t)
+                raise TimeoutError(f"the run did not end within {timeout} s: it was aborted (cleanup runs)")
+            time.sleep(poll)
+            fresh = run_status(t, after=seq)
+            if fresh.id != run_id:
+                break  # another run replaced ours: ours has ended
+            for e in fresh.events:
+                events.append(e)
+                _emit(on_event, e)
+            seq = max(seq, fresh.last_seq)
+            status = fresh
+    except KeyboardInterrupt:
+        _abort_quietly(t)
+        raise
+    status.events = events
+    return status
+
+
+def _emit(cb: Optional[Callable[[Dict[str, Any]], None]], e: Dict[str, Any]) -> None:
+    if cb is not None:
+        cb(e)
+
+
+def _abort_quietly(t: Transport) -> None:
+    with contextlib.suppress(Refused):  # it ended in the meantime
+        abort_run(t)