Coverage for src/homeassistant_repl/repl.py: 84%

347 statements  

« prev     ^ index     » next       coverage.py v7.17.2, created at 2026-11-17 19:05 +0000

1"""Live mode's interactive shell: a real local Python session (LocalSession, 

2the same engine API client mode uses) with a remote Home Assistant session 

3alongside it. 

4 

5Code runs here, in this process, by default - `import polars`, define 

6functions, keep a dataframe around; none of it touches Home Assistant. `sql` 

7and `hass_api` are local objects that fetch data over the wire (Arrow over 

8the websocket, and the REST API) and hand back local results. 

9 

10`hass` and `obj` are the exception: they only exist inside Home Assistant, 

11so a statement that uses either one (or a variable an earlier such statement 

12left behind over there) is sent to the server-side session and run there, 

13with its output shipped back as text - see LiveSession for exactly how 

14that's decided and what crosses over. `ha-repl exec` runs its snippet the 

15same way (cli.py), just without the prompt. 

16""" 

17 

18from __future__ import annotations 

19 

20import ast 

21import asyncio 

22import contextlib 

23import copy 

24import io 

25import json 

26import sys 

27import types 

28from collections.abc import Sequence 

29from dataclasses import dataclass, field 

30from pathlib import Path 

31from typing import Any 

32 

33from rich.console import Console 

34 

35from .cli import display_options, print_result 

36from .client import Client, HaReplError, client_version 

37from .complete import context_start 

38from .completer import HaCompleter, names_read 

39from .config import display_path 

40from .editor import python_prompt, run_interruptibly 

41from .local_session import LocalSession, format_error 

42from .plugins import bind_context, bind_rebind, run_plugins 

43from .render import decode_value 

44from .rest import hass_api 

45from .shellhelp import answer, help_request 

46from .sql import SqlResult, SqlRow, SqlTool 

47 

48HISTORY = Path.home() / ".ha_repl_history" 

49 

50# Names that only ever exist on the Home Assistant side. 

51REMOTE_ONLY = frozenset({"hass", "obj"}) 

52 

53# Local values bigger than this (as source text) aren't copied to the server. 

54_MAX_SHIPPED_CHARS = 100_000 

55 

56_LIST_ITERATOR: type = type(iter([])) 

57 

58_LITERAL_TYPES = ( 

59 str, 

60 bytes, 

61 int, 

62 float, 

63 bool, 

64 type(None), 

65 list, 

66 tuple, 

67 dict, 

68 set, 

69) 

70 

71 

72@dataclass 

73class Captured: 

74 """What a run produced, collected instead of printed - for `ha-repl exec 

75 --json`. `value` is the trailing expression's, as JSON-ready data.""" 

76 

77 stdout: str = "" 

78 value: Any = None 

79 error: dict[str, str] | None = None 

80 # Server-side output was cut short at the server's size limit. 

81 truncated: bool = False 

82 

83 

84@dataclass 

85class _Chunk: 

86 """Consecutive statements that run on the same side.""" 

87 

88 remote: bool 

89 start: int # first source line, 1-based 

90 end: int # last source line, inclusive 

91 names: _Names 

92 count: int = 1 # statements 

93 

94 

95@dataclass 

96class LiveSession: 

97 """Decides, one statement at a time, which side runs it. 

98 

99 A statement runs on the server if it reads a name that lives there: 

100 `hass`, `obj`, or a variable an earlier server-side statement assigned 

101 (`s = hass.states.get("sun.sun")`, then `s.state`). Everything else 

102 runs locally. A name lives wherever it was last assigned. 

103 

104 The two namespaces are otherwise separate, and only plain data 

105 (strings, numbers, lists/dicts of them) crosses between them. Local -> 

106 server, for a server-side statement that uses local names: plain data 

107 is copied over, and an imported module is imported there under the same 

108 name. Server -> local: a variable a server-side statement assigns comes 

109 back, and is local from then on, if what it holds is plain data. Anything 

110 else local (a dataframe, a function, `sql` or `hass_api` themselves) 

111 can't follow, and the statement is refused with an explanation rather 

112 than failing over there with a puzzling NameError. 

113 """ 

114 

115 client: Any 

116 session_name: str 

117 local: LocalSession 

118 auto_await: bool = True 

