koebelt-dash-scripts 1.3.0b1__tar.gz → 1.3.0b2__tar.gz

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koebelt-dash-scripts
-Version: 1.3.0b1
+Version: 1.3.0b2
 Summary: Control drones, robots and test rigs connected in the koebelt/dash app from Python.
 Author-email: Thomas Koebel <contact@koebelt.com>
 License-Expression: MIT
@@ -128,6 +128,26 @@ dash stays in charge, whatever the script does:
 | `every(seconds)`, `wait(seconds)` | Steady loops; dash shows the real rate. |
 | `pid`, `lowpass`, `rate_limit`, `clamp`, `distance`, `bearing`, `angle_diff`, `geo_distance`, `geo_bearing` | Helpers. |
 
+## Errors
+
+When something goes wrong, the error says what, points at the line of your
+script, says why and how to fix it, and suggests the name you meant:
+
+```
+error[E0201]: “pitch” is not a stick of a rover
+  --> follow_me.py:21
+   |
+21 |     dev.sticks(throttle=0.4, pitch=steer)
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = why: sticks are named for the kind of device
+   = help: a rover has: throttle, steer, lx, ly, rx, ry
+   = docs: https://github.com/koebelt/koebelt_dash/blob/main/libs/python-dash-scripts/ERRORS.md#e0201
+```
+
+Every code is explained in [ERRORS.md](ERRORS.md). Catch them as `ScriptError`
+(`e.code`, `e.why`, `e.help`).
+
 The messages between scripts and dash are documented in
 [protocol/SCRIPTS.md](https://github.com/koebelt/koebelt_dash/blob/main/protocol/SCRIPTS.md).
 

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/README.md

@@ -100,6 +100,26 @@ dash stays in charge, whatever the script does:
 | `every(seconds)`, `wait(seconds)` | Steady loops; dash shows the real rate. |
 | `pid`, `lowpass`, `rate_limit`, `clamp`, `distance`, `bearing`, `angle_diff`, `geo_distance`, `geo_bearing` | Helpers. |
 
+## Errors
+
+When something goes wrong, the error says what, points at the line of your
+script, says why and how to fix it, and suggests the name you meant:
+
+```
+error[E0201]: “pitch” is not a stick of a rover
+  --> follow_me.py:21
+   |
+21 |     dev.sticks(throttle=0.4, pitch=steer)
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = why: sticks are named for the kind of device
+   = help: a rover has: throttle, steer, lx, ly, rx, ry
+   = docs: https://github.com/koebelt/koebelt_dash/blob/main/libs/python-dash-scripts/ERRORS.md#e0201
+```
+
+Every code is explained in [ERRORS.md](ERRORS.md). Catch them as `ScriptError`
+(`e.code`, `e.why`, `e.help`).
+
 The messages between scripts and dash are documented in
 [protocol/SCRIPTS.md](https://github.com/koebelt/koebelt_dash/blob/main/protocol/SCRIPTS.md).
 

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/koebelt_dash_scripts/__init__.py

@@ -6,12 +6,16 @@
         dev.sticks(throttle=0.3)
 """
 
-__version__ = "1.3.0b1"
+__version__ = "1.3.0b2"
 
 from .camera import Camera, CameraError, decode_jpeg  # noqa: E402
 from .client import Device, Released, ScriptError, Setting, Telemetry, connect, every, wait  # noqa: E402
+from .errors import TelemetryFieldError, install as _install_errors  # noqa: E402
 from .tools import angle_diff, bearing, clamp, distance, geo_bearing, geo_distance, lowpass, pid, rate_limit  # noqa: E402
 
-__all__ = ["connect", "every", "wait", "Device", "Telemetry", "Setting", "ScriptError", "Released", "Camera", "CameraError", "decode_jpeg",
+__all__ = ["connect", "every", "wait", "Device", "Telemetry", "Setting", "ScriptError", "Released", "Camera", "CameraError", "decode_jpeg", "TelemetryFieldError",
            "pid", "lowpass", "rate_limit", "clamp", "distance", "bearing", "angle_diff", "geo_distance", "geo_bearing",
            "__version__"]
+
+# Uncaught errors from this library print Rust style (errors.py).
+_install_errors()

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/koebelt_dash_scripts/camera.py

@@ -13,8 +13,11 @@ import urllib.request
 from typing import Any, Dict, Iterator, Optional
 
 
-class CameraError(RuntimeError):
-    pass
+from .errors import ScriptError
+
+
+class CameraError(ScriptError):
+    """A camera problem (E0602, E0603)."""
 
 
 def decode_jpeg(data: bytes):
@@ -27,13 +30,13 @@ def decode_jpeg(data: bytes):
     if cv2 is not None:
         img = cv2.imdecode(np.frombuffer(data, np.uint8), cv2.IMREAD_COLOR)
         if img is None:
-            raise CameraError("could not decode a camera frame")
+            raise CameraError("E0602", {"camera": "?", "timeout": 0, "reason": "a frame could not be decoded"})
         return img
     try:
         import numpy as np
         from PIL import Image
     except ImportError:
-        raise CameraError("camera frames need numpy and OpenCV (pip install opencv-python) or Pillow (pip install pillow)") from None
+        raise CameraError("E0603") from None
     return np.asarray(Image.open(io.BytesIO(data)).convert("RGB"))[:, :, ::-1].copy()
 
 
@@ -61,7 +64,7 @@ class Camera:
         if self._thread is not None:
             return
         if not self.url:
-            raise CameraError(f"camera {self.label} is not reachable from this computer")
+            raise CameraError("E0602", {"camera": self.label, "timeout": 0, "reason": "dash knows no address for it that this computer can reach"})
         self._thread = threading.Thread(target=self._read, daemon=True, name=f"koebelt-dash-camera-{self.id}")
         self._thread.start()
 
@@ -121,7 +124,7 @@ class Camera:
         self._start()
         with self._cond:
             if not self._cond.wait_for(lambda: self._jpeg is not None, timeout=timeout):
-                raise CameraError(f"no picture from camera {self.label} within {timeout} s" + (f": {self.error}" if self.error else ""))
+                raise CameraError("E0602", {"camera": self.label, "timeout": timeout, "reason": self.error or "the stream sent nothing"})
             return self._jpeg  # type: ignore[return-value]
 
     def frame(self, timeout: float = 5.0):
@@ -135,7 +138,7 @@ class Camera:
         while True:
             with self._cond:
                 if not self._cond.wait_for(lambda: self._count != seen and self._jpeg is not None, timeout=timeout):
-                    raise CameraError(f"no picture from camera {self.label} within {timeout} s" + (f": {self.error}" if self.error else ""))
+                    raise CameraError("E0602", {"camera": self.label, "timeout": timeout, "reason": self.error or "the stream sent nothing"})
                 seen, data = self._count, self._jpeg
             yield decode_jpeg(data)  # type: ignore[arg-type]
 
@@ -157,7 +160,7 @@ class _Buffered:
             return False
         self.buf += chunk
         if len(self.buf) > 32_000_000:
-            raise CameraError("camera stream without frame boundaries")
+            raise CameraError("E0602", {"camera": "?", "timeout": 0, "reason": "the stream has no frame boundaries"})
         return True
 
     def readline(self) -> Optional[bytes]:

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/koebelt_dash_scripts/client.py

@@ -16,26 +16,18 @@ import queue
 import sys
 import threading
 import time
-import traceback
 from typing import Any, Callable, Dict, Iterator, List, Optional
 
 from websockets.exceptions import ConnectionClosed
 from websockets.sync.client import connect as ws_connect
 
 from .camera import Camera, boxes_of
+from .errors import Released, ScriptError, TelemetryFieldError, report, warn_once
 
 API_VERSION = 1
 DISCOVERY = pathlib.Path.home() / ".koebelt" / "dash-api.json"
 
 
-class ScriptError(RuntimeError):
-    """dash refused a request; the message says why."""
-
-
-class Released(ScriptError):
-    """dash took the sticks away (watchdog, geofence, STOP…) and the operator has not resumed the script yet."""
-
-
 class Telemetry:
     """The device's latest telemetry. Attributes are the fields dash sends
     (``pos``, ``vel``, ``roll``, ``mode``, ``armed``, ``battery``…, see
@@ -63,10 +55,12 @@ class Telemetry:
         return (self.raw["lat"], self.raw["lon"], self.raw.get("galt", 0.0))
 
     def __getattr__(self, name: str):
+        if name.startswith("__"):
+            raise AttributeError(name)
         try:
             return self.raw[name]
         except KeyError:
-            raise AttributeError(f"this device sends no '{name}' (it sends: {', '.join(sorted(self.raw))})") from None
+            raise TelemetryFieldError("E0501", {"name": name, "names": sorted([*self.raw, "alt", "gps", "age"])}) from None
 
     def __repr__(self):
         keys = ("mode", "armed", "pos", "speed", "battery")
@@ -145,8 +139,7 @@ def _find_dash(url: Optional[str], token: Optional[str]):
     try:
         found = json.loads(DISCOVERY.read_text())
     except (OSError, ValueError):
-        raise ScriptError("koebelt dash is not running on this computer (no ~/.koebelt/dash-api.json). "
-                          "Start it, or pass url= and token=.") from None
+        raise ScriptError("E0010") from None
     return url or found["url"], token or found["token"]
 
 
@@ -190,7 +183,7 @@ class Device:
 
     def _call(self, t: str, timeout: float = 5, **fields) -> Any:
         if self._closed.is_set():
-            raise ScriptError("the connection to koebelt dash is closed")
+            raise ScriptError("E0013")
         i = next(self._ids)
         box: "queue.Queue[Dict[str, Any]]" = queue.Queue(1)
         self._waiting[i] = box
@@ -199,14 +192,15 @@ class Device:
             try:
                 res = box.get(timeout=timeout)
             except queue.Empty:
-                raise ScriptError(f"koebelt dash did not answer '{t}' within {timeout} s") from None
+                raise ScriptError("E0014", {"request": t, "timeout": timeout}) from None
         finally:
             self._waiting.pop(i, None)
         if res.get("closed"):
-            raise ScriptError("the connection to koebelt dash closed")
+            raise ScriptError("E0013")
         if not res.get("ok"):
-            err = res.get("err") or "refused"
-            raise (Released if self.released and "resume" in err else ScriptError)(err)
+            code = res.get("code") or "E0900"
+            data = {**(res.get("data") or {}), "message": res.get("err") or "refused"}
+            raise (Released if code == "E0102" else ScriptError)(code, data, res.get("err"))
         return res.get("value")
 
     def _receive(self) -> None:
@@ -271,8 +265,8 @@ class Device:
             for h in handlers:
                 try:
                     h(*args)
-                except Exception:
-                    traceback.print_exc()
+                except Exception as e:
+                    report(e)
 
     def _keepalive(self) -> None:
         while not self._closed.wait(0.1):
@@ -305,7 +299,7 @@ class Device:
     def tlm(self) -> Telemetry:
         """The latest telemetry (20 Hz)."""
         if self._tlm is None:
-            raise ScriptError("no telemetry from the device yet")
+            raise ScriptError("E0502")
         return self._tlm
 
     def next_tlm(self, timeout: float = 1.0) -> Telemetry:
@@ -313,15 +307,21 @@ class Device:
         with self._tlm_ready:
             before = self._tlm
             if not self._tlm_ready.wait_for(lambda: self._tlm is not before, timeout=timeout):
-                raise ScriptError(f"no telemetry for {timeout} s")
+                raise ScriptError("E0502")
             return self._tlm  # type: ignore[return-value]
 
     # ------------------------------------------------------------------ acting
-    def sticks(self, **axes: float) -> None:
+    def sticks(self, *values: float, **axes: float) -> None:
         """Sets the sticks, −1…1, until changed. Drones: ``throttle``, ``yaw``,
         ``pitch``, ``roll``; rovers: ``throttle``, ``steer``; any device:
         ``lx``, ``ly``, ``rx``, ``ry``. dash scales them to the script's speed
         limit, and the operator's sticks win."""
+        if values:
+            raise ScriptError("E0202")
+        for k, v in list(axes.items()):
+            if not -1 <= v <= 1:
+                axes[k] = max(-1.0, min(1.0, float(v)))
+                warn_once("W0201", k, {"name": k, "value": round(float(v), 3), "clamped": axes[k]})
         self._call("sticks", a=axes)
 
     def release(self) -> None:
@@ -408,7 +408,7 @@ class Device:
     def camera(self) -> Camera:
         """The device's first camera."""
         if not self.cameras:
-            raise ScriptError(f"{self.name} has no camera")
+            raise ScriptError("E0601", {"device": self.name})
         return self.cameras[0]
 
     def overlay(self, boxes: Any, width: Optional[float] = None, height: Optional[float] = None) -> None:
@@ -422,6 +422,10 @@ class Device:
                 label: Optional[str] = None) -> Setting:
         """A slider (numbers) or switch (True/False) in dash. Read ``.value``;
         the operator's last value is kept between runs."""
+        if not isinstance(default, (bool, int, float)):
+            raise ScriptError("E0701", {"name": name, "reason": f"the default must be a number or True/False, not {type(default).__name__}"})
+        if min is not None and max is not None and min >= max:
+            raise ScriptError("E0701", {"name": name, "reason": f"min ({min}) must be below max ({max})"})
         value = self._call("setting", name=name, value=default, min=min, max=max, label=label)
         s = self._settings[name] = Setting(name, value)
         return s
@@ -432,6 +436,9 @@ class Device:
         ``button`` (no argument), ``switch`` (True/False) or ``value`` (a
         number). ``key`` and ``gamepad`` suggest bindings; the operator can
         change them."""
+        if kind not in ("button", "switch", "value"):
+            raise ScriptError("E0702", {"name": name, "kind": kind})
+
         def register(fn: Callable) -> Callable:
             self._triggers[name] = fn
             self._call("trigger", name=name, kind=kind, key=key, gamepad=gamepad, min=min, max=max)
@@ -511,13 +518,13 @@ def connect(device: Optional[str] = None, *, url: Optional[str] = None, token: O
     try:
         # Entering the context opens it, in every websockets version from 12 on.
         ws = ws_connect(url, open_timeout=5, max_size=None).__enter__()
-    except OSError as e:
-        raise ScriptError(f"cannot reach koebelt dash at {url}: {e}") from None
+    except (OSError, TimeoutError) as e:
+        raise ScriptError("E0011", {"url": url, "reason": str(e) or type(e).__name__}) from None
     ws.send(json.dumps({"t": "hello", "v": API_VERSION, "token": token, "name": name, "pid": os.getpid()}))
     welcome = json.loads(ws.recv(timeout=5))
     if welcome.get("t") != "welcome":
         ws.close()
-        raise ScriptError(welcome.get("why") or "koebelt dash refused the connection")
+        raise ScriptError("E0012", {"reason": welcome.get("why") or "no reason given"})
     dev = Device(ws, welcome, name)
     dev._use(device)
     _current = dev
@@ -528,6 +535,8 @@ def every(seconds: float) -> Iterator[int]:
     """A steady loop: ``for i in every(0.05): ...`` runs the body every 50 ms
     (or as fast as it can), and reports the real rate to dash."""
     period = float(seconds)
+    if period <= 0:
+        raise ScriptError("E0703", {"seconds": seconds})
     nxt = time.monotonic()
     window, count = nxt, 0
     for i in itertools.count():

koebelt_dash_scripts-1.3.0b2/koebelt_dash_scripts/errors.py

@@ -0,0 +1,297 @@
+"""Errors that say what went wrong, where in your script, why, and what to do.
+
+    error[E0301]: arming is not allowed for this script
+      --> follow_me.py:14
+       |
+    14 |     dev.arm()
+       |     ^^^^^^^^^
+       |
+       = why: the script's limits in koebelt dash do not allow arming or take-off
+       = help: in dash, open the script, then Limits > Allow arming and take-off
+       = docs: https://github.com/koebelt/koebelt_dash/blob/main/libs/python-dash-scripts/ERRORS.md#e0301
+
+Every error has a code, explained in ERRORS.md. Uncaught, they print like
+this instead of a traceback through the library (set KOEBELT_DASH_TRACEBACK=1
+for the full one).
+"""
+from __future__ import annotations
+
+import difflib
+import linecache
+import os
+import pathlib
+import sys
+import threading
+import traceback
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+DOCS = "https://github.com/koebelt/koebelt_dash/blob/main/libs/python-dash-scripts/ERRORS.md"
+_PACKAGE = str(pathlib.Path(__file__).resolve().parent)
+
+# code: (title, why, help). Titles and texts are formatted with the error's data.
+CATALOG: Dict[str, Tuple[str, str, str]] = {
+    # Connecting
+    "E0001": ("no device is connected in koebelt dash",
+              "connect() uses the device selected in dash, and none is connected",
+              "connect a device in dash (Devices), or a simulated one (Devices > Pair > Simulated)"),
+    "E0002": ("no connected device called “{name}”",
+              "connect(\"{name}\") looks for a connected device by name or id",
+              "{suggest}connected now: {names_list}"),
+    "E0003": ("this script has no device yet",
+              "commands need a device, and connect() did not get one",
+              "use the Device returned by connect()"),
+    "E0010": ("koebelt dash is not running on this computer",
+              "connect() looks for ~/.koebelt/dash-api.json, which dash writes when it starts",
+              "open koebelt dash, or run the script from it (Scripts); on another computer, set KOEBELT_DASH_URL and KOEBELT_DASH_TOKEN"),
+    "E0011": ("cannot reach koebelt dash at {url}",
+              "{reason}",
+              "check that dash is open; a script host needs the phone or computer running dash on the same network"),
+    "E0012": ("koebelt dash refused the connection",
+              "{reason}",
+              "run the script from dash, or restart dash so that ~/.koebelt/dash-api.json is up to date"),
+    "E0013": ("the connection to koebelt dash closed",
+              "dash was closed, or the script was stopped from it",
+              "start the script again once dash is open"),
+    "E0014": ("koebelt dash did not answer “{request}” within {timeout} s",
+              "dash is busy or stuck, or the network to it dropped",
+              "try again; if it keeps happening, restart dash"),
+    # Safety: the operator decides
+    "E0101": ("STOP is on",
+              "the operator pressed STOP, and dash refuses commands until they clear it",
+              "clear STOP in dash, then run the script again; a script can react with @dev.on_stop"),
+    "E0102": ("this script lost the sticks: {why}",
+              "dash took the sticks away for safety, and the script may not take them back by itself",
+              "in dash, press Resume on the script (or on Control); handle it in the script with @dev.on_stop"),
+    "E0103": ("{other} already drives {device}",
+              "one script at a time drives a device's sticks",
+              "stop {other} in dash, or connect this script to another device"),
+    # Driving
+    "E0201": ("“{name}” is not a stick of a {kind}",
+              "sticks are named for the kind of device",
+              "{suggest}a {kind} has: {names_list}"),
+    "E0202": ("sticks() takes named axes",
+              "each axis has a name, so a value cannot go to the wrong one",
+              "dev.sticks(throttle=0.5, steer=-0.2); a drone has throttle, yaw, pitch, roll"),
+    # Limits set in dash
+    "E0301": ("arming and take-off are not allowed for this script",
+              "the script's limits in koebelt dash do not allow arming or take-off",
+              "in dash, open the script, then Limits > Allow arming and take-off; or arm the device yourself first"),
+    "E0302": ("parameter writes are not allowed for this script",
+              "the script's limits in koebelt dash do not allow writing parameters",
+              "in dash, open the script, then Limits > Allow parameter writes"),
+    "E0303": ("that point is {distance:.0f} m from home, beyond the {fence:.0f} m geofence",
+              "the script's geofence keeps it within {fence:.0f} m of home",
+              "aim closer to home, or raise the geofence in dash (the script's Limits)"),
+    "E0304": ("{height} m is above the {ceiling:.0f} m ceiling",
+              "the script's ceiling keeps drones below {ceiling:.0f} m",
+              "fly lower, or raise the ceiling in dash (the script's Limits)"),
+    # Steps and programs
+    "E0401": ("a {kind} has no “{name}” step",
+              "Program steps depend on the kind of device",
+              "{suggest}a {kind} has: {names_list}"),
+    "E0402": ("no program called “{name}” on {device}",
+              "run_program() runs a sequence from dash's Program screen, by name",
+              "{suggest}programs on {device}: {names_list}"),
+    "E0403": ("“{running}” is already running",
+              "a device runs one sequence at a time",
+              "wait for it, or dev.stop_program() first"),
+    "E0404": ("the device cannot run it now",
+              "it is stopped, disconnected, or replaying a recording in dash",
+              "check the device in dash"),
+    "E0405": ("the step did not finish: {message}",
+              "the device, the operator or a safety check ended it",
+              "look at what the device is doing in dash; the operator taking the sticks ends a step"),
+    "E0406": ("no program is running",
+              "pause_program(), resume_program() and stop_program() act on a running one",
+              "start one with dev.run_program(\"…\")"),
+    # Reading
+    "E0501": ("this device sends no “{name}”",
+              "telemetry has the fields the device sends",
+              "{suggest}it sends: {names_list}"),
+    "E0502": ("no telemetry from the device yet",
+              "the device has not sent any since the script connected",
+              "check that it is connected and its link is up in dash"),
+    # Camera
+    "E0601": ("{device} has no camera",
+              "the device declares no video stream",
+              "add one in the firmware: video() in the koebelt/link library (see the Live video guide)"),
+    "E0602": ("no picture from camera {camera} within {timeout} s",
+              "{reason}",
+              "check the camera in dash (Live > CAM); a camera reached by IP needs this computer on the same network"),
+    "E0603": ("camera frames need numpy and OpenCV or Pillow",
+              "frames are decoded into numpy images",
+              "pip install opencv-python   (or: pip install pillow numpy)"),
+    # Declarations
+    "E0701": ("setting “{name}”: {reason}",
+              "settings become sliders (numbers) or switches (True/False) in dash",
+              "dev.setting(\"speed\", 0.4, min=0, max=1) or dev.setting(\"patrol\", False)"),
+    "E0702": ("trigger “{name}”: unknown kind “{kind}”",
+              "a trigger is a button, a switch or a value",
+              "kind=\"button\", kind=\"switch\" or kind=\"value\""),
+    "E0703": ("every() needs a period above 0 s, not {seconds}",
+              "it is the time between two turns of the loop",
+              "for _ in every(0.05):   # 20 times a second"),
+    # Anything else dash refuses
+    "E0900": ("koebelt dash refused: {message}", "", "if it looks like a bug, report it with the script on GitHub"),
+    "E0901": ("koebelt dash does not know “{message}”",
+              "this library and dash disagree on the messages",
+              "update koebelt dash and koebelt-dash-scripts to matching versions"),
+}
+
+WARNINGS: Dict[str, Tuple[str, str, str]] = {
+    "W0201": ("{name}={value} is outside −1…1: dash uses {clamped}",
+              "sticks go from −1 to 1",
+              "clamp it yourself (koebelt_dash_scripts.clamp) to silence this"),
+}
+
+
+def _suggestion(name: Any, names: Iterable[str]) -> str:
+    close = difflib.get_close_matches(str(name), [str(n) for n in names], n=1, cutoff=0.6)
+    return f"did you mean “{close[0]}”? " if close else ""
+
+
+def _user_frame() -> Optional[traceback.FrameSummary]:
+    """The innermost frame of the script calling the library."""
+    for f in reversed(traceback.extract_stack()):
+        if not str(pathlib.Path(f.filename).resolve()).startswith(_PACKAGE) and not f.filename.startswith("<frozen"):
+            return f
+    return None
+
+
+class ScriptError(RuntimeError):
+    """An error from koebelt-dash-scripts or koebelt dash, with its code."""
+
+    def __init__(self, code: str, data: Optional[Dict[str, Any]] = None, message: Optional[str] = None):
+        self.code = code
+        self.data = dict(data or {})
+        names = self.data.get("names")
+        if names is not None:
+            self.data.setdefault("names_list", ", ".join(str(n) for n in names) or "none")
+            self.data.setdefault("suggest", _suggestion(self.data.get("name", ""), names))
+        self.data.setdefault("suggest", "")
+        title, why, help_ = (WARNINGS if code.startswith("W") else CATALOG).get(code, ("{message}", "", ""))
+        self.data.setdefault("message", message or "")
+        self.title = _fmt(title, self.data) or message or code
+        self.why = _fmt(why, self.data)
+        self.help = _fmt(help_, self.data)
+        self.where = _user_frame()
+        super().__init__(self.title)
+
+    def render(self, color: Optional[bool] = None) -> str:
+        return render(self, color=color)
+
+
+class Released(ScriptError):
+    """dash took the sticks away (watchdog, geofence, STOP…) and the operator has not resumed the script yet."""
+
+
+class TelemetryFieldError(ScriptError, AttributeError):
+    """A telemetry field the device does not send."""
+
+
+def _fmt(t: str, data: Dict[str, Any]) -> str:
+    class Safe(dict):
+        def __missing__(self, k):
+            return "{" + k + "}"
+    try:
+        return t.format_map(Safe(data))
+    except (ValueError, TypeError):
+        return t
+
+
+def _use_color(stream) -> bool:
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("KOEBELT_DASH_COLOR"):
+        return True
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def render(e: ScriptError, color: Optional[bool] = None) -> str:
+    """The error, Rust style: title, the script's line, why, help, docs."""
+    c = _use_color(sys.stderr) if color is None else color
+
+    def paint(s: str, code: str) -> str:
+        return f"\x1b[{code}m{s}\x1b[0m" if c else s
+
+    kind = "warning" if e.code.startswith("W") else "error"
+    head = paint(f"{kind}[{e.code}]", "1;33" if kind == "warning" else "1;31") + paint(f": {e.title}", "1")
+    out = [head]
+    f = e.where
+    if f is not None and f.lineno:
+        src = (linecache.getline(f.filename, f.lineno) or "").rstrip("\n")
+        n = str(f.lineno)
+        pad = " " * len(n)
+        out.append(f"{pad}{paint('-->', '1;34')} {os.path.basename(f.filename)}:{f.lineno}")
+        if src.strip():
+            indent = len(src) - len(src.lstrip())
+            out.append(f"{pad} {paint('|', '1;34')}")
+            out.append(f"{paint(n, '1;34')} {paint('|', '1;34')} {src}")
+            out.append(f"{pad} {paint('|', '1;34')} {' ' * indent}{paint('^' * max(1, len(src.strip())), '1;31' if kind == 'error' else '1;33')}")
+        out.append(f"{pad} {paint('|', '1;34')}")
+        lead = f"{pad} {paint('=', '1;34')}"
+    else:
+        lead = f"  {paint('=', '1;34')}"
+    if e.why:
+        out.append(f"{lead} {paint('why', '1')}: {e.why}")
+    if e.help:
+        out.append(f"{lead} {paint('help', '1;32')}: {e.help}")
+    out.append(f"{lead} {paint('docs', '1')}: {DOCS}#{e.code.lower()}")
+    return "\n".join(out)
+
+
+_warned = set()
+
+
+def warn_once(code: str, key: Any, data: Dict[str, Any]) -> None:
+    """A warning, once per place in the script and key."""
+    w = ScriptError(code, data)
+    at = (code, key, w.where.filename if w.where else None, w.where.lineno if w.where else None)
+    if at in _warned:
+        return
+    _warned.add(at)
+    print(render(w), file=sys.stderr, flush=True)
+
+
+def _hook(kind, value, tb):
+    if isinstance(value, ScriptError) and not os.environ.get("KOEBELT_DASH_TRACEBACK"):
+        # The call chain in the script, without the library's frames.
+        chain = [f for f in traceback.extract_tb(tb) if not str(pathlib.Path(f.filename).resolve()).startswith(_PACKAGE)]
+        if value.where is None and chain:
+            value.where = chain[-1]
+        print(render(value), file=sys.stderr, flush=True)
+        if len(chain) > 1:
+            print("\n  called from: " + " ← ".join(f"{os.path.basename(f.filename)}:{f.lineno} {f.name}()" for f in reversed(chain[:-1])), file=sys.stderr)
+        return
+    _previous(kind, value, tb)
+
+
+def _thread_hook(args):
+    if isinstance(args.exc_value, ScriptError):
+        _hook(args.exc_type, args.exc_value, args.exc_traceback)
+    else:
+        _previous_thread(args)
+
+
+_previous = sys.excepthook
+_previous_thread = threading.excepthook
+
+
+def install() -> None:
+    """Prints this library's errors Rust style when the script does not catch them."""
+    if sys.excepthook is not _hook:
+        sys.excepthook = _hook
+        threading.excepthook = _thread_hook
+
+
+def report(exc: BaseException) -> None:
+    """For handlers: print an exception the library caught, readably."""
+    if isinstance(exc, ScriptError):
+        print(render(exc), file=sys.stderr, flush=True)
+    else:
+        tb = [f for f in traceback.extract_tb(exc.__traceback__) if not str(pathlib.Path(f.filename).resolve()).startswith(_PACKAGE)]
+        print("".join(traceback.format_list(tb)) + "".join(traceback.format_exception_only(type(exc), exc)), file=sys.stderr, end="", flush=True)
+
+
+def codes() -> List[str]:
+    return sorted(CATALOG) + sorted(WARNINGS)

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/koebelt_dash_scripts.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: koebelt-dash-scripts
-Version: 1.3.0b1
+Version: 1.3.0b2
 Summary: Control drones, robots and test rigs connected in the koebelt/dash app from Python.
 Author-email: Thomas Koebel <contact@koebelt.com>
 License-Expression: MIT
@@ -128,6 +128,26 @@ dash stays in charge, whatever the script does:
 | `every(seconds)`, `wait(seconds)` | Steady loops; dash shows the real rate. |
 | `pid`, `lowpass`, `rate_limit`, `clamp`, `distance`, `bearing`, `angle_diff`, `geo_distance`, `geo_bearing` | Helpers. |
 
+## Errors
+
+When something goes wrong, the error says what, points at the line of your
+script, says why and how to fix it, and suggests the name you meant:
+
+```
+error[E0201]: “pitch” is not a stick of a rover
+  --> follow_me.py:21
+   |
+21 |     dev.sticks(throttle=0.4, pitch=steer)
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = why: sticks are named for the kind of device
+   = help: a rover has: throttle, steer, lx, ly, rx, ry
+   = docs: https://github.com/koebelt/koebelt_dash/blob/main/libs/python-dash-scripts/ERRORS.md#e0201
+```
+
+Every code is explained in [ERRORS.md](ERRORS.md). Catch them as `ScriptError`
+(`e.code`, `e.why`, `e.help`).
+
 The messages between scripts and dash are documented in
 [protocol/SCRIPTS.md](https://github.com/koebelt/koebelt_dash/blob/main/protocol/SCRIPTS.md).
 

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/koebelt_dash_scripts.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ koebelt_dash_scripts/__init__.py
 koebelt_dash_scripts/__main__.py
 koebelt_dash_scripts/camera.py
 koebelt_dash_scripts/client.py
+koebelt_dash_scripts/errors.py
 koebelt_dash_scripts/host.py
 koebelt_dash_scripts/py.typed
 koebelt_dash_scripts/tools.py
@@ -16,5 +17,6 @@ koebelt_dash_scripts.egg-info/requires.txt
 koebelt_dash_scripts.egg-info/top_level.txt
 tests/test_camera.py
 tests/test_client.py
+tests/test_errors.py
 tests/test_host.py
 tests/test_tools.py

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "koebelt-dash-scripts"
-version = "1.3.0b1"
+version = "1.3.0b2"
 description = "Control drones, robots and test rigs connected in the koebelt/dash app from Python."
 readme = "README.md"
 requires-python = ">=3.9"

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/tests/test_camera.py

@@ -57,8 +57,9 @@ def test_reads_multipart_frames_whatever_their_type(stream):
 
 
 def test_a_camera_without_a_url():
-    with pytest.raises(RuntimeError, match="not reachable"):
+    with pytest.raises(RuntimeError) as e:
         Camera({"id": "cam", "url": None}).jpeg(timeout=0.1)
+    assert e.value.code == "E0602" and "address" in e.value.why
 
 
 class _T:

{koebelt_dash_scripts-1.3.0b1 → koebelt_dash_scripts-1.3.0b2}/tests/test_client.py

@@ -54,9 +54,12 @@ class FakeDash:
                 elif m["t"] == "setting":
                     res["value"] = 0.7 if m["name"] == "kept" else m["value"]
                 elif m["t"] == "sticks" and self.refuse_sticks:
-                    res = {"t": "res", "id": m["id"], "ok": False, "err": self.refuse_sticks}
+                    res = {"t": "res", "id": m["id"], "ok": False, "err": self.refuse_sticks, "code": "E0102", "data": {"why": "Mule left the 50 m geofence: it holds."}}
                 elif m["t"] == "cmd" and m["c"] == "arm":
-                    res = {"t": "res", "id": m["id"], "ok": False, "err": "Arming is not allowed for this script (Limits in dash)."}
+                    res = {"t": "res", "id": m["id"], "ok": False, "err": "Arming is not allowed for this script (Limits in dash).", "code": "E0301"}
+                elif m["t"] == "sticks" and "pitch" in m["a"]:
+                    res = {"t": "res", "id": m["id"], "ok": False, "err": "not a stick", "code": "E0201",
+                           "data": {"name": "pitch", "names": ["throttle", "steer", "lx", "ly", "rx", "ry"], "kind": "rover"}}
                 elif m["t"] == "cmd" and m["c"] == "params":
                     res["value"] = {"MAX_SPD": 2.0}
                 ws.send(json.dumps(res))
@@ -92,16 +95,21 @@ def test_finds_dash_and_uses_the_selected_device(dash):
     assert dash.hello["name"] == "test.py" and dash.hello["v"] == 1
     assert (dev.name, dev.kind, dev.simulated) == ("Mule", "rover", True)
     assert dev.tlm.alt == 3 and dev.tlm.mode == "AUTO" and dev.tlm.battery == 80
-    with pytest.raises(AttributeError, match="sends no 'lidar'"):
+    with pytest.raises(AttributeError) as e:
         dev.tlm.lidar
+    assert e.value.code == "E0501" and "lidar" in e.value.title
+    with pytest.raises(AttributeError) as e:
+        dev.tlm.batery
+    assert "did you mean “battery”" in e.value.help
     dev.close()
 
 
 def test_environment_wins_over_the_discovery_file(dash, monkeypatch):
     monkeypatch.setenv("KOEBELT_DASH_URL", dash.url)
     monkeypatch.setenv("KOEBELT_DASH_TOKEN", "wrong")
-    with pytest.raises(k.ScriptError, match="token"):
+    with pytest.raises(k.ScriptError) as e:
         k.connect()
+    assert e.value.code == "E0012" and "token" in e.value.why
 
 
 def test_no_dash_running(tmp_path, monkeypatch):
@@ -190,8 +198,9 @@ def test_released_and_takeover(dash):
     dash.send({"t": "released", "why": "Mule left the 50 m geofence: it holds."})
     assert wait_for(lambda: stopped and dev.released)
     dash.refuse_sticks = "Mule left the 50 m geofence: it holds. The operator must resume the script in dash."
-    with pytest.raises(k.Released, match="resume"):
+    with pytest.raises(k.Released) as e:
         dev.sticks(throttle=1)
+    assert "Resume" in e.value.help
     dash.send({"t": "resumed"})
     assert wait_for(lambda: dev.released is None)
     dev.close()

koebelt_dash_scripts-1.3.0b2/tests/test_errors.py

@@ -0,0 +1,91 @@
+"""Errors read like Rust's: what, where in the script, why, help, docs."""
+import json
+import os
+import subprocess
+import sys
+import textwrap
+
+import pytest
+
+import koebelt_dash_scripts as k
+from koebelt_dash_scripts.errors import CATALOG, WARNINGS, ScriptError, render
+from test_client import FakeDash, dash  # noqa: F401  (fixture)
+
+
+def test_points_at_the_scripts_line_with_why_help_and_docs(dash):  # noqa: F811
+    dev = k.connect()
+    with pytest.raises(k.ScriptError) as e:
+        dev.arm()
+    text = render(e.value, color=False)
+    lines = text.splitlines()
+    assert lines[0] == "error[E0301]: arming and take-off are not allowed for this script"
+    assert lines[1].strip().startswith("--> test_errors.py:")
+    assert "dev.arm()" in text and "^^^^^^^^^" in text
+    assert "= why: the script's limits in koebelt dash do not allow arming or take-off" in text
+    assert "= help: in dash, open the script, then Limits > Allow arming and take-off" in text
+    assert text.endswith("ERRORS.md#e0301")
+    dev.close()
+
+
+def test_suggests_the_name_you_meant(dash):  # noqa: F811
+    dev = k.connect()
+    with pytest.raises(k.ScriptError) as e:
+        dev.sticks(throttle=0.2, pitch=1)
+    assert e.value.code == "E0201"
+    assert e.value.title == "“pitch” is not a stick of a rover"
+    assert e.value.help.startswith("a rover has: throttle, steer")
+    with pytest.raises(k.ScriptError) as e:
+        dev.sticks(0.5, 0.2)
+    assert e.value.code == "E0202"
+    dev.close()
+
+
+def test_warns_once_when_a_stick_is_out_of_range(dash, capsys):  # noqa: F811
+    dev = k.connect()
+    for _ in range(3):
+        dev.sticks(throttle=1.7)
+    err = capsys.readouterr().err
+    assert err.count("warning[W0201]: throttle=1.7 is outside −1…1: dash uses 1.0") == 1
+    assert dash.got[-1]["a"] == {"throttle": 1.0}
+    dev.close()
+
+
+def test_mistakes_caught_before_dash(dash):  # noqa: F811
+    dev = k.connect()
+    with pytest.raises(k.ScriptError) as e:
+        dev.setting("speed", 0.4, min=1, max=0)
+    assert e.value.code == "E0701" and "min (1) must be below max (0)" in e.value.title
+    with pytest.raises(k.ScriptError) as e:
+        dev.trigger("Go", kind="lever")
+    assert e.value.code == "E0702"
+    with pytest.raises(k.ScriptError) as e:
+        next(k.every(0))
+    assert e.value.code == "E0703"
+    dev.close()
+
+
+def test_every_code_is_documented():
+    with open(os.path.join(os.path.dirname(__file__), "..", "ERRORS.md"), encoding="utf-8") as f:
+        doc = f.read()
+    for code in [*CATALOG, *WARNINGS]:
+        assert f"## {code}" in doc, f"ERRORS.md has no section for {code}"
+
+
+def test_an_uncaught_error_prints_rust_style_without_the_librarys_traceback(tmp_path):
+    script = tmp_path / "my_script.py"
+    script.write_text(textwrap.dedent('''\
+        import koebelt_dash_scripts as k
+
+        def go():
+            k.connect()
+
+        go()
+    '''))
+    env = dict(os.environ, HOME=str(tmp_path), NO_COLOR="1")
+    env.pop("KOEBELT_DASH_URL", None)
+    r = subprocess.run([sys.executable, str(script)], capture_output=True, text=True, env=env)
+    assert r.returncode == 1
+    assert r.stderr.startswith("error[E0010]: koebelt dash is not running on this computer")
+    assert "--> my_script.py:4" in r.stderr and "k.connect()" in r.stderr
+    assert "called from: my_script.py:6 <module>()" in r.stderr
+    assert "Traceback" not in r.stderr and "client.py" not in r.stderr