benchloom 0.1.3__py3-none-any.whl

benchloom/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Friedrich-Christer Rosenthal
+"""Benchloom: open lab automation."""
+
+from .plugin import CommandError, Device, Param, command
+from .scpi import ScpiDevice
+from .transports import RawSimTransport, SimTransport, Transport
+
+__version__ = "0.1.3"
+HOMEPAGE = "https://github.com/criscrafter/benchloom"
+
+# The notices an interactive program under the AGPL shows: copyright, no warranty,
+# the licence. The app's About dialog and `benchloom --version` print them.
+NOTICE = f"""\
+Benchloom {__version__}
+Copyright (C) 2026 Friedrich-Christer Rosenthal
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, either version 3 of the License, or (at your option) any
+later version.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. You are responsible for operating connected equipment
+safely and for checking results. See the GNU Affero General Public License for
+details.
+
+Benchloom is developed with substantial assistance from AI tools. Every change
+is reviewed by the maintainer and checked by automated tests.
+
+Source code and licence: {HOMEPAGE}"""
+
+__all__ = [
+    "CommandError",
+    "Device",
+    "Param",
+    "RawSimTransport",
+    "ScpiDevice",
+    "SimTransport",
+    "Transport",
+    "command",
+]

benchloom/__main__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Friedrich-Christer Rosenthal
+from .cli import main
+
+raise SystemExit(main())

benchloom/cli.py