119 remote_names: set[str] = field(default_factory=set) 

120 # Bound locally by this shell itself (`sql`, `hass_api`) - never copied over. 

121 shared: frozenset[str] = frozenset() 

122 # Set to collect output instead of printing it. 

123 capture: Captured | None = None 

124 # Seconds the server allows each of its own statements, if any. 

125 timeout: float | None = None 

126 # A statement is running in Home Assistant now. 

127 _remote_busy: bool = field(default=False, init=False) 

128 _sends: set[asyncio.Task[None]] = field(default_factory=set, init=False) 

129 

130 async def refresh_remote_names(self) -> None: 

131 """Pick up what an existing server session already holds (it 

132 outlives this process); after that, run() keeps track itself.""" 

133 reply = await self.client.call("ha_repl_server/sessions") 

134 self.remote_names = set() 

135 for session in reply["sessions"]: 

136 if session["name"] == self.session_name: 136 ↛ 135line 136 didn't jump to line 135 because the condition on line 136 was always true

137 self.remote_names = set(session["variables"]) - self._local_names() 

138 

139 async def run(self, source: str, *, echo: bool = True) -> bool: 

140 """Run source, stopping at the first statement that fails. Only the 

141 final statement's value is echoed, and not even that with `echo` 

142 off. Returns False on any failure.""" 

143 try: 

144 tree = ast.parse(source) 

145 except SyntaxError, ValueError: 

146 return await self._run_local(source, echo=echo) # reports the error 

147 if not tree.body: 147 ↛ 148line 147 didn't jump to line 148 because the condition on line 147 was never true

148 return await self._run_local(source, echo=echo) 

149 lines = source.splitlines() 

150 body = tree.body 

151 whole = True 

152 while body: 

153 # Planned one step at a time: where the rest runs depends on 

154 # what this step leaves behind, and on which side. 

155 chunk = self._next_chunk(body) 

156 body = body[chunk.count :] 

157 # Untouched if it's all there is, so comments and layout survive 

158 # into tracebacks. 

159 text = ( 

160 source 

161 if whole and not body 

162 else "\n".join(lines[chunk.start - 1 : chunk.end]) 

163 ) 

164 whole = False 

165 if chunk.remote: 

166 ok = await self._run_remote(text, chunk.names, echo=echo and not body) 

167 else: 

168 ok = await self._run_local(text, echo=echo and not body) 

169 self.remote_names -= chunk.names.assigned 

170 if not ok: 

171 return False 

172 return True 

173 

174 async def run_quiet(self, source: str) -> dict[str, Any] | None: 

175 """Run source the way a plugin's statement is run: no value 

176 echoed, what it prints sent to stderr, and its error (None if it 

177 worked) handed back rather than reported.""" 

178 outer, quiet = self.capture, Captured() 

179 self.capture = quiet 

180 try: 

181 await self.run(source, echo=False) 

182 finally: 

183 self.capture = outer 

184 sys.stderr.write(quiet.stdout) 

185 return quiet.error 

186 

187 def _next_chunk(self, body: list[ast.stmt]) -> _Chunk: 

188 """The leading statements of `body` that run together: a run of 

189 local ones, or a single server-side one - what a server-side 

190 statement assigns may come back as local data (see _run_remote), 

191 which changes where the statements after it belong.""" 

192 local = self._local_names() 

193 remote = (REMOTE_ONLY | self.remote_names) - local 

194 chunk: _Chunk | None = None 

195 for stmt in body: 

196 names = _Names() 

197 names.visit(stmt) 

198 is_remote = bool(names.loaded & remote) 

199 start = min([ 

200 stmt.lineno, 

201 *(d.lineno for d in getattr(stmt, "decorator_list", [])), 

202 ]) 

203 end = stmt.end_lineno or stmt.lineno 

204 if chunk is None: 

205 chunk = _Chunk(is_remote, start, end, names) 

206 elif start <= chunk.end: 

207 # Two statements sharing a line (`a = 1; hass.x`) can't be cut 

208 # apart by line, so they go together - to the server if either does. 

209 chunk.remote = chunk.remote or is_remote 

210 chunk.end = max(chunk.end, end) 

211 chunk.names.merge(names) 

212 chunk.count += 1 

213 elif not chunk.remote and not is_remote: 

214 chunk.end = end 

