canopen-bench 1.0.170__py3-none-any.whl

canopen_bench/__init__.py

@@ -0,0 +1,43 @@
+"""CANopen Bench — web tool to test and control CANopen devices."""
+import re
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from pathlib import Path
+
+
+def _read_version() -> str:
+    """The one place the version is read from.
+
+    pyproject.toml first: this project bumps the version on every commit
+    and does not tag releases, so a source checkout is the normal way to
+    run it — and the installed metadata of an editable install goes stale
+    until the next `pip install -e`, happily reporting an old number.
+    Wheel installs have no pyproject next to the package and fall through
+    to the (then correct) metadata.
+
+    The file is scanned for the version line rather than parsed as TOML:
+    ``tomllib`` only exists from Python 3.11, and on 3.10 falling back to
+    the metadata would quietly reintroduce exactly the staleness this
+    function exists to avoid. Adding a ``tomli`` dependency to read one
+    line is not worth it.
+
+    Kept in this module rather than in ``core`` so that reading the
+    version costs no imports beyond the standard library.
+    """
+    try:
+        pp = Path(__file__).resolve().parent.parent / "pyproject.toml"
+        for line in pp.read_text(encoding="utf-8").splitlines():
+            # first `version = "..."` in the file; [project] declares it
+            # before any other table can (build-system has no version key)
+            match = re.match(r'\s*version\s*=\s*["\'](?P<v>[^"\']+)["\']', line)
+            if match:
+                return match.group("v")
+    except OSError:
+        pass
+    try:
+        return _pkg_version("canopen-bench")
+    except PackageNotFoundError:  # bare checkout without install
+        return "dev"
+
+
+__version__ = _read_version()

canopen_bench/__main__.py

