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
« 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.
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.
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"""
18from __future__ import annotations
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
33from rich.console import Console
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
48HISTORY = Path.home() / ".ha_repl_history"
50# Names that only ever exist on the Home Assistant side.
51REMOTE_ONLY = frozenset({"hass", "obj"})
53# Local values bigger than this (as source text) aren't copied to the server.
54_MAX_SHIPPED_CHARS = 100_000
56_LIST_ITERATOR: type = type(iter([]))
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)
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."""
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
84@dataclass
85class _Chunk:
86 """Consecutive statements that run on the same side."""
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
95@dataclass
96class LiveSession:
97 """Decides, one statement at a time, which side runs it.
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.
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 """
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)
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()
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
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
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
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
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
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 {}
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
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 }
367 def remote_names_now(self) -> set[str]:
368 """The names that live in Home Assistant."""
369 return {*REMOTE_ONLY, *self.remote_names}
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())
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 }
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)."""
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
399 def merge(self, other: _Names) -> None:
400 self.loaded |= other.loaded
401 self.bound |= other.bound
402 self.assigned |= other.assigned
404 def _bind(self, name: str) -> None:
405 self.bound.add(name)
406 if self._depth == 0:
407 self.assigned.add(name)
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)
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])
419 def visit_arg(self, node: ast.arg) -> None:
420 self.bound.add(node.arg)
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
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)
440 def _visit_scope(self, node: ast.AST) -> None:
441 self._depth += 1
442 self.generic_visit(node)
443 self._depth -= 1
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
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
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)}"
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)
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
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"}
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"
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()
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
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)
606def is_quit_call(source: str) -> bool:
607 """True for a bare `quit()` or `exit()` - the standard way to leave a REPL.
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 )