215 chunk.names.merge(names) 

216 chunk.count += 1 

217 else: 

218 break 

219 local |= names.assigned 

220 remote -= names.assigned 

221 assert chunk is not None 

222 return chunk 

223 

224 async def _run_local(self, source: str, *, echo: bool) -> bool: 

225 if self.capture is None: 

226 ok = await self.local.run(source, echo=echo) 

227 else: 

228 out = io.StringIO() 

229 try: 

230 with contextlib.redirect_stdout(out): 

231 value = await self.local.evaluate(source, echo=echo) 

232 except asyncio.CancelledError: 

233 raise 

234 except BaseException as err: # noqa: BLE001 - report everything, incl. SystemExit 

235 self.capture.error = format_error(err) 

236 ok = False 

237 else: 

238 if echo and value is not None: 

239 self.capture.value = _jsonable(value) 

240 ok = True 

241 finally: 

242 self.capture.stdout += out.getvalue() 

243 if "_" in self.local.globals_: 

244 self.remote_names.discard("_") 

245 return ok 

246 

247 async def _run_remote(self, source: str, names: _Names, *, echo: bool) -> bool: 

248 local_names = self._local_names() 

249 via = ", ".join( 

250 f"`{n}`" for n in sorted(names.loaded & (REMOTE_ONLY | self.remote_names)) 

251 ) 

252 local_only = sorted(names.loaded & self.shared & local_names) 

253 if local_only: 

254 self._refuse( 

255 f"not run - {', '.join(f'`{n}`' for n in local_only)} only " 

256 f"work{'s' if len(local_only) == 1 else ''} locally and {via} only " 

257 "inside Home Assistant, so one statement can't use both. Assign " 

258 "the Home Assistant part to a variable in a statement of its own " 

259 "first - plain data (strings, numbers, lists/dicts of them) comes back." 

260 ) 

261 return False 

262 preamble: list[str] = [] 

263 stuck: list[str] = [] 

264 for name in sorted(names.loaded & (local_names - self.shared)): 

265 line = _ship(name, self.local.globals_[name]) 

266 if line is not None: 

267 preamble.append(line) 

268 elif name not in names.bound: 

269 stuck.append(name) 

270 if stuck: 

271 self._refuse( 

272 f"not run - this would run inside Home Assistant (it uses {via}), but " 

273 f"{', '.join(f'`{n}`' for n in stuck)} only " 

274 f"exist{'s' if len(stuck) == 1 else ''} in the local session and can't " 

275 "be copied over (only plain data, small sql results and imported modules can)." 

276 ) 

277 return False 

278 if preamble: 

279 copied = await self._exec_remote("\n".join(preamble), echo=False) 

280 if copied is None: 

281 return False 

282 # What it assigns lives on the server afterwards - except plain data, 

283 # which the server hands back and is local from here on. 

284 returned = await self._exec_remote( 

285 source, echo=echo, fetch=sorted(names.assigned) 

286 ) 

287 ok = returned is not None 

288 for name in names.assigned: 

289 self.local.globals_.pop(name, None) 

290 self.remote_names |= names.assigned 

291 for name, tree in (returned or {}).items(): 

292 self.local.globals_[name] = decode_value(tree) 

293 self.remote_names.discard(name) 

294 if echo: 

295 # `_` is whichever side answered last. 

296 self.local.globals_.pop("_", None) 

297 self.remote_names.add("_") 

298 return ok 

299 

300 async def _exec_remote( 

301 self, source: str, *, echo: bool, fetch: list[str] | None = None 

302 ) -> dict[str, Any] | None: 

303 """Run source in the server-side session. None if it raised; 

304 otherwise those of the `fetch` variables that came back as data.""" 

305 payload: dict[str, Any] = { 

306 "code": source, 

307 "session": self.session_name, 

308 "auto_await": self.auto_await, 

309 **display_options(), 

310 } 

311 if self.timeout: 311 ↛ 312line 311 didn't jump to line 312 because the condition on line 311 was never true

312 payload["timeout"] = self.timeout 

313 if fetch: 

314 payload["fetch"] = fetch 

315 if self.capture is not None: 

316 # Escape codes inside a JSON string are just noise for a consumer 

317 # that asked for machine-readable output. 

318 payload["color"] = False 

319 self._remote_busy = True 