@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Friedrich-Christer Rosenthal
+"""Command line: ``benchloom gui | new | run | devices | describe | plugins | usbgpib``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import NOTICE
+from .engine import run_project
+from .plugin import PluginError, PluginRegistry
+from .project import ProjectError, create_project, templates
+
+
+def _new(args) -> int:
+    project = create_project(args.path, args.mode, args.template)
+    print(f"Created {project.mode} project in {project.path}")
+    print(f"Run it with: benchloom run {args.path}")
+    return 0
+
+
+def _run(args) -> int:
+    result = run_project(args.path, trust_plugins=args.trust_plugins)
+    print(f"\n{len(result.rows)} row(s) logged. Run saved to {result.path}")
+    return 0 if result.status == "ok" else 1
+
+
+def _devices(args) -> int:
+    # --project names the project on purpose, which is the permission to use its plugins
+    registry = PluginRegistry.default(Path(args.project) if args.project else None,
+                                      trust_project=True)
+    for plugin in registry.plugins.values():
+        print(f"{plugin.name} ({plugin.id} {plugin.version})")
+        for device in plugin.devices:
+            print(f"  {device.id:<18} {device.name}")
+    for error in registry.errors:
+        print(f"warning: {error}", file=sys.stderr)
+    return 0
+
+
+def _plugins(args) -> int:
+    from . import plugin_install
+    from .config import AppConfig
+    from .plugin import SOURCES
+
+    project = Path(args.project) if args.project else None
+    if args.action == "list":
+        registry = PluginRegistry.default(project, trust_project=True)
+        for info in registry.found:
+            status = registry.status(info)
+            mark = {"enabled": "on ", "disabled": "off", "replaced": "---"}[status]
+            print(f"{mark} {info.id:<12} {info.version:<8} "
+                  f"{SOURCES.get(info.source, info.source):<14} {info.path}")
+        for folder, error in registry.broken:
+            print(f"err {folder}: {error}")
+        return 0
+    if not args.target:
+        raise PluginError(f"'plugins {args.action}' needs a {'path' if args.action == 'install' else 'plugin id'}")
+    if args.action == "install":
+        print(plugin_install.TRUST_WARNING)
+        info = plugin_install.install(Path(args.target), replace=args.replace)
+        print(f"Installed {info.name} {info.version} ({info.id}) in {info.path}")
+        return 0
+    registry = PluginRegistry.default(project, trust_project=True)
+    matches = [info for info in registry.found if info.id == args.target]
+    if not matches:
+        raise PluginError(f"no plugin with id '{args.target}' (see: benchloom plugins)")
+    if args.action == "remove":
+        installed = [info for info in matches if plugin_install.is_removable(info)]
+        if not installed:
+            raise PluginError(f"'{args.target}' is not an installed plugin")
+        plugin_install.remove(installed[0])
+        print(f"Removed {installed[0].path}")
+        return 0
+    config = AppConfig.load()
+    config.set_enabled(args.target, args.action == "enable")
+    config.save()
+    print(f"Plugin '{args.target}' switched {'on' if args.action == 'enable' else 'off'}")
+    return 0
+
+
+def _describe(args) -> int:
+    registry = PluginRegistry.default(Path(args.project) if args.project else None,
+                                      trust_project=True)
+    spec = registry.device(args.device)
+    print(f"{spec.name} ({spec.id})")
+    if spec.description:
+        print(spec.description)
+    print(f"Connections: {', '.join(spec.transports) or 'any'}\n")
+    for info in spec.load_driver().commands().values():
+        params = []
+        for p in info.params:
+            text = p.name
+            if p.unit:
+                text += f" [{p.unit}]"
+            if p.min is not None or p.max is not None:
+                low = "" if p.min is None else f"{p.min:g}"
+                high = "" if p.max is None else f"{p.max:g}"
+                text += f" {low}..{high}"
+            params.append(text if p.required else f"[{text}]")
+        returns = ""
+        if info.returns not in ("nil", "any"):
+            returns = f" -> {info.returns}" + (f" [{info.unit}]" if info.unit else "")
+        print(f"  {info.name}({', '.join(params)}){returns}")
+        if info.doc:
+            print(f"      {info.doc}")
+    return 0
+
+
+def _usbgpib(args) -> int:
+    from .transports import TransportError, find_usbtmc, open_transport
+
+    if not args.commands:
+        found = find_usbtmc(0x03EB, 0x2065)
+        for _, _, serial in found:
+            print(f"usbgpib://{serial}" if serial else "usbgpib:// (serial number not readable)")
+        if not found:
+            print("no UsbGpib adapter found (it only appears while a powered instrument "
+                  "is connected to it)")
+        return 0
+    try:
+        transport = open_transport(f"usbgpib://{args.serial or ''}")
+    except TransportError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    try:
+        for text in args.commands:
+            reply = transport.adapter_command(text)
+            print(f"{text} -> {reply}" if reply is not None else f"{text}: sent")
+    finally:
+        transport.close()
+    return 0
+
+
+def _gui(args) -> int:
+    from .gui import main as gui_main
+
+    return gui_main(args.path)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="benchloom", description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter,
+                                     epilog="Benchloom comes with ABSOLUTELY NO WARRANTY; "
+                                            "see 'benchloom --version' for details.")
+    parser.add_argument("--version", action="version", version=NOTICE)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    new = sub.add_parser("new", help="create a project with a working example")
+    new.add_argument("path")
+    new.add_argument("--mode", choices=("lua", "visual"), default="lua")
+    new.add_argument("--template", choices=[t.id for t in templates()], default="example",
+                     help="what the project starts with: " + "; ".join(
+                         f"{t.id} = {t.title}" for t in templates()))
+    new.set_defaults(func=_new)
+
+    run = sub.add_parser("run", help="run a project's test")
+    run.add_argument("path", nargs="?", default=".")
+    run.add_argument("--trust-plugins", action="store_true",
+                     help="allow the project's own plugins folder (Python code) to load, "
+                          "now and in later runs")
+    run.set_defaults(func=_run)
+
+    devices = sub.add_parser("devices", help="list the device types plugins provide")
+    devices.add_argument("--project", help="also include this project's plugins folder")
+    devices.set_defaults(func=_devices)
+
+    describe = sub.add_parser("describe", help="show the commands of a device type")
+    describe.add_argument("device", help="device type, e.g. demo.psu")
+    describe.add_argument("--project", help="also include this project's plugins folder")
+    describe.set_defaults(func=_describe)
+
+    plugins = sub.add_parser(
+        "plugins", help="list, install, remove, or switch plugins on and off",
+        description="list: every plugin found (on, off, or --- when replaced by a plugin "
+                    "with the same id). install PATH: copy a plugin folder or .zip into "
+                    "the user plugin folder. remove/enable/disable ID.")
+    plugins.add_argument("action", nargs="?", default="list",
+                         choices=("list", "install", "remove", "enable", "disable"))
+    plugins.add_argument("target", nargs="?", help="a path for install, else a plugin id")
+    plugins.add_argument("--replace", action="store_true",
+                         help="install over a plugin with the same id")
+    plugins.add_argument("--project", help="also include this project's plugins folder")
+    plugins.set_defaults(func=_plugins)
+
+    usbgpib = sub.add_parser(
+        "usbgpib", help="list xyphro UsbGpib adapters, or send them their own '!' commands",
+        description="Without commands: list the adapters. With commands: send them to the "
+                    "adapter, e.g. benchloom usbgpib \"!autoid off\" for instruments that "
+                    "do not understand *IDN? (HP 3478A), or \"!ver?\".")
+    usbgpib.add_argument("commands", nargs="*")
+    usbgpib.add_argument("--serial", help="the adapter's serial number, if there are several")
+    usbgpib.set_defaults(func=_usbgpib)
+
+    gui = sub.add_parser("gui", help="open the desktop app")
+    gui.add_argument("path", nargs="?", help="project folder to open")
+    gui.set_defaults(func=_gui)
+
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except (ProjectError, PluginError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

benchloom/config.py

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Friedrich-Christer Rosenthal
+"""App-wide settings shared by the desktop app, the command line and test runs.
+
+Stored as JSON in ``~/.benchloom/config.json`` (or ``$BENCHLOOM_HOME/config.json``).
+Before the rename to Benchloom this was ``~/.patchbay``; that folder is still
+used while there is no ``~/.benchloom``.
+Only settings that a test run needs live here, such as which plugins are
+switched off; window layout and other desktop-only choices stay in Qt's own
+settings store.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+CONFIG_NAME = "config.json"
+
+
+def home_dir() -> Path:
+    """Benchloom's own folder: user plugins and config.json."""
+    override = os.environ.get("BENCHLOOM_HOME") or os.environ.get("PATCHBAY_HOME")
+    if override:
+        return Path(override)
+    home = Path.home() / ".benchloom"
+    legacy = Path.home() / ".patchbay"
+    return legacy if legacy.is_dir() and not home.exists() else home
+
+
+def user_plugin_dir() -> Path:
+    return home_dir() / "plugins"
+
+
+def _project_key(project_dir: str | Path) -> str:
+    """A project folder as it is compared and stored: absolute, in the system's spelling."""
+    return os.path.normcase(str(Path(project_dir).resolve()))
+
+
+@dataclass
+class AppConfig:
+    disabled_plugins: list[str] = field(default_factory=list)
+    plugin_paths: list[str] = field(default_factory=list)  # extra folders to load plugins from
+    # project folders whose own plugins/ folder may be loaded (the user said yes)
+    trusted_projects: list[str] = field(default_factory=list)
+    _other: dict = field(default_factory=dict, repr=False)  # keys from newer versions, kept
+
+    @classmethod
+    def load(cls) -> "AppConfig":
+        try:
+            data = json.loads((home_dir() / CONFIG_NAME).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            data = {}
+        if not isinstance(data, dict):
+            data = {}
+
+        def strings(key):
+            value = data.pop(key, [])
+            return [str(v) for v in value] if isinstance(value, list) else []
+
+        return cls(strings("disabled_plugins"), strings("plugin_paths"),
+                   strings("trusted_projects"), data)
+
+    def save(self) -> None:
+        path = home_dir() / CONFIG_NAME
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data = dict(self._other, disabled_plugins=sorted(set(self.disabled_plugins)),
+                    plugin_paths=self.plugin_paths,
+                    trusted_projects=sorted(set(self.trusted_projects)))
+        tmp = path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+        tmp.replace(path)
+
+    def trusts(self, project_dir: str | Path) -> bool:
+        """Whether the user allowed this project's own plugins to be loaded."""
+        return _project_key(project_dir) in {_project_key(p) for p in self.trusted_projects}
+
+    def set_trusted(self, project_dir: str | Path, trusted: bool = True) -> None:
+        key = _project_key(project_dir)
+        kept = [p for p in self.trusted_projects if _project_key(p) != key]
+        self.trusted_projects = sorted(kept + [key] if trusted else kept)
+
+    def set_enabled(self, plugin_id: str, enabled: bool) -> None:
+        disabled = set(self.disabled_plugins)
+        (disabled.discard if enabled else disabled.add)(plugin_id)
+        self.disabled_plugins = sorted(disabled)

benchloom/datalog.py

@@ -0,0 +1,205 @@
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# Copyright (C) 2026 Friedrich-Christer Rosenthal
+"""Run folders: every run keeps its data, console output and script together.
+
+A run folder holds ``data.csv`` (the logged rows), ``console.log``, ``run.json``
+(how the run went), a copy of the script, ``checks.csv`` (pass/fail checks, when
+the test made any), ``waveforms/`` (saved scope traces as CSV, SVG and PNG) and
+``report.html``, which shows all of it on one page.
+"""
+
+from __future__ import annotations
+
+import csv
+import importlib.util
+import json
+import math
+import re
+import subprocess
+import sys
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Sequence
+
+from .svgplot import waveform_svg
+
+# The packaged app's programs start the PNG helper when given this first argument.
+SVGPNG_ARG = "--benchloom-svgpng"
+
+
+@dataclass
+class Check:
+    name: str
+    value: Any
+    low: float | None
+    high: float | None
+    unit: str
+    passed: bool
+    time_s: float
+
+    def limits(self) -> str:
+        if self.low is not None and self.high is not None:
+            return f"{self.low:g} to {self.high:g}"
+        if self.low is not None:
+            return f"at least {self.low:g}"
+        if self.high is not None:
+            return f"at most {self.high:g}"
+        return "true"
+
+
+@dataclass
+class Waveform:
+    name: str
+    file: str  # path relative to the run folder, without extension
+    traces: dict[str, tuple[list, list]]
+    time_s: float
+
+
+def evaluate(value: Any, low: float | None, high: float | None) -> bool:
+    """Whether a check passes: a number within its limits, or true without limits."""
+    if low is None and high is None:
+        return value is True or (isinstance(value, (int, float)) and not isinstance(value, bool)
+                                 and math.isfinite(value) and value != 0)
+    if isinstance(value, bool) or not isinstance(value, (int, float)) or math.isnan(value):
+        return False
+    return (low is None or value >= low) and (high is None or value <= high)
+
+
+class RunLog:
+    def __init__(self, runs_dir: Path):
+        self.started = datetime.now()
+        self._t0 = time.monotonic()
+        stamp = self.started.strftime("%Y-%m-%d_%H%M%S")
+        self.path = runs_dir / stamp
+        n = 2
+        while self.path.exists():
+            self.path = runs_dir / f"{stamp}_{n}"
+            n += 1
+        self.path.mkdir(parents=True)
+        self.rows: list[dict[str, Any]] = []
+        self.checks: list[Check] = []
+        self.waveforms: list[Waveform] = []
+        self._columns = ["time_s"]
+        self._console = open(self.path / "console.log", "w", encoding="utf-8")
+
+    def elapsed(self) -> float:
+        return time.monotonic() - self._t0
+
+    def console(self, text: str) -> None:
+        self._console.write(text + "\n")
+        self._console.flush()
+
+    def log(self, values: dict[str, Any]) -> dict[str, Any]:
+        """Append one row to data.csv; new keys become new columns. Returns the row."""
+        row = {"time_s": round(self.elapsed(), 3), **values}
+        self.rows.append(row)
+        new = [key for key in row if key not in self._columns]
+        file = self.path / "data.csv"
+        if new or len(self.rows) == 1:
+            self._columns += sorted(new)
+            with open(file, "w", newline="", encoding="utf-8") as f:
+                writer = csv.DictWriter(f, self._columns, restval="")
+                writer.writeheader()
+                writer.writerows(self.rows)
+        else:
+            with open(file, "a", newline="", encoding="utf-8") as f:
+                csv.DictWriter(f, self._columns, restval="").writerow(row)
+        return row
+
+    # --- checks -------------------------------------------------------------
+    def check(self, name: str, value: Any, low: float | None = None, high: float | None = None,
+              unit: str = "") -> Check:
+        """Record a pass/fail check and append it to checks.csv."""
+        result = Check(str(name), value, low, high, unit or "", evaluate(value, low, high),
+                       round(self.elapsed(), 3))
+        self.checks.append(result)
+        file = self.path / "checks.csv"
+        new = not file.exists()
+        with open(file, "a", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            if new:
+                writer.writerow(["time_s", "name", "value", "low", "high", "unit", "result"])
+            writer.writerow([result.time_s, result.name, result.value,
+                             "" if low is None else low, "" if high is None else high,
+                             result.unit, "pass" if result.passed else "fail"])
+        return result
+
+    def verdict(self) -> str:
+        """'pass', 'fail', or 'none' when the test made no checks."""
+        if not self.checks:
+            return "none"
+        return "pass" if all(c.passed for c in self.checks) else "fail"
+
+    # --- waveforms ------------------------------------------------------------
+    def save_waveform(self, name: str, traces: dict[str, tuple[Sequence, Sequence]]) -> Waveform:
+        """Save scope traces (name -> (times, volts)) as CSV and SVG under waveforms/."""
+        folder = self.path / "waveforms"
+        folder.mkdir(exist_ok=True)
+        slug = re.sub(r"[^A-Za-z0-9_.-]+", "_", str(name)).strip("_") or "waveform"
+        stem = f"{len(self.waveforms) + 1:03d}_{slug}"[:80]
+        traces = {str(k): (list(t), list(v)) for k, (t, v) in traces.items()}
+        names = list(traces)
+        shared = len({tuple(t) for t, _ in traces.values()}) == 1
+        with open(folder / f"{stem}.csv", "w", newline="", encoding="utf-8") as f:
+            writer = csv.writer(f)
+            if shared:
+                times = traces[names[0]][0]
+                writer.writerow(["time_s"] + [f"{n}_V" for n in names])
+                writer.writerows([t] + [traces[n][1][i] for n in names]
+                                 for i, t in enumerate(times))
+            else:
+                writer.writerow([c for n in names for c in (f"{n}_time_s", f"{n}_V")])
+                longest = max(len(t) for t, _ in traces.values())
+                for i in range(longest):
+                    writer.writerow([x for n in names for x in (
+                        (traces[n][0][i], traces[n][1][i]) if i < len(traces[n][0]) else ("", ""))])
+        (folder / f"{stem}.svg").write_text(waveform_svg(traces, str(name)), encoding="utf-8")
+        waveform = Waveform(str(name), f"waveforms/{stem}", traces, round(self.elapsed(), 3))
+        self.waveforms.append(waveform)
+        return waveform
+
+    def _render_pngs(self) -> None:
+        """PNG copies of the waveform images, drawn by Qt in a helper process, when the
+        desktop app is installed. The run itself never loads Qt."""
+        frozen = getattr(sys, "frozen", False)  # the packaged app: no python -m there
+        if not self.waveforms or (not frozen and importlib.util.find_spec("PySide6") is None):
+            return
+        files = [str(self.path / f"{w.file}.svg") for w in self.waveforms]
+        helper = [sys.executable, SVGPNG_ARG] if frozen else [sys.executable, "-m",
+                                                              "benchloom.svgpng"]
+        try:
+            subprocess.run(helper + files, timeout=60 + 2 * len(files), capture_output=True,
+                           check=False, creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0))
+        except (OSError, subprocess.SubprocessError):
+            pass  # the SVG images stay
+
+    # --- end of the run -------------------------------------------------------
+    def finish(self, status: str, error: str | None, info: dict[str, Any],
+               plot: dict[str, Any] | None = None) -> None:
+        self._console.close()
+        passed = sum(c.passed for c in self.checks)
+        meta = {
+            **info,
+            "started": self.started.isoformat(timespec="seconds"),
+            "duration_s": round(self.elapsed(), 3),
+            "status": status,
+            "error": error,
+            "rows": len(self.rows),
+            "result": self.verdict(),
+            "checks": {"passed": passed, "failed": len(self.checks) - passed},
+            "waveforms": [w.file for w in self.waveforms],
+        }
+        (self.path / "run.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
+        self._render_pngs()
+        from .report import write_report
+
+        try:
+            write_report(self, meta, plot or {})
+        except Exception as exc:  # a report must never turn a finished run into a crash
+            (self.path / "report.html").write_text(
+                f"<p>The report could not be made: {exc!r}</p>", encoding="utf-8")
+
+    def check_records(self) -> list[dict[str, Any]]:
+        return [asdict(c) for c in self.checks]