@@ -0,0 +1,173 @@
+"""Run with:  python -m canopen_bench  [--host 0.0.0.0] [--port 8000]
+
+Hardware adapters (CPC-USB / IXXAT / PCAN) talk to the bus via
+python-can/canopen; pick the adapter on the Setup page. Demo mode needs no
+hardware — it generates virtual DUTs from the uploaded EDS files. The
+CPC-USB adapter additionally needs the cob-cpcusb driver package.
+"""
+import argparse
+import os
+import signal
+import sys
+import time
+from pathlib import Path
+
+import uvicorn
+
+from . import usersettings
+from .app import create_app
+
+#: How long uvicorn may wait for open connections when stopping. The state
+#: channel is a WebSocket per browser tab, and a tab left open on another
+#: screen never closes it — with uvicorn's default of "wait as long as it
+#: takes", Ctrl+C began a shutdown that never ended. The process stayed
+#: alive holding the supply's serial port, so the next start reported no
+#: power supply found, and the way out was the task manager.
+SHUTDOWN_S = 5
+
+#: Name of the lock file inside a data folder. Dot-prefixed, so it stays out
+#: of the workspace list (Bench._workspace_names skips those).
+LOCK_NAME = ".bench.lock"
+
+#: Held open for the lifetime of the process: the lock lives on the open
+#: file, so the operating system drops it the moment the process is gone,
+#: crash and kill included — there is no stale lock to clean up and no pid
+#: to test for liveness. Module level rather than a local in main(), or the
+#: garbage collector closes the file and hands the folder to the next
+#: starter while this bench is still running.
+_lock_handle = None
+
+
+def _lock(f) -> None:
+    """Exclusive, non-blocking lock, per open file rather than per process.
+
+    Both calls below lock a single open file rather than the process, so a
+    second attempt from *this* process is refused the same way another
+    process would be — which is what makes it testable without spawning
+    one. POSIX ``lockf`` would not: its record locks belong to the process,
+    so a second claim inside one test run would quietly succeed.
+    """
+    if os.name == "nt":
+        import msvcrt
+        f.seek(0)
+        msvcrt.locking(f.fileno(), msvcrt.LK_NBLCK, 1)
+    else:
+        import fcntl
+        fcntl.flock(f.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+
+def claim_data_folder(root: Path) -> int | None:
+    """Claim a data folder for this process. None if it is ours now,
+    otherwise the pid of the bench already holding it (0 if unreadable).
+
+    Two benches on one data folder share a database, a plugin directory and
+    whatever hardware is plugged into the machine. The damage is not loud:
+    the second one to start takes the serial port, and the first one's
+    search then finds nothing and reports "no known power supply found" —
+    which sends the reader to the cable, the port and the instrument, when
+    what was wrong was that the bench was running twice.
+
+    The HTTP port needs no guard of its own: the operating system already
+    refuses the second bind. The data folder is the resource with no such
+    protection, and it is also the right granularity — a release bench on
+    its own folder and port is meant to run beside an everyday one.
+    """
+    root.mkdir(parents=True, exist_ok=True)
+    f = open(root / LOCK_NAME, "a+", encoding="utf-8")
+    try:
+        _lock(f)
+    except OSError:
+        # Only the first byte is locked on Windows, so the pid behind it
+        # stays readable — the message can name what to stop.
+        f.seek(1)
+        held = f.read().strip()
+        f.close()
+        return int(held) if held.isdigit() else 0
+    f.seek(0)
+    f.truncate()
+    f.write(f"\n{os.getpid()}")   # byte 0 is the locked one, the pid follows
+    f.flush()
+    global _lock_handle
+    _lock_handle = f
+    return None
+
+
+def take_over(root: Path, pid: int, timeout_s: float = 8.0) -> bool:
+    """Stop the bench holding this data folder, then claim it.
+
+    Safe to do by pid: the folder is locked, and only the process holding
+    that lock ever wrote the pid behind it, so it cannot be a number the
+    system has since handed to something else. That is the whole reason
+    the pid lives in the lock file rather than in one of its own.
+
+    Windows has no polite signal for this — os.kill terminates there
+    whatever is passed — so the bench does not get to run its shutdown.
+    It does not need to: the port and the bus are handles, and handles go
+    when the process does.
+    """
+    if not pid:
+        return False
+    try:
+        os.kill(pid, signal.SIGTERM)
+    except OSError:
+        pass    # gone already, or not ours to signal — the wait below decides
+    deadline = time.monotonic() + timeout_s
+    while time.monotonic() < deadline:
+        if claim_data_folder(root) is None:
+            return True
+        time.sleep(0.2)
+    return False
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="CANopen Bench web tool")
+    ap.add_argument("--host", default="127.0.0.1")
+    ap.add_argument("--port", type=int, default=8000)
+    ap.add_argument("--data", default=None,
+                    help="this start's data folder, for this start only and not remembered: "
+                         "a second bench beside the everyday one, a mounted Docker volume. "
+                         "Normally it is chosen under Setup > Folders")
+    ap.add_argument("--db", default=None,
+                    help="expert override: explicit sqlite workspace db path. Normally "
+                         "workspaces live as subfolders of the data folder (Setup > Folders, "
+                         "or --data) "
+                         "and are selected on the Setup page. Skips the one-bench-per-data-"
+                         "folder check, since there is no data folder to speak of")
+    ap.add_argument("--takeover", action="store_true",
+                    help="stop the bench already running on this data folder and take it "
+                         "over, instead of refusing to start. What it is really for is the "
+                         "one left behind by a laptop that slept: it still holds the "
+                         "supply's serial port, and no other program can hand that back")
+    args = ap.parse_args()
+
+    data = Path(args.data) if args.data else None
+    if not args.db:
+        root = data or usersettings.data_root()
+        held_by = claim_data_folder(root)
+        if held_by is not None and args.takeover:
+            print(f"Stopping the bench on {root.resolve()} (process {held_by}) …")
+            if take_over(root, held_by):
+                held_by = None
+            else:
+                print(f"Process {held_by} did not stop.", file=sys.stderr)
+        if held_by is not None:
+            who = f"as process {held_by}" if held_by else "already"
+            print(f"CANopen Bench is running {who} on {root.resolve()}.\n"
+                  f"Two of them share that folder's database, plugins and the hardware "
+                  f"plugged into this machine.\n"
+                  f"Stop that one first, or start with --takeover to stop it from here.\n"
+                  f"To run both, give this one a folder and a port of its own:\n"
+                  f"  canopen-bench --data <folder> --port <other port>",
+                  file=sys.stderr)
+            raise SystemExit(1)
+        # said before anybody goes looking for a workspace in another one;
+        # Setup names it too, and changes it (usersettings.data_root)
+        where = "--data, this start only" if data else f"remembered in {usersettings.settings_file()}"
+        print(f"CANopen Bench data folder: {root.resolve()} ({where})", flush=True)
+
+    uvicorn.run(create_app(args.db, data=data), host=args.host, port=args.port,
+                timeout_graceful_shutdown=SHUTDOWN_S)
+
+
+if __name__ == "__main__":
+    main()