320 try: 

321 result = await self.client.call("ha_repl_server/exec", **payload) 

322 finally: 

323 self._remote_busy = False 

324 if not echo: 

325 result = {**result, "value": None} 

326 if self.capture is None: 

327 print_result(result) 

328 else: 

329 if result["stdout"] is not None: 329 ↛ 331line 329 didn't jump to line 331 because the condition on line 329 was always true

330 self.capture.stdout += result["stdout"] 

331 tree = result.get("value_tree") 

332 # What show() made is already text laid out to be read. 

333 as_text = tree is None or result.get("shown") 

334 self.capture.value = ( 

335 result["value"] if as_text else _jsonable(decode_value(tree)) 

336 ) 

337 # The frames are for drawing a traceback, not for a JSON consumer. 

338 self.capture.error = result["error"] and { 

339 k: v for k, v in result["error"].items() if k != "stacks" 

340 } 

341 self.capture.truncated |= bool(result.get("truncated")) 

342 return None if result["error"] else result.get("names") or {} 

343 

344 def interrupt(self) -> bool: 

345 """Ctrl-C: if a statement is running in Home Assistant, ask the 

346 server to stop it there, and say so. Its exec then answers as 

347 usual, with where it stopped.""" 

348 if not self._remote_busy: 

349 return False 

350 send = asyncio.ensure_future( 

351 self.client.send("ha_repl_server/cancel", session=self.session_name) 

352 ) 

353 self._sends.add(send) 

354 send.add_done_callback(self._sends.discard) 

355 return True 

356 

357 def _refuse(self, message: str) -> None: 

358 if self.capture is None: 

359 print(f"ha-repl: {message}", file=sys.stderr) 

360 else: 

361 self.capture.error = { 

362 "type": "HaReplError", 

363 "message": message, 

364 "traceback": f"ha-repl: {message}\n", 

365 } 

366 

367 def remote_names_now(self) -> set[str]: 

368 """The names that live in Home Assistant.""" 

369 return {*REMOTE_ONLY, *self.remote_names} 

370 

371 def completes_remotely(self, text: str) -> bool: 

372 """Whether what's being typed at the end of `text` belongs to Home 

373 Assistant: the input so far reads something that lives there, as 

374 run() would decide - leaving out the word still being typed.""" 

375 return bool(names_read(text[: context_start(text)]) & self.remote_names_now()) 

376 

377 def _local_names(self) -> set[str]: 

378 return { 

379 name 

380 for name in self.local.globals_ 

381 if not name.startswith("__") 

382 # the shell's own, with a counterpart inside Home Assistant 

383 and name not in ("_maybe_await", "unawait", "help", "show") 

384 } 

385 

386 

387class _Names(ast.NodeVisitor): 

388 """The names a piece of code reads (`loaded`), the ones it binds 

389 anywhere at all (`bound` - including arguments and comprehension 

390 variables), and the ones it leaves assigned in the session's own 

391 namespace afterwards (`assigned` - not those inner-scope ones).""" 

392 

393 def __init__(self) -> None: 

394 self.loaded: set[str] = set() 

395 self.bound: set[str] = set() 

396 self.assigned: set[str] = set() 

397 self._depth = 0 

398 

399 def merge(self, other: _Names) -> None: 

400 self.loaded |= other.loaded 

401 self.bound |= other.bound 

402 self.assigned |= other.assigned 

403 

404 def _bind(self, name: str) -> None: 

405 self.bound.add(name) 

406 if self._depth == 0: 

407 self.assigned.add(name) 

408 

409 def visit_Name(self, node: ast.Name) -> None: 

410 if isinstance(node.ctx, ast.Load): 

411 self.loaded.add(node.id) 

412 else: 

413 self._bind(node.id) 

414 

415 def visit_alias(self, node: ast.alias) -> None: 

416 if node.name != "*": 416 ↛ exitline 416 didn't return from function 'visit_alias' because the condition on line 416 was always true

417 self._bind((node.asname or node.name).partition(".")[0]) 

418 

419 def visit_arg(self, node: ast.arg) -> None: 

420 self.bound.add(node.arg) 

421 

422 def visit_AnnAssign(self, node: ast.AnnAssign) -> None: 

423 # Annotations aren't read: nothing evaluates them when the statement 

