qupai-lab 0.2.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.
qupai_lab/__init__.py ADDED
@@ -0,0 +1,16 @@
1
+ """The QuPai Lab SDK: work a lab's instruments from Python through InstruCore's REST API (LS4).
2
+
3
+ from qupai_lab import Lab
4
+
5
+ lab = Lab.from_env(record="calls.jsonl")
6
+ with lab.machine("signal-bench-sim") as m:
7
+ gen = m.role("dg822_pro_usb")
8
+ gen.write("set_waveform", channel=1, shape="sine", frequency_hz=1000, amplitude_v=1.0)
9
+ """
10
+
11
+ __version__ = "0.2.0"
12
+
13
+ from qupai_lab.errors import LabError # noqa: E402 (after __version__, which lab.py imports)
14
+ from qupai_lab.lab import Instrument, Lab, Machine # noqa: E402
15
+
16
+ __all__ = ["Instrument", "Lab", "LabError", "Machine", "__version__"]
qupai_lab/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from qupai_lab.cli import main
2
+
3
+ raise SystemExit(main())
qupai_lab/changes.py ADDED
@@ -0,0 +1,63 @@
1
+ """The writes a script made, grouped as a live run's card shows them (LS9): ranges, boxes and fixed arguments."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from dataclasses import dataclass
7
+ from typing import Any
8
+
9
+ from qupai_lab.record import jsonable
10
+
11
+ # Arguments that pick what is written to rather than a value: CH1 and CH2 are two changes, never a range.
12
+ SELECTORS = frozenset({"channel"})
13
+
14
+
15
+ @dataclass
16
+ class Write:
17
+ role: str
18
+ op: str
19
+ args: dict[str, Any]
20
+ machine: str
21
+
22
+
23
+ def _numeric(value: Any) -> bool:
24
+ return isinstance(value, (int, float)) and not isinstance(value, bool)
25
+
26
+
27
+ def _key(value: Any) -> str:
28
+ return json.dumps(value, sort_keys=True, default=jsonable)
29
+
30
+
31
+ def group(writes: list[Write]) -> list[dict[str, Any]]:
32
+ """Group writes by role and op.
33
+
34
+ Within a group the numeric arguments that took more than one value move: one gives
35
+ ``{quantity, min, max}``, several a box ``{ranges: {quantity: [min, max]}}``. Every other argument is
36
+ ``fixed``. Writes whose other arguments differ (another shape, another channel, another set of names) are
37
+ separate groups of the same role and op, in the order they were first written.
38
+ """
39
+ groups: dict[tuple[str, str, str], list[Write]] = {}
40
+ for w in writes:
41
+ names = sorted(w.args)
42
+ held = {k: v for k, v in w.args.items() if k in SELECTORS or not _numeric(v)}
43
+ groups.setdefault((w.role, w.op, _key([names, held])), []).append(w)
44
+ out: list[dict[str, Any]] = []
45
+ for (role, op, _), members in groups.items():
46
+ first = members[0].args
47
+ moving: dict[str, list[Any]] = {}
48
+ fixed: dict[str, Any] = {}
49
+ for name, value in first.items():
50
+ values = [m.args[name] for m in members]
51
+ if name not in SELECTORS and _numeric(value) and len({float(v) for v in values}) > 1:
52
+ moving[name] = [min(values, key=float), max(values, key=float)]
53
+ else:
54
+ fixed[name] = value
55
+ entry: dict[str, Any] = {"role": role, "op": op, "calls": len(members)}
56
+ if len(moving) == 1:
57
+ (quantity, (low, high)), = moving.items()
58
+ entry |= {"quantity": quantity, "min": low, "max": high}
59
+ elif moving:
60
+ entry["ranges"] = moving
61
+ entry["fixed"] = fixed
62
+ out.append(entry)
63
+ return out
qupai_lab/cli.py ADDED
@@ -0,0 +1,94 @@
1
+ """``qupai-lab machines``: the lab's machines, the check that this sandbox (or PC) reaches its lab.
2
+ ``qupai-lab run``: a live run's script, as QuPai starts it after the member approved the run (``runner``)."""
3
+
4
+ from __future__ import annotations
5
+
6
+ import argparse
7
+ import json
8
+ import sys
9
+ from typing import Any
10
+
11
+ from qupai_lab import __version__, config, runner
12
+ from qupai_lab.errors import LabError
13
+ from qupai_lab.lab import Lab, listed
14
+
15
+
16
+ def _instruments(roles: dict[str, str]) -> str:
17
+ return ", ".join(role if role == inst else f"{role}={inst}" for role, inst in roles.items()) or "-"
18
+
19
+
20
+ def _state(m: dict[str, Any]) -> str:
21
+ status = m.get("status")
22
+ return f"{m.get('state')} ({status})" if status and status != "online" else str(m.get("state"))
23
+
24
+
25
+ def rows(data: dict[str, Any]) -> list[tuple[str, str, str, str]]:
26
+ """The listing as (id, kind, state, instruments) rows: live machines, then each pool and its copies."""
27
+ machines = listed(data)
28
+ out = [(m["id"], "live", _state(m), _instruments(m["roles"])) for m in machines if m["kind"] == "live"]
29
+ out += [
30
+ (m["id"], str(m["kind"]), _state(m), _instruments(m["roles"]))
31
+ for m in machines
32
+ if m["kind"] != "live" and not m["pool"]
33
+ ]
34
+ for p in data.get("pools") or []:
35
+ pid = p.get("public_id") or p["id"]
36
+ copies = [m for m in machines if m["pool"] in (pid, p["id"])]
37
+ out.append((pid, "pool", f"{p.get('free', '?')} of {len(p.get('copies') or copies)} free", ""))
38
+ out += [(f" {m['id']}", "simulated", _state(m), _instruments(m["roles"])) for m in copies]
39
+ return out
40
+
41
+
42
+ def _print_machines(lab: Lab, as_json: bool) -> None:
43
+ data = lab.request("GET", "/v1/machines")
44
+ if as_json:
45
+ print(json.dumps({"lab": lab.url, "machines": listed(data), "pools": data.get("pools") or []}, indent=2,
46
+ ensure_ascii=False))
47
+ return
48
+ table = [("MACHINE", "KIND", "STATE", "INSTRUMENTS BY ROLE"), *rows(data)]
49
+ widths = [max(len(r[i]) for r in table) for i in range(3)]
50
+ print(f"Lab {lab.url}")
51
+ for r in table:
52
+ print(" ".join(cell.ljust(w) for cell, w in zip(r[:3], widths)) + " " + r[3])
53
+
54
+
55
+ def main(argv: list[str] | None = None) -> int:
56
+ parser = argparse.ArgumentParser(prog="qupai-lab", description="The QuPai Lab SDK's command line.")
57
+ parser.add_argument("--version", action="version", version=f"qupai-lab {__version__}")
58
+ sub = parser.add_subparsers(dest="command", metavar="command")
59
+ p = sub.add_parser(
60
+ "machines",
61
+ help="list the lab's machines: the check that this sandbox reaches its lab",
62
+ description="Lists the lab's machines (id, kind, state, instruments by role) from QUPAI_LAB_URL with "
63
+ "QUPAI_LAB_KEY, read from the environment, the nearest .env up from here, or /workspace/project/.env.",
64
+ )
65
+ p.add_argument("--json", action="store_true", help="print JSON")
66
+ r = sub.add_parser(
67
+ "run",
68
+ help="run a live run's script (QuPai starts it once the member approved the run)",
69
+ description="Reads the run's settings from the key file and deletes it, checks the commit out into "
70
+ "/tmp/qupai-run-<run>, runs `python run.py <machine>` in the experiment's folder there with the run's key, "
71
+ "copies data/, figures/, calls.jsonl and changes.json to <experiment>/runs/<run>/ and exits with the "
72
+ "script's exit code. SIGTERM and SIGINT are passed to the script; it is killed 20 s later.",
73
+ )
74
+ r.add_argument("--key-file", required=True, help="the run's key file (KEY=VALUE lines), deleted once read")
75
+ r.add_argument("--commit", required=True, help="the approved commit")
76
+ r.add_argument("experiment", help="the experiment's folder, relative to the repository's root")
77
+ r.add_argument("machine", help="the live machine the run holds")
78
+ args = parser.parse_args(argv)
79
+ if args.command == "run":
80
+ return runner.run(args.key_file, args.commit, args.experiment, args.machine)
81
+ if args.command != "machines":
82
+ parser.print_help(sys.stderr)
83
+ return 2
84
+ try:
85
+ url, key = config.settings()
86
+ _print_machines(Lab(url, key, script_ref=""), args.json)
87
+ except LabError as e:
88
+ print(f"qupai-lab: {e}", file=sys.stderr)
89
+ return 1
90
+ return 0
91
+
92
+
93
+ if __name__ == "__main__":
94
+ raise SystemExit(main())
qupai_lab/config.py ADDED
@@ -0,0 +1,152 @@
1
+ """Where a script finds its lab (the environment, a ``.env``) and how it names itself (``X-InstruCore-Script``)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+ import subprocess
7
+ import sys
8
+ from pathlib import Path
9
+ from urllib.parse import quote
10
+
11
+ from qupai_lab.errors import LabError
12
+
13
+ URL_ENV = "QUPAI_LAB_URL"
14
+ KEY_ENV = "QUPAI_LAB_KEY"
15
+ # Set by ``qupai-lab run`` for the script of a live run: the run's id and the live machine it holds.
16
+ RUN_ENV = "QUPAI_LAB_RUN"
17
+ RUN_MACHINE_ENV = "QUPAI_LAB_RUN_MACHINE"
18
+ # A QuPai lab project's checkout in the sandbox: its .env holds the project key.
19
+ PROJECT_ENV = Path("/workspace/project/.env")
20
+ SCRIPT_REF_MAX = 300
21
+
22
+
23
+ def read_dotenv(path: Path) -> dict[str, str]:
24
+ """``KEY=value`` lines of a ``.env`` file: ``export``, quotes and ``#`` comments as shells write them."""
25
+ out: dict[str, str] = {}
26
+ try:
27
+ text = path.read_text(encoding="utf-8")
28
+ except (OSError, UnicodeDecodeError):
29
+ return out
30
+ for raw in text.splitlines():
31
+ line = raw.strip()
32
+ if not line or line.startswith("#"):
33
+ continue
34
+ if line.startswith("export "):
35
+ line = line[len("export ") :].lstrip()
36
+ name, sep, value = line.partition("=")
37
+ if not sep:
38
+ continue
39
+ name, value = name.strip(), value.strip()
40
+ if value[:1] in ("'", '"') and value.find(value[0], 1) > 0:
41
+ value = value[1 : value.find(value[0], 1)] # a quoted value; anything after it is a comment
42
+ elif " #" in value:
43
+ value = value.split(" #", 1)[0].rstrip()
44
+ out[name] = value
45
+ return out
46
+
47
+
48
+ def nearest_dotenv(start: Path | None = None) -> Path | None:
49
+ """The nearest ``.env`` from ``start`` (the working directory) up to the root."""
50
+ here = (start or Path.cwd()).resolve()
51
+ for folder in (here, *here.parents):
52
+ candidate = folder / ".env"
53
+ if candidate.is_file():
54
+ return candidate
55
+ return None
56
+
57
+
58
+ def settings() -> tuple[str, str]:
59
+ """``QUPAI_LAB_URL`` and ``QUPAI_LAB_KEY``: the environment first, then the nearest ``.env`` up from the
60
+ working directory, then ``/workspace/project/.env``."""
61
+ found = {URL_ENV: os.environ.get(URL_ENV, "").strip(), KEY_ENV: os.environ.get(KEY_ENV, "").strip()}
62
+ nearest = nearest_dotenv()
63
+ looked = ["the environment", str(nearest) if nearest else f"no .env from {Path.cwd()} up", str(PROJECT_ENV)]
64
+ for path in (nearest, PROJECT_ENV):
65
+ if all(found.values()):
66
+ break
67
+ if path is None or not path.is_file():
68
+ continue
69
+ values = read_dotenv(path)
70
+ for name in found:
71
+ found[name] = found[name] or values.get(name, "").strip()
72
+ missing = [name for name, value in found.items() if not value]
73
+ if missing:
74
+ raise LabError(
75
+ "NOT_CONFIGURED",
76
+ f"{' and '.join(missing)} not set; looked in: {'; '.join(looked)}. In a QuPai lab project the "
77
+ "project's .env holds both; at a lab PC, use Lab(url, key)",
78
+ {"missing": missing, "looked": looked},
79
+ )
80
+ return found[URL_ENV], found[KEY_ENV]
81
+
82
+
83
+ def run() -> tuple[str | None, str | None]:
84
+ """Inside a live run: its id (``QUPAI_LAB_RUN``) and its machine (``QUPAI_LAB_RUN_MACHINE``); else None."""
85
+ return (os.environ.get(RUN_ENV, "").strip() or None, os.environ.get(RUN_MACHINE_ENV, "").strip() or None)
86
+
87
+
88
+ def _git(folder: Path, *args: str) -> str | None:
89
+ try:
90
+ done = subprocess.run(
91
+ ["git", "-C", str(folder), *args],
92
+ capture_output=True,
93
+ text=True,
94
+ timeout=10,
95
+ check=False,
96
+ )
97
+ except (OSError, subprocess.SubprocessError):
98
+ return None
99
+ out = done.stdout.strip()
100
+ return out if done.returncode == 0 and out else None
101
+
102
+
103
+ def script_ref_for(path: str | os.PathLike[str] | None) -> str | None:
104
+ """``<path relative to the git root>@<HEAD short sha>`` for the file at ``path``; None outside a git
105
+ repository, before its first commit, or without git."""
106
+ if not path:
107
+ return None
108
+ file = Path(path).resolve()
109
+ if not file.is_file():
110
+ return None
111
+ root = _git(file.parent, "rev-parse", "--show-toplevel")
112
+ commit = _git(file.parent, "rev-parse", "--short", "HEAD")
113
+ if root is None or commit is None:
114
+ return None
115
+ try:
116
+ rel = file.relative_to(Path(root).resolve())
117
+ except ValueError:
118
+ return None
119
+ ref = f"{rel.as_posix()}@{commit}"
120
+ if not ref.isascii(): # HTTP headers are Latin-1: a non-ASCII file name goes percent-encoded
121
+ ref = quote(ref, safe="/@._-+~=,:")
122
+ if len(ref) > SCRIPT_REF_MAX: # InstruCore keeps at most 300 characters: keep the commit, cut the path
123
+ ref = ref[-SCRIPT_REF_MAX:]
124
+ return ref
125
+
126
+
127
+ _cached: list[str | None] = []
128
+
129
+
130
+ def running_script_ref() -> str | None:
131
+ """The running ``__main__`` file's ref, computed once per process."""
132
+ if not _cached:
133
+ main = sys.modules.get("__main__")
134
+ _cached.append(script_ref_for(getattr(main, "__file__", None)))
135
+ return _cached[0]
136
+
137
+
138
+ def running_script_blob() -> str | None:
139
+ """The git blob id of the running script's file (``git hash-object`` of it), or None when there is no file:
140
+ what the live run's card compares with the run's commit to say whether this file was rehearsed."""
141
+ import hashlib
142
+ import sys
143
+
144
+ main = sys.modules.get("__main__")
145
+ path = getattr(main, "__file__", None)
146
+ if not path:
147
+ return None
148
+ try:
149
+ data = Path(path).read_bytes()
150
+ except OSError:
151
+ return None
152
+ return hashlib.sha1(b"blob %d\x00" % len(data) + data).hexdigest()
qupai_lab/errors.py ADDED
@@ -0,0 +1,56 @@
1
+ """Refusals and failures, from InstruCore's error shape or the QuPai gateway's problem documents."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ from typing import Any
7
+
8
+ GATEWAY_PROBLEM = "urn:qupai:problem:"
9
+
10
+
11
+ class LabError(Exception):
12
+ """A call the lab, the gateway or the SDK refused or could not make.
13
+
14
+ ``code`` is InstruCore's error code (``LIMIT_EXCEEDED``, ``APPROVAL_REQUIRED``, ``RUN_REQUIRED`` …), the
15
+ gateway's problem code in the same form (``RATE``, ``INVALID_KEY``, ``FORBIDDEN`` …) or one of the SDK's own
16
+ (``UNREACHABLE``, ``NOT_CONFIGURED``, ``UNKNOWN_ROLE`` …). ``message`` is the lab's sentence as it was sent.
17
+ ``status`` is the HTTP status, 0 when no answer came.
18
+ """
19
+
20
+ def __init__(self, code: str, message: str, detail: dict[str, Any] | None = None, status: int = 0) -> None:
21
+ super().__init__(f"{code}: {message}")
22
+ self.code = code
23
+ self.message = message
24
+ self.detail = detail or {}
25
+ self.status = status
26
+
27
+
28
+ def from_response(status: int, body: bytes, content_type: str = "") -> LabError:
29
+ """The error an answer of ``status`` (400 or more) carries.
30
+
31
+ InstruCore answers ``{"error": {code, message, detail}, "req_id"}``; the gateway answers
32
+ ``application/problem+json`` with ``type`` ``urn:qupai:problem:<code>``, ``title`` and a ``detail`` sentence.
33
+ """
34
+ text = body.decode("utf-8", "replace")
35
+ try:
36
+ data = json.loads(text) if text.strip() else None
37
+ except ValueError:
38
+ data = None
39
+ if isinstance(data, dict):
40
+ err = data.get("error")
41
+ if isinstance(err, dict) and err.get("code"):
42
+ detail = err.get("detail") if isinstance(err.get("detail"), dict) else {}
43
+ if data.get("req_id") and "req_id" not in detail:
44
+ detail = {**detail, "req_id": data["req_id"]}
45
+ return LabError(str(err["code"]), str(err.get("message") or ""), detail, status)
46
+ if "type" in data or "problem+json" in content_type:
47
+ kind = str(data.get("type") or "")
48
+ name = kind[len(GATEWAY_PROBLEM) :] if kind.startswith(GATEWAY_PROBLEM) else ""
49
+ code = name.upper().replace("-", "_") if name else f"HTTP_{status}"
50
+ title = str(data.get("title") or "")
51
+ said = data.get("detail")
52
+ message = str(said) if isinstance(said, str) and said else title or text[:300]
53
+ return LabError(code, message, {"type": kind, "title": title, "source": "gateway"}, status)
54
+ if isinstance(err, str) and err:
55
+ return LabError(f"HTTP_{status}", err, {}, status)
56
+ return LabError(f"HTTP_{status}", text[:300] or f"HTTP {status}", {}, status)