canopen_bench/app.py

@@ -0,0 +1,288 @@
+"""Starlette application: serves the frontend, one command endpoint, one state WebSocket.
+
+Workspaces: without an explicit db path the app runs in multi-workspace
+mode — every subfolder of the data folder (chosen under Setup, see
+usersettings; or ``--data`` for one start, e.g. a mounted Docker volume) is
+one workspace holding its own db, EDS files, traces and flows. The active
+workspace is remembered in ``<root>/active-workspace`` and can be switched
+from the Setup page at runtime; switching swaps the whole Bench instance.
+An explicit ``--db`` path keeps the old single-file behaviour (tests,
+embedding, experts).
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from datetime import datetime
+from pathlib import Path
+
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import FileResponse, HTMLResponse, JSONResponse, Response
+from starlette.routing import Mount, Route, WebSocketRoute
+from starlette.staticfiles import StaticFiles
+from starlette.websockets import WebSocket, WebSocketDisconnect
+
+from . import __version__, usersettings
+from .bus.interface import BusInterface
+from .core import Bench
+from .db import Db
+from .plugin import BenchPlugin
+
+STATIC = Path(__file__).parent / "static"
+DEFAULT_WORKSPACE = "default"
+#: the page and its files are asked for again on every load, answered with a
+#: 304 while unchanged. Without it the browser guesses how long a file stays
+#: fresh — and after an update it kept the old stylesheet beside the new
+#: script, a page laid out for a version that was no longer running.
+REVALIDATE = {"Cache-Control": "no-cache"}
+
+
+class _RevalidatedFiles(StaticFiles):
+    async def get_response(self, path, scope):
+        response = await super().get_response(path, scope)
+        response.headers.update(REVALIDATE)
+        return response
+
+
+def _active_workspace(root: Path) -> str:
+    try:
+        name = (root / "active-workspace").read_text(encoding="utf-8").strip()
+    except OSError:
+        return DEFAULT_WORKSPACE
+    return name if name and (root / name).is_dir() else DEFAULT_WORKSPACE
+
+
+def create_app(db_path: str | None = None, bus: BusInterface | None = None,
+               plugins: list[BenchPlugin] | None = None, data: Path | None = None) -> Starlette:
+    """``data``: this start's data folder (``--data``), not the remembered one."""
+    if db_path:
+        root: Path | None = None
+        path = Path(db_path)
+    else:
+        root = Path(data) if data else usersettings.data_root()
+        path = root / _active_workspace(root) / "canopen-bench.db"
+
+    clients: set[WebSocket] = set()
+    holder: dict = {"bench": None, "ticker": None}
+
+    async def broadcast() -> None:
+        if not clients:
+            return
+        snap = holder["bench"].snapshot()
+        dead = []
+        # over a snapshot of the set, not the set itself: sending is an
+        # await, and a browser connecting or a tab closing in that window
+        # mutates `clients` mid-iteration. That raised "Set changed size
+        # during iteration" *out of the whole broadcast*, so every client
+        # after the one being sent to missed that update — and since this
+        # runs as a fire-and-forget task, the only trace was an unretrieved
+        # exception on the console while a screen quietly went stale.
+        for ws in tuple(clients):
+            try:
+                await ws.send_json({"type": "state", "state": snap})
+            except Exception:
+                dead.append(ws)
+        for ws in dead:
+            clients.discard(ws)
+
+    async def safe_broadcast() -> None:
+        """Push state, and never let failing to push break anything else.
+
+        The tick loop awaits this every tick and the Bench fires it after
+        every action. A raise out of here used to take the whole tick loop
+        with it — and since nothing closes the WebSocket, the browser kept
+        a healthy socket that simply never received another message. No
+        reconnect, no error on screen: a run that had finished still read
+        "Running…".
+        """
+        try:
+            await broadcast()
+        except Exception as exc:      # noqa: BLE001 — the point is to catch all
+            bench = holder.get("bench")
+            if bench is not None:
+                bench.log(f"APP  state not pushed — {type(exc).__name__}: {exc}", "emcy0")
+
+    def _build_bench(db: Db) -> Bench:
+        bench = Bench(db, bus=bus, plugins=plugins, workspaces_root=root,
+                      data_fixed=data is not None)
+        bench.set_notifier(safe_broadcast)
+        if root is not None:
+            bench.on_workspace_switch = lambda name: asyncio.ensure_future(_switch(name))
+            bench.on_plugin_reload = lambda: asyncio.ensure_future(_reload_plugins())
+        return bench
+
+    async def _rebuild(next_db: Db, new_workspace: str | None) -> None:
+        """Shared teardown/boot for both workspace switching and a plugin
+        reload: stop the tick loop, tear down the bus, hand off to a fresh
+        Bench (fresh plugin discovery included — Bench.__init__ always
+        re-runs load_plugins()), restart the tick loop. `new_workspace` is
+        the workspace name to persist as active, or None to stay put (a
+        plugin reload never changes which workspace is active)."""
+        old: Bench = holder["bench"]
+        holder["ticker"].cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await holder["ticker"]
+        old.shutdown()
+        if new_workspace is not None:
+            old.db.close()
+            (root / "active-workspace").write_text(new_workspace, encoding="utf-8")
+        bench = _build_bench(next_db)
+        holder["bench"] = bench
+        app.state.bench = bench
+        bench.startup()
+        holder["ticker"] = asyncio.create_task(bench.tick_loop())
+        await broadcast()
+
+    async def _switch(name: str) -> None:
+        """Swap the whole Bench for another workspace: closes the old db,
+        opens the new workspace's."""
+        await _rebuild(Db(root / name / "canopen-bench.db"), new_workspace=name)
+
+    async def _reload_plugins() -> None:
+        """Rebuild the Bench after a plugin install/removal, same workspace
+        and the same live db connection — only the plugin set changes."""
+        await _rebuild(holder["bench"].db, new_workspace=None)
+
+    holder["bench"] = _build_bench(Db(path))
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette):
+        holder["bench"].startup()
+        holder["ticker"] = asyncio.create_task(holder["bench"].tick_loop())
+        yield
+        holder["ticker"].cancel()
+        with contextlib.suppress(asyncio.CancelledError):
+            await holder["ticker"]
+        # Close the state channels rather than waiting for the browsers to
+        # do it. uvicorn's graceful shutdown waits for open connections,
+        # and a tab left open on another screen never closes this one — so
+        # Ctrl+C started a shutdown that never finished, the process stayed
+        # alive holding the supply's serial port, and the next start found
+        # no power supply. __main__ caps that wait as well; this is what
+        # makes the normal case end at once instead of at the cap.
+        for ws in tuple(clients):
+            with contextlib.suppress(Exception):
+                await ws.close()
+        clients.clear()
+        holder["bench"].shutdown()
+        holder["bench"].db.close()
+
+    # the version in the names of the page's files: a browser that holds a
+    # copy from before an update asks for them as new files, rather than
+    # trusting its guess about the old ones (REVALIDATE only reaches it once
+    # it asks again)
+    page = (STATIC / "index.html").read_text(encoding="utf-8")
+    for name in ("styles.css", "app.js"):
+        page = page.replace(f'/static/{name}"', f'/static/{name}?v={__version__}"')
+
+    async def index(request: Request) -> HTMLResponse:
+        return HTMLResponse(page, headers=REVALIDATE)
+
+    async def state(request: Request) -> JSONResponse:
+        return JSONResponse(holder["bench"].snapshot())
+
+    async def action(request: Request) -> JSONResponse:
+        """Parsed by hand rather than through a validation library: one
+        endpoint, two fields. `dispatch` validates the action name and its
+        params anyway, and raises ValueError with a message for the UI."""
+        try:
+            body = await request.json()
+        except Exception:
+            return JSONResponse({"ok": False, "error": "body must be JSON"}, status_code=400)
+        if not isinstance(body, dict) or not isinstance(body.get("action"), str):
+            return JSONResponse({"ok": False, "error": "missing 'action'"}, status_code=400)
+        params = body.get("params") or {}
+        if not isinstance(params, dict):
+            return JSONResponse({"ok": False, "error": "'params' must be an object"},
+                                status_code=400)
+        try:
+            holder["bench"].dispatch(body["action"], params)
+        except ValueError as e:
+            return JSONResponse({"ok": False, "error": str(e)}, status_code=400)
+        return JSONResponse({"ok": True})
+
+    # Plain GET downloads, deliberately outside the action/WebSocket state
+    # machine: a browser download is a different concern (Content-Disposition,
+    # not JSON) and doesn't mutate any state, so it doesn't need dispatch().
+    def _download(body: str, media_type: str, suffix: str) -> Response:
+        stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        return Response(content=body, media_type=media_type, headers={
+            "Content-Disposition": f'attachment; filename="trace_{stamp}.{suffix}"'})
+
+    #: Most rows one request may ask for. A window is what fits on a screen
+    #: plus a little either side; anything larger is someone asking for the
+    #: whole buffer a page at a time, which is what the exports are for.
+    TRACE_PAGE_MAX = 2000
+
+    async def trace_rows(request: Request) -> JSONResponse:
+        """The slice of the trace the panel is scrolled to, newest first.
+
+        A GET rather than an action, for the same reason as the exports: it
+        reads, it does not mutate, and the answer belongs to the one panel
+        that asked rather than in the snapshot every browser receives ten
+        times a second.
+        """
+        def _int(name: str, default: int, lo: int, hi: int) -> int:
+            try:
+                return max(lo, min(hi, int(request.query_params[name])))
+            except (KeyError, TypeError, ValueError):
+                return default
+
+        return JSONResponse(holder["bench"]._trace_page(
+            _int("end", 0, 0, 100_000_000), _int("n", 200, 1, TRACE_PAGE_MAX)))
+
+    async def export_csv(request: Request) -> Response:
+        return _download(holder["bench"]._trace_csv(), "text/csv", "csv")
+
+    async def export_candump(request: Request) -> Response:
+        return _download(holder["bench"]._trace_candump(), "text/plain", "candump.log")
+
+    async def report(request: Request) -> Response:
+        """One file out of the results folder.
+
+        The reports are written as HTML that links to each other and to a
+        stylesheet by bare file name, so they are served under one prefix
+        and those relative links keep working — a summary opened here can
+        still reach its per-case pages.
+
+        Only a plain name is accepted, and only from that folder: the name
+        arrives from the URL, and a results folder is a path the operator
+        chose, so "whatever is under it" must not become "whatever is on
+        the disk".
+        """
+        name = request.path_params["name"]
+        folder = holder["bench"]._results_dir().resolve()
+        target = (folder / name).resolve()
+        if (Path(name).name != name or target.parent != folder
+                or target.suffix.lower() not in (".html", ".json", ".css")
+                or not target.is_file()):
+            return Response("not found", status_code=404)
+        return FileResponse(target)
+
+    async def ws(websocket: WebSocket) -> None:
+        await websocket.accept()
+        clients.add(websocket)
+        try:
+            await websocket.send_json({"type": "state", "state": holder["bench"].snapshot()})
+            while True:
+                await websocket.receive_text()  # client sends pings only
+        except WebSocketDisconnect:
+            pass
+        finally:
+            clients.discard(websocket)
+
+    app = Starlette(lifespan=lifespan, routes=[
+        Route("/", index),
+        Route("/api/state", state),
+        Route("/api/action", action, methods=["POST"]),
+        Route("/api/trace/rows", trace_rows),
+        Route("/api/trace/export.csv", export_csv),
+        Route("/api/trace/export/candump", export_candump),
+        Route("/api/report/{name}", report),
+        WebSocketRoute("/ws", ws),
+        Mount("/static", _RevalidatedFiles(directory=STATIC), name="static"),
+    ])
+    app.state.bench = holder["bench"]
+    app.state.ws_clients = clients   # for tests; the app itself closes over it
+    return app

canopen_bench/bus/__init__.py

@@ -0,0 +1,3 @@
+from .interface import BusInterface, FoundDevice, Frame, SdoResult
+
+__all__ = ["BusInterface", "FoundDevice", "Frame", "SdoResult"]