424 # runs (PEP 649), so a type that only exists on one side - `Any` 

425 # imported locally, a class from the component - is no obstacle. 

426 if node.value is not None: 

427 self.visit(node.target) 

428 self.visit(node.value) 

429 elif not isinstance(node.target, ast.Name): 429 ↛ 430line 429 didn't jump to line 430 because the condition on line 429 was never true

430 self.visit(node.target) 

431 # else a bare `hass: HomeAssistant`, which binds nothing 

432 

433 def _visit_def(self, node: Any) -> None: 

434 self._bind(node.name) 

435 if getattr(node, "returns", None) is not None: 

436 node = copy.copy(node) 

437 node.returns = None 

438 self._visit_scope(node) 

439 

440 def _visit_scope(self, node: ast.AST) -> None: 

441 self._depth += 1 

442 self.generic_visit(node) 

443 self._depth -= 1 

444 

445 visit_FunctionDef = visit_AsyncFunctionDef = visit_ClassDef = _visit_def 

446 visit_Lambda = visit_ListComp = visit_SetComp = visit_DictComp = _visit_scope 

447 visit_GeneratorExp = _visit_scope 

448 

449 

450def _jsonable(value: Any) -> Any: 

451 """A trailing value as something json.dumps accepts: a SqlResult as 

452 its rows, anything already JSON-shaped as itself, a rich renderable 

453 (the Table show() returns) as plain text, the rest as their repr.""" 

454 if isinstance(value, SqlResult): 454 ↛ 455line 454 didn't jump to line 455 because the condition on line 454 was never true

455 return value.json_data() 

456 if isinstance(value, SqlRow): 456 ↛ 457line 456 didn't jump to line 457 because the condition on line 456 was never true

457 return value.json_data() 

458 if not isinstance(value, type) and ( 458 ↛ 461line 458 didn't jump to line 461 because the condition on line 458 was never true

459 hasattr(value, "__rich__") or hasattr(value, "__rich_console__") 

460 ): 

461 out = io.StringIO() 

462 Console(file=out, color_system=None, width=120).print(value) 

463 return out.getvalue() 

464 try: 

465 json.dumps(value) 

466 except TypeError, ValueError: 

467 return repr(value) 

468 return value 

469 

470 

471def _ship(name: str, value: Any) -> str | None: 

472 """A line of source that recreates this local value under the same name 

473 on the server, or None if it isn't something that can be recreated.""" 

474 if isinstance(value, types.ModuleType): 

475 return f"import {value.__name__} as {name}" 

476 if isinstance(value, SqlResult): 

477 # Crosses as its rows, a list of lists - enough for the loop or 

478 # comprehension over a result that calls into `hass` per row. 

479 value = list(value) 

480 if isinstance(value, SqlRow): 480 ↛ 481line 480 didn't jump to line 481 because the condition on line 480 was never true

481 value = value.values 

482 template = "{}" 

483 if type(value) is _LIST_ITERATOR: 

484 # What obj.find_names()/find_paths() hand back: recreated from the 

485 # items it has left, read from a copy so this one isn't used up. 

486 remaining: Any = copy.copy(value) 

487 value, template = list(remaining), "iter({})" 

488 if not isinstance(value, _LITERAL_TYPES): 

489 return None 

490 try: 

491 text = repr(value) 

492 if len(text) > _MAX_SHIPPED_CHARS or ast.literal_eval(text) != value: 492 ↛ 493line 492 didn't jump to line 493 because the condition on line 492 was never true

493 return None 

494 except Exception: # noqa: BLE001 - any failure just means "can't be copied" 

495 return None 

496 return f"{name} = {template.format(text)}" 

497 

498 

499async def connect_live( 

500 client: Client, 

501 session_name: str, 

502 *, 

503 auto_await: bool = True, 

504 capture: Captured | None = None, 

505 timeout: float | None = None, 

506) -> LiveSession: 

507 """A LiveSession with the local `sql` and `hass_api` bound - shared by 

508 the interactive shell and `ha-repl exec`, so a snippet behaves the 

509 same in either.""" 

510 bindings: dict[str, Any] = {} 

511 try: 

512 bindings["hass_api"] = await hass_api(client.url, client.token) 

513 except HaReplError as err: 

514 print(f"ha-repl: hass_api unavailable: {err}", file=sys.stderr) 

