sim86 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
sim86/__init__.py ADDED
@@ -0,0 +1,26 @@
1
+ """Simulator86: run firmware on simulated boards, test it with pytest, inject faults.
2
+
3
+ from sim86 import load_board, Run
4
+ board = load_board("board.json")
5
+ with Run.start(board, duration="10s") as run:
6
+ run["gateway"].serial.wait_for("ready", ms=500)
7
+ run.until(edge="imu.SCL", kind="falling", nth=3)
8
+ fault = run.short("imu.SDA", "gnd")
9
+ """
10
+
11
+ __version__ = "0.1.0"
12
+
13
+ #: Shown in --help, --version, the README and once on first use.
14
+ NOTICE = (
15
+ "sim86 is a demo and feedback preview: it is not designed for production use.\n"
16
+ "For more information, contact Tariq at t@simulator86.com."
17
+ )
18
+
19
+ from .api import ApiError, AuthError, Client, Sim86Error # noqa: E402
20
+ from .board import Board, Part, check_board, load_board, parse_ms # noqa: E402
21
+ from .run import Halt, LogLine, PartHandle, Reading, Run, RunEnded, SerialTimeout # noqa: E402
22
+
23
+ __all__ = [
24
+ "ApiError", "AuthError", "Board", "Client", "Halt", "LogLine", "Part", "PartHandle", "Reading", "Run",
25
+ "RunEnded", "SerialTimeout", "Sim86Error", "check_board", "load_board", "parse_ms",
26
+ ]
sim86/_build.py ADDED
@@ -0,0 +1 @@
1
+ CHANNEL = "release"
sim86/api.py ADDED
@@ -0,0 +1,368 @@
1
+ """HTTP side of the Simulator86 API: credentials, GraphQL, the catalog and run creation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import contextlib
6
+ import json
7
+ import os
8
+ import sys
9
+ import time
10
+ import uuid
11
+ import urllib.error
12
+ import urllib.parse
13
+ import urllib.request
14
+ from pathlib import Path
15
+ from typing import Any, Dict, Iterator, List, Optional
16
+
17
+ from . import __version__
18
+ from ._build import CHANNEL
19
+
20
+ # Where the CLI talks to, built in: users never configure URLs. A release
21
+ # build knows production only; a dev build (the source tree, editable
22
+ # installs) also knows `dev` and `local` (the dev API + an editor on
23
+ # localhost:3000), picked with `--target` / SIM86_TARGET.
24
+ _PROD = ("https://api.sim86.com", "https://app.sim86.com")
25
+ TARGETS = {"prod": _PROD}
26
+ if CHANNEL == "dev":
27
+ TARGETS.update({
28
+ "dev": ("https://api-dev.sim86.com", "https://dev-app.sim86.com"),
29
+ "local": ("https://api-dev.sim86.com", "http://localhost:3000"),
30
+ })
31
+ DEFAULT_TARGET = "prod"
32
+ IS_DEV_BUILD = CHANNEL == "dev"
33
+ # Runs belong to a project on the server. The CLI keeps one per account,
34
+ # out of the way, so users only ever deal with runs.
35
+ RUNS_PROJECT_NAME = "sim86 CLI runs"
36
+
37
+
38
+ class Sim86Error(Exception):
39
+ """Base class for every error this package raises."""
40
+
41
+
42
+ class AuthError(Sim86Error):
43
+ """The API key is missing, revoked, or not accepted."""
44
+
45
+
46
+ class ApiError(Sim86Error):
47
+ def __init__(self, message: str, status: Optional[int] = None):
48
+ super().__init__(message)
49
+ self.status = status
50
+
51
+
52
+ TOKEN_FILE = "token.env"
53
+ #: How long starting a run waits for a free simulator.
54
+ WAIT_FOR_SIMULATOR_S = 300
55
+
56
+
57
+ def token_file_key(start: Optional[Path] = None) -> Optional[str]:
58
+ """SIM86_API_KEY from a token.env in this folder or up to three above it
59
+ (a demo folder ships one, so its boards run with no setup)."""
60
+ here = (start or Path.cwd()).resolve()
61
+ for folder in [here, *list(here.parents)[:3]]:
62
+ path = folder / TOKEN_FILE
63
+ try:
64
+ text = path.read_text()
65
+ except OSError:
66
+ continue
67
+ for line in text.splitlines():
68
+ line = line.strip()
69
+ if line.startswith("export "):
70
+ line = line[7:].strip()
71
+ if line.startswith("SIM86_API_KEY="):
72
+ value = line.split("=", 1)[1].strip().strip('"').strip("'")
73
+ if value and "REPLACE" not in value.upper():
74
+ return value
75
+ return None
76
+
77
+
78
+ def config_path() -> Path:
79
+ if os.name == "nt":
80
+ base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
81
+ else:
82
+ base = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
83
+ return Path(base) / "sim86" / "config.json"
84
+
85
+
86
+ @contextlib.contextmanager
87
+ def config_lock() -> Iterator[None]:
88
+ """One process at a time (pytest -n workers) for first-time setup."""
89
+ path = config_path().with_suffix(".lock")
90
+ path.parent.mkdir(parents=True, exist_ok=True)
91
+ with open(path, "a") as f:
92
+ try:
93
+ import fcntl
94
+
95
+ fcntl.flock(f, fcntl.LOCK_EX)
96
+ except ImportError: # Windows
97
+ import msvcrt
98
+
99
+ while True:
100
+ try:
101
+ msvcrt.locking(f.fileno(), msvcrt.LK_LOCK, 1) # gives up after about 10 s
102
+ break
103
+ except OSError:
104
+ continue
105
+ yield
106
+
107
+
108
+ def load_config() -> Dict[str, Any]:
109
+ try:
110
+ return json.loads(config_path().read_text())
111
+ except (OSError, ValueError):
112
+ return {}
113
+
114
+
115
+ def save_config(cfg: Dict[str, Any]) -> None:
116
+ path = config_path()
117
+ path.parent.mkdir(parents=True, exist_ok=True)
118
+ path.write_text(json.dumps(cfg, indent=2) + "\n")
119
+ try:
120
+ path.chmod(0o600)
121
+ except OSError:
122
+ pass
123
+
124
+
125
+ def open_browser(url: str) -> bool:
126
+ """Open a URL in the user's browser. False when there is no browser to
127
+ open (Linux without a display, e.g. over SSH).
128
+
129
+ On Linux the browser starts detached and silent: a browser started in the
130
+ foreground prints its own log lines into the CLI's output. The standalone
131
+ executable sets its own library path, which the browser would inherit and
132
+ fail on, so it also gets the user's environment restored."""
133
+ import subprocess
134
+ import sys
135
+ import webbrowser
136
+
137
+ if sys.platform.startswith("linux"):
138
+ if not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")):
139
+ return False
140
+ env = dict(os.environ)
141
+ if getattr(sys, "frozen", False):
142
+ for var in ("LD_LIBRARY_PATH", "LD_PRELOAD"):
143
+ original = env.pop(var + "_ORIG", None)
144
+ if original is not None:
145
+ env[var] = original
146
+ else:
147
+ env.pop(var, None)
148
+ for opener in ("xdg-open", "gio", "sensible-browser"):
149
+ args = [opener, "open", url] if opener == "gio" else [opener, url]
150
+ try:
151
+ subprocess.Popen(args, env=env, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
152
+ stderr=subprocess.DEVNULL, start_new_session=True)
153
+ return True
154
+ except FileNotFoundError:
155
+ continue
156
+ return False
157
+ return webbrowser.open(url)
158
+
159
+
160
+ class Client:
161
+ """One API key against one Simulator86 deployment."""
162
+
163
+ def __init__(self, api_key: Optional[str] = None, target: Optional[str] = None):
164
+ cfg = load_config()
165
+ self.target = (target or os.environ.get("SIM86_TARGET") or DEFAULT_TARGET) if IS_DEV_BUILD else DEFAULT_TARGET
166
+ if self.target not in TARGETS:
167
+ raise Sim86Error(f"unknown target {self.target!r}; use one of {', '.join(TARGETS)}")
168
+ self.api_url, self.app_url = TARGETS[self.target]
169
+ self.api_key = api_key or os.environ.get("SIM86_API_KEY") or token_file_key() or cfg.get("apiKey")
170
+ self._catalog: Optional[Dict[str, Dict[str, Any]]] = None
171
+
172
+ # ---- plumbing ----------------------------------------------------------
173
+
174
+ def _require_key(self) -> str:
175
+ if not self.api_key:
176
+ raise AuthError(
177
+ "no API key: put it in token.env (SIM86_API_KEY=…) next to your boards, "
178
+ "set SIM86_API_KEY, or run `sim86 login`"
179
+ )
180
+ return self.api_key
181
+
182
+ def _request(self, method: str, path: str, body: Optional[bytes] = None,
183
+ headers: Optional[Dict[str, str]] = None, auth: bool = True, timeout: float = 120) -> Any:
184
+ h = {"user-agent": f"sim86-python/{__version__}", **(headers or {})}
185
+ if auth:
186
+ h["authorization"] = f"Bearer {self._require_key()}"
187
+ req = urllib.request.Request(self.api_url + path, data=body, method=method, headers=h)
188
+ try:
189
+ with urllib.request.urlopen(req, timeout=timeout) as res:
190
+ raw = res.read()
191
+ except urllib.error.HTTPError as e:
192
+ raw = e.read()
193
+ try:
194
+ message = json.loads(raw).get("error") or f"API error {e.code}"
195
+ except ValueError:
196
+ message = f"API error {e.code}"
197
+ if e.code == 401:
198
+ raise AuthError(f"API key rejected ({message})") from None
199
+ raise ApiError(message, e.code) from None
200
+ except urllib.error.URLError as e:
201
+ raise ApiError(f"Simulator86 API unreachable at {self.api_url}: {e.reason}") from None
202
+ return json.loads(raw) if raw else {}
203
+
204
+ def gql(self, query: str, variables: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
205
+ body = json.dumps({"query": query, "variables": variables or {}}).encode()
206
+ res = self._request("POST", "/plugin", body, {"content-type": "application/json"})
207
+ if res.get("errors"):
208
+ message = res["errors"][0].get("message", "unknown error")
209
+ if "not authorized" in message.lower() or "unauthorized" in message.lower():
210
+ raise AuthError(message)
211
+ raise ApiError(message)
212
+ return res.get("data") or {}
213
+
214
+ # ---- catalog -----------------------------------------------------------
215
+
216
+ def catalog(self) -> Dict[str, Dict[str, Any]]:
217
+ """Every part the simulator can build, by type name and alias."""
218
+ if self._catalog is None:
219
+ components = self._request("GET", "/catalog", auth=False)["components"]
220
+ by_name: Dict[str, Dict[str, Any]] = {}
221
+ for c in components:
222
+ by_name[c["type"]] = c
223
+ for alias in c.get("aliases") or []:
224
+ by_name.setdefault(alias, c)
225
+ self._catalog = by_name
226
+ return self._catalog
227
+
228
+ def part(self, type_name: str) -> Optional[Dict[str, Any]]:
229
+ cat = self.catalog()
230
+ if type_name in cat:
231
+ return cat[type_name]
232
+ lower = type_name.lower()
233
+ exact = next((c for k, c in cat.items() if k.lower() == lower), None)
234
+ if exact is not None:
235
+ return exact
236
+ # An older spelling, or a type this part replaced (the bare LED
237
+ # LedAnalog is the LED now): the catalog lists them as aliases.
238
+ return next((c for c in cat.values() if any(str(a).lower() == lower for a in c.get("aliases") or [])), None)
239
+
240
+ def search_parts(self, query: str = "", kind: Optional[str] = None, limit: int = 30) -> List[Dict[str, Any]]:
241
+ params = {k: v for k, v in {"q": query, "kind": kind, "limit": str(limit)}.items() if v}
242
+ return self._request("GET", "/catalog/components?" + urllib.parse.urlencode(params), auth=False)["components"]
243
+
244
+ def search_registers(self, type_name: str, query: str = "", limit: int = 40) -> Dict[str, Any]:
245
+ params = {k: v for k, v in {"q": query, "limit": str(limit)}.items() if v}
246
+ return self._request("GET", f"/catalog/registers/{urllib.parse.quote(type_name)}?" + urllib.parse.urlencode(params),
247
+ auth=False)
248
+
249
+ # ---- runs --------------------------------------------------------------
250
+
251
+ def runs_project(self) -> str:
252
+ """The project this account's CLI runs are filed under (created once)."""
253
+ override = os.environ.get("SIM86_PROJECT")
254
+ if override:
255
+ return override
256
+ cfg = load_config()
257
+ cached = (cfg.get("runsProject") or {}).get(self.api_url)
258
+ if cached:
259
+ return cached
260
+ # Parallel test workers on a fresh machine would each create one.
261
+ with config_lock():
262
+ cfg = load_config()
263
+ cached = (cfg.get("runsProject") or {}).get(self.api_url)
264
+ if cached:
265
+ return cached
266
+ return self._find_or_create_runs_project(cfg)
267
+
268
+ def _find_or_create_runs_project(self, cfg: Dict[str, Any]) -> str:
269
+ projects = self.gql("query { projects(filters: { owned: true }) { id name } }").get("projects", [])
270
+ found = next((p["id"] for p in projects if p["name"] == RUNS_PROJECT_NAME), None)
271
+ if not found:
272
+ found = self.gql(
273
+ "mutation($name: String!) { createProject(project: { name: $name }) { id } }",
274
+ {"name": RUNS_PROJECT_NAME},
275
+ )["createProject"]["id"]
276
+ cfg.setdefault("runsProject", {})[self.api_url] = found
277
+ save_config(cfg)
278
+ return found
279
+
280
+ def create_run(self, spec: Dict[str, Any], firmware: Dict[str, bytes]) -> str:
281
+ boundary = f"sim86-{uuid.uuid4().hex}"
282
+ parts: List[bytes] = []
283
+
284
+ def part(name: str, filename: str, ctype: str, data: bytes) -> None:
285
+ parts.append(
286
+ (f"--{boundary}\r\nContent-Disposition: form-data; name=\"{name}\"; filename=\"{filename}\"\r\n"
287
+ f"Content-Type: {ctype}\r\n\r\n").encode() + data + b"\r\n"
288
+ )
289
+
290
+ part("spec", "spec.json", "application/json", json.dumps(spec).encode())
291
+ for comp_id, data in firmware.items():
292
+ part(f"firmware:{comp_id}", f"{comp_id}.bin", "application/octet-stream", data)
293
+ body = b"".join(parts) + f"--{boundary}--\r\n".encode()
294
+ # When every simulator is taken the request is refused (a 502 or 503 from
295
+ # the gateway), and nothing has started: wait for a slot.
296
+ deadline = time.monotonic() + WAIT_FOR_SIMULATOR_S
297
+ delay, told = 2.0, False
298
+ while True:
299
+ try:
300
+ res = self._request("POST", "/sdk/runs", body,
301
+ {"content-type": f"multipart/form-data; boundary={boundary}"}, timeout=300)
302
+ break
303
+ except ApiError as e:
304
+ if e.status not in (502, 503, 504):
305
+ raise
306
+ if time.monotonic() >= deadline:
307
+ raise ApiError("No simulator came free in "
308
+ f"{WAIT_FOR_SIMULATOR_S // 60} minutes. Please try again shortly, or run fewer "
309
+ "tests at once.", e.status) from None
310
+ if not told:
311
+ print("sim86: all simulators are busy, waiting for one…", file=sys.stderr)
312
+ told = True
313
+ time.sleep(delay)
314
+ delay = min(delay * 1.5, 15.0)
315
+ if res.get("status") == "failed":
316
+ raise Sim86Error(f"run refused: {res.get('reason') or 'unknown reason'}")
317
+ return res["runId"]
318
+
319
+ def put_project_file(self, project_id: str, path: str, data: bytes) -> None:
320
+ """Store a file in the runs project (flash images a board's config names)."""
321
+ quoted = "/".join(urllib.parse.quote(part) for part in path.strip("/").split("/"))
322
+ self._request("POST", f"/sdk/projects/{project_id}/files/{quoted}", data,
323
+ {"content-type": "application/octet-stream"}, timeout=600)
324
+
325
+ def run_info(self, run_id: str) -> Dict[str, Any]:
326
+ return self.gql(
327
+ "query($id: UUID!) { run(id: $id) { id status reason simT durationMs realtimeMs startedAt endedAt } }",
328
+ {"id": run_id},
329
+ )["run"]
330
+
331
+ def run_logs(self, run_id: str, since: float = 0) -> Dict[str, Any]:
332
+ return self.gql(
333
+ "query($id: UUID!, $since: Float) { runLogs(id: $id, since: $since) { cursor lines { t source line } } }",
334
+ {"id": run_id, "since": since},
335
+ )["runLogs"]
336
+
337
+ def stop_run(self, run_id: str) -> None:
338
+ self.gql("mutation($id: UUID!) { stopRun(id: $id) }", {"id": run_id})
339
+
340
+ def runs(self) -> List[Dict[str, Any]]:
341
+ return self.gql("query { runs { id status reason simT startedAt endedAt } }").get("runs", [])
342
+
343
+ def run_url(self, run_id: str) -> str:
344
+ """The run's details page (status, limits, logs)."""
345
+ return f"{self.app_url}/cloud/{run_id}"
346
+
347
+ def live_url(self, run_id: str, name: Optional[str] = None) -> str:
348
+ """The run on its own page: the board live, clickable parts, sensor inputs, serial."""
349
+ query = f"?{urllib.parse.urlencode({'name': name})}" if name else ""
350
+ return f"{self.app_url}/live/{run_id}{query}"
351
+
352
+ def open_live(self, url: str) -> None:
353
+ """Open a live page signed in with this key. The key rides in the
354
+ #fragment, which browsers never send to a server; the page keeps it
355
+ for the tab and removes it from the address bar."""
356
+ key = self._require_key()
357
+ open_browser(f"{url}#{urllib.parse.urlencode({'key': key})}")
358
+
359
+ def ws_url(self, path: str) -> str:
360
+ return self.api_url.replace("https://", "wss://", 1).replace("http://", "ws://", 1) + path
361
+
362
+ # ---- feedback ----------------------------------------------------------
363
+
364
+ def send_feedback(self, message: str, kind: Optional[str] = None) -> None:
365
+ self.gql(
366
+ "mutation($input: FeedbackInput!) { createFeedback(input: $input) { id } }",
367
+ {"input": {"message": message, "type": kind}},
368
+ )