515 bindings["hass_api"] = None 

516 try: 

517 bindings["sql"] = await SqlTool.connect(client) 

518 except HaReplError as err: 

519 # Switched off in the integration's options - left unbound. 

520 print(f"ha-repl: sql unavailable: {err}", file=sys.stderr) 

521 

522 live = LiveSession( 

523 client, 

524 session_name, 

525 LocalSession(dict(bindings), auto_await=auto_await), 

526 auto_await=auto_await, 

527 shared=frozenset(bindings), 

528 capture=capture, 

529 timeout=timeout, 

530 ) 

531 await live.refresh_remote_names() 

532 return live 

533 

534 

535def bind_live_rebind(live: LiveSession, plugins: Sequence[Path]) -> None: 

536 """Bind `rebind()` in a live session - once everything else of the 

537 shell's own is bound there, and before the plugins first run.""" 

538 bind_rebind(live.local.globals_, plugins, live.run_quiet, REMOTE_ONLY) 

539 live.shared |= {"rebind"} 

540 

541 

542async def run_repl( 

543 client: Client, 

544 session_name: str, 

545 *, 

546 auto_await: bool = True, 

547 server_name: str | None = None, 

548 plugins: Sequence[Path] = (), 

549) -> int: 

550 try: 

551 info = await client.call("ha_repl_server/info") 

552 server = f"Live Server v{info['version']}" 

553 except HaReplError: 

554 # An older server predating this command - not fatal, just less to show. 

555 info, server = {}, "Live Server" 

556 

557 live = await connect_live(client, session_name, auto_await=auto_await) 

558 completer = HaCompleter(live.local.globals_, live) 

559 completer.remote = "complete" in info.get("commands", ()) 

560 prompt = python_prompt(HISTORY, completer) 

561 bind_context(live.local.globals_, "live", server_name) 

562 bind_live_rebind(live, plugins) 

563 loaded = await run_plugins(plugins, live.run_quiet) 

564 print( 

565 f"Live client v{client_version()} connected to {server} at HA API " 

566 f"{banner_address(client.url, server_name)} (session {session_name!r}). " 

567 "Ctrl-D to exit.\n" 

568 "Python runs locally; anything using `hass` or `obj` runs inside Home Assistant." 

569 f"{banner_plugins(loaded)}" 

570 + ( 

571 "" 

572 if completer.remote 

573 else "\nCompletion inside Home Assistant needs Live Server v0.14.0 or later." 

574 ) 

575 ) 

576 while True: 

577 try: 

578 source = await prompt.prompt_async(">>> ") 

579 except KeyboardInterrupt: 

580 continue 

581 except EOFError: 

582 return 0 

583 if not source.strip(): 

584 continue 

585 if (asked := help_request(source)) is not None: 

586 await answer(asked, "live", live.run, completer.locate, completer.describe) 

587 continue 

588 if is_quit_call(source): 

589 return 0 

590 await run_interruptibly(live.run(source), live.interrupt) 

591 completer.forget() 

592 

593 

594def banner_address(url: str, server_name: str | None) -> str: 

595 """Where a shell is connected, by name too if it was chosen by name.""" 

596 return f"{server_name} ({url})" if server_name else url 

597 

598 

599def banner_plugins(loaded: Sequence[Path]) -> str: 

600 """The banner's line listing the plugins run, if there were any.""" 

601 if not loaded: 

602 return "" 

603 return "\nPlugins: " + ", ".join(display_path(path) for path in loaded) 

604 

605 

606def is_quit_call(source: str) -> bool: 

607 """True for a bare `quit()` or `exit()` - the standard way to leave a REPL. 

608 

609 Running that would raise SystemExit inside the session, caught and 

610 reported back as a confusing traceback instead of actually exiting 

611 anything, so it's handled like Ctrl-D instead. 

612 """ 

613 try: 

614 (stmt,) = ast.parse(source).body 

615 except SyntaxError, ValueError: 

616 return False 

617 return ( 

618 isinstance(stmt, ast.Expr) 

619 and isinstance(stmt.value, ast.Call) 

620 and isinstance(stmt.value.func, ast.Name) 

621 and stmt.value.func.id in ("quit", "exit") 

622 and not stmt.value.args 

623 and not stmt.value.keywords 

624 )