Coverage for custom_components/ha_repl_server/session.py: 95%
581 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"""REPL sessions: persistent namespaces that execute code on the running event loop.
3Deliberately free of Home Assistant imports so it can be tested standalone.
4"""
6from __future__ import annotations
8import ast
9import asyncio
10import builtins
11import collections
12import copy
13import dataclasses
14import inspect
15import io
16import itertools
17import linecache
18import math
19import pprint
20import pydoc
21import re
22import reprlib
23import sys
24import textwrap
25import time
26import traceback
27import typing
28from collections.abc import Iterable
29from dataclasses import dataclass, field
30from pathlib import Path
31from typing import Any
33import yaml
34from pygments import format as format_tokens
35from pygments import lex
36from pygments.formatters.terminal import TerminalFormatter
37from pygments.lexers.python import PythonLexer
39MAX_OUTPUT_CHARS = 1_000_000
41# Variables bigger than this (as a tree) aren't handed back to the client.
42MAX_FETCHED_CHARS = 100_000
44# Source lines sent either side of each traceback frame's own.
45_CONTEXT_LINES = 3
46# Frames kept per exception; the middle of anything longer (a runaway
47# recursion, typically) is dropped.
48_MAX_FRAMES = 100
50_cell_counter = itertools.count(1)
52# help() on a hass object documents its *type*; pydoc has no docstrings for core HA
53# classes written with newcomers in mind, so point at the real docs instead. Keyed by
54# fully-qualified class name so it applies no matter what name the object is bound to.
55# This list only grows, and is useful independently of the code around it, hence the
56# data file rather than a dict literal here.
57_DOC_URLS: dict[str, str] = yaml.safe_load(
58 (Path(__file__).parent / "doc_urls.yaml").read_text()
59)
62@dataclass
63class ExecResult:
64 """Outcome of running one snippet."""
66 stdout: str = ""
67 # The trailing expression's value twice over: as plain text, and (unless
68 # it's too big to be worth shipping) as the tree _encode_value() builds
69 # for the client to pretty-print itself.
70 value: str | None = None
71 value_tree: Any = None
72 # The value is a picture show() made, so a client wanting data rather
73 # than a drawing is better served by `value`'s text than by the tree.
74 shown: bool = False
75 # The variables the caller asked after that turned out to be plain data,
76 # each as a tree like value_tree.
77 names: dict[str, Any] = field(default_factory=dict)
78 error: dict[str, Any] | None = None
79 duration: float = 0.0
80 truncated: bool = False
82 def as_dict(self) -> dict[str, Any]:
83 return {
84 "stdout": self.stdout,
85 "value": self.value,
86 "value_tree": self.value_tree,
87 "shown": self.shown,
88 "names": self.names,
89 "error": self.error,
90 "duration": self.duration,
91 "truncated": self.truncated,
92 }
94 def summary(self, limit: int = 200) -> str:
95 """One line saying how a run went, for the log."""
96 if self.error is not None:
97 outcome = f"raised {self.error['type']}: {self.error['message']}"
98 elif self.value is not None:
99 outcome = f"returned {self.value}"
100 else:
101 outcome = "finished"
102 outcome = reprlib.Repr(maxstring=limit).repr(outcome)[1:-1]
103 output = f", {len(self.stdout)} chars of output" if self.stdout else ""
104 cut = ", truncated" if self.truncated else ""
105 return f"{outcome} in {self.duration:.3f}s{output}{cut}"
108@dataclass
109class Session:
110 """A named namespace that persists between executions until reset."""
112 name: str
113 globals_: dict[str, Any]
114 protected: dict[str, Any] = field(default_factory=dict)
115 created: float = field(default_factory=time.time)
116 last_used: float = field(default_factory=time.time)
117 executions: int = 0
118 _lock: asyncio.Lock = field(default_factory=asyncio.Lock)
119 _running: asyncio.Future[Any] | None = None
121 @property
122 def busy(self) -> bool:
123 return self._running is not None and not self._running.done()
125 def cancel(self, reason: str) -> bool:
126 """Stop the code running now, if any - reported to whoever ran it as
127 a CancelledError carrying `reason`. False if nothing was running."""
128 if not self.busy:
129 return False
130 assert self._running is not None
131 return self._running.cancel(reason)
133 async def run(
134 self,
135 source: str,
136 timeout: float | None = None,
137 *,
138 color: bool = False,
139 width: int = 88,
140 auto_await: bool = True,
141 fetch: Iterable[str] = (),
142 ) -> ExecResult:
143 """Execute source in this session, returning captured output and the
144 last value - and, of the variables named in `fetch`, those that hold
145 plain data afterwards."""
146 async with self._lock:
147 self.last_used = time.time()
148 self.executions += 1
149 out = io.StringIO()
150 # hass/obj/open are re-seeded every run, not just at session creation, so a
151 # snippet that does `obj = obj["/mqtt"]["..."]` only shadows them for its own
152 # run - the next command always starts from the real bindings again.
153 self.globals_.update(self.protected)
154 self.globals_["print"] = _capturing_print(out)
155 self.globals_["help"] = _capturing_help(out, color=color, width=width)
156 self.globals_["show"] = show
157 self.globals_["_maybe_await"] = _maybe_await
158 self.globals_["unawait"] = unawait
159 result = ExecResult()
160 start = time.perf_counter()
161 # Its own task, so cancel() can stop it without cancelling the caller.
162 self._running = asyncio.ensure_future(
163 _outcome(self._execute(source, auto_await=auto_await))
164 )
165 try:
166 async with asyncio.timeout(timeout):
167 value, raised = await self._running
168 if raised is not None:
169 raise raised
170 if value is not None:
171 self.globals_["_"] = value
172 result.value = _plain_text(value, width=width)
173 result.value_tree = _encode_value(value)
174 result.shown = type(value) is Shown
175 except asyncio.CancelledError as err:
176 # Cancellation of the caller must propagate, not be reported as
177 # a result; cancel() stopping the code itself is reported.
178 current = asyncio.current_task()
179 if current is not None and current.cancelling():
180 raise
181 result.error = _format_error(err)
182 except BaseException as err: # noqa: BLE001 - report everything, incl. SystemExit
183 result.error = _format_error(err)
184 finally:
185 self._running = None
186 result.duration = time.perf_counter() - start
187 result.stdout = out.getvalue()
188 for name in fetch:
189 if name in self.globals_ and name not in self.protected:
190 tree = _encode_plain(self.globals_[name])
191 if tree is not _NOT_PLAIN:
192 result.names[name] = tree
193 for attr in ("stdout", "value"):
194 text = getattr(result, attr)
195 if text is not None and len(text) > MAX_OUTPUT_CHARS:
196 setattr(result, attr, text[:MAX_OUTPUT_CHARS])
197 result.truncated = True
198 return result
200 async def _execute(self, source: str, *, auto_await: bool = True) -> Any:
201 # Named the way the client names its own cells (local_session.py).
202 filename = f"/ha_repl/cell_{next(_cell_counter)}"
203 # Register the source so tracebacks can show the offending lines.
204 linecache.cache[filename] = (
205 len(source),
206 None,
207 (source if source.endswith("\n") else source + "\n").splitlines(
208 keepends=True
209 ),
210 filename,
211 )
212 tree = ast.parse(source, filename, "exec")
213 if auto_await:
214 tree = _AutoAwait().visit(tree)
215 ast.fix_missing_locations(tree)
217 # Like the interactive interpreter, echo the value of a trailing expression.
218 last_expr = None
219 last_stmt = tree.body[-1] if tree.body else None
220 if isinstance(last_stmt, ast.Expr):
221 tree.body.pop()
222 last_expr = ast.Expression(last_stmt.value)
224 flags = ast.PyCF_ALLOW_TOP_LEVEL_AWAIT
225 # dont_inherit=True: compile() otherwise inherits this module's own
226 # `from __future__ import annotations`, which would make every
227 # annotation in the user's code a plain string - breaking the
228 # FORWARDREF-based signature rendering in _format_signature below.
229 if tree.body:
230 await _run_code(
231 compile(tree, filename, "exec", flags=flags, dont_inherit=True),
232 self.globals_,
233 )
234 if last_expr is None:
235 return None
236 return await _run_code(
237 compile(last_expr, filename, "eval", flags=flags, dont_inherit=True),
238 self.globals_,
239 )
242def _plain_text(value: Any, *, width: int) -> str:
243 """A value as plain text - what a client that can't use the tree
244 _encode_value() builds (too big to send, or a client that predates it)
245 shows instead, and what `ha-repl --json` reports."""
246 try:
247 return pprint.pformat(value, width=width, sort_dicts=False)
248 except Exception as err: # noqa: BLE001 - a broken __repr__ can raise anything
249 return f"<repr-error {str(err)!r}>"
252class _TooBig(Exception):
253 """The value doesn't fit in MAX_OUTPUT_CHARS as a tree."""
256def _encode_value(value: Any) -> Any:
257 """A value as JSON the client can rebuild into something its own
258 pretty-printer lays out the way it would the real thing - the objects
259 themselves never leave this process, so this is as close as the far end
260 gets. None, bools, strings and ordinary ints/floats are sent as
261 themselves and a list as a JSON list; everything else is a `{"t": ...}`
262 node: the other builtin containers by kind, an iterator over a list as
263 the items it has left ("iter"), a dataclass, attrs instance or namedtuple
264 as its class name and fields ("obj"), and whatever is left as just its
265 repr() ("repr"). None when the value is too big to send
266 this way - the caller's plain text then stands in for it.
267 """
268 try:
269 return _encode(value, [MAX_OUTPUT_CHARS], set())
270 except _TooBig, RecursionError:
271 return None
274_NOT_PLAIN: Any = object()
277def _encode_plain(value: Any) -> Any:
278 """The same tree, but only for a value that survives the trip whole -
279 builtin containers (or an iterator over a list), strings, numbers and
280 None, all the way down - and isn't too big to be worth sending.
281 _NOT_PLAIN otherwise.
282 """
283 try:
284 tree = _encode(value, [MAX_FETCHED_CHARS], set())
285 except _TooBig, RecursionError:
286 return _NOT_PLAIN
287 return tree if _is_plain(tree) else _NOT_PLAIN
290def _is_plain(tree: Any) -> bool:
291 if isinstance(tree, list):
292 return all(_is_plain(item) for item in tree)
293 if not isinstance(tree, dict):
294 return True
295 if tree["t"] in ("repr", "obj"):
296 return False
297 if tree["t"] == "dict":
298 return all(_is_plain(k) and _is_plain(v) for k, v in tree["v"])
299 return _is_plain(tree["v"])
302def _encode(value: Any, budget: list[int], ancestors: set[int]) -> Any:
303 kind = type(value)
304 budget[0] -= len(value) if kind is str else 8
305 if budget[0] < 0:
306 raise _TooBig
307 if kind is Shown:
308 return value.tree
309 if value is None or kind is bool or kind is str:
310 return value
311 # Home Assistant's websocket layer serialises with orjson, which has no
312 # integers beyond 64 bits and turns nan/inf into null.
313 if kind is int and -(2**63) <= value < 2**63:
314 return value
315 if kind is float and math.isfinite(value):
316 return value
317 if id(value) in ancestors:
318 return {"t": "repr", "r": "..."}
319 try:
320 parts = _parts(value, kind)
321 except Exception: # noqa: BLE001 - a property or descriptor can raise anything
322 parts = None
323 if parts is None:
324 return {"t": "repr", "r": _encode_repr(value, budget)}
325 tag, name, items = parts
326 ancestors.add(id(value))
327 try:
328 if tag == "dict":
329 encoded: Any = [
330 [_encode(k, budget, ancestors), _encode(v, budget, ancestors)]
331 for k, v in items
332 ]
333 elif tag == "obj":
334 encoded = [[k, _encode(v, budget, ancestors)] for k, v in items]
335 else:
336 encoded = [_encode(item, budget, ancestors) for item in items]
337 finally:
338 ancestors.discard(id(value))
339 if tag == "list":
340 return encoded
341 if tag == "obj":
342 return {"t": "obj", "n": name, "f": encoded}
343 return {"t": tag, "v": encoded}
346def _encode_repr(value: Any, budget: list[int]) -> str:
347 try:
348 text = repr(value)
349 except Exception as err: # noqa: BLE001 - a broken __repr__ can raise anything
350 text = f"<repr-error {str(err)!r}>"
351 budget[0] -= len(text)
352 if budget[0] < 0: 352 ↛ 353line 352 didn't jump to line 353 because the condition on line 352 was never true
353 raise _TooBig
354 return text
357_LIST_ITERATOR: type = type(iter([]))
358_BUILTIN_CONTAINERS: tuple[tuple[str, type], ...] = (
359 ("list", list),
360 ("tuple", tuple),
361 ("set", set),
362 ("frozenset", frozenset),
363)
366def _parts(value: Any, kind: type) -> tuple[str, str, Any] | None:
367 """How a value breaks down into (node tag, class name, items), or None
368 for one that's only meaningful as its repr(). A class with a __repr__ of
369 its own always is: that's its author saying how it should read.
370 """
371 code = getattr(kind.__repr__, "__code__", None)
372 made_by = code.co_filename if code is not None else ""
373 if isinstance(value, tuple) and made_by == collections.__file__:
374 # collections.namedtuple's generated __repr__, so typing.NamedTuple too.
375 return (
376 "obj",
377 kind.__name__,
378 list(zip(getattr(kind, "_fields", ()), value, strict=True)),
379 )
380 if kind is _LIST_ITERATOR:
381 # What it has left to give, read from a copy so it isn't used up.
382 return "iter", "", list(copy.copy(value))
383 if isinstance(value, dict):
384 return ("dict", "", value.items()) if kind.__repr__ is dict.__repr__ else None
385 for tag, base in _BUILTIN_CONTAINERS:
386 if isinstance(value, base):
387 return (tag, "", value) if kind.__repr__ is base.__repr__ else None
388 if dataclasses.is_dataclass(value) and made_by in (
389 dataclasses.__file__,
390 reprlib.__file__,
391 ):
392 return (
393 "obj",
394 kind.__name__,
395 [
396 (f.name, getattr(value, f.name))
397 for f in dataclasses.fields(value)
398 if f.repr
399 ],
400 )
401 attributes = getattr(kind, "__attrs_attrs__", None)
402 if attributes is not None and made_by.startswith("<attrs generated"): 402 ↛ 403line 402 didn't jump to line 403 because the condition on line 402 was never true
403 return (
404 "obj",
405 kind.__name__,
406 [
407 (
408 a.name,
409 _Shown(a.repr(getattr(value, a.name)))
410 if callable(a.repr)
411 else getattr(value, a.name),
412 )
413 for a in attributes
414 if a.repr
415 ],
416 )
417 return None
420class _Shown:
421 """A field that an attrs class formats with its own repr= callable."""
423 def __init__(self, text: str) -> None:
424 self.text = text
426 def __repr__(self) -> str:
427 return self.text
430# The most show() sends back whatever it is asked for: enough for a screen
431# or several, far short of what a registry or `hass.data` holds.
432_SHOW_BUDGET = 50_000
435class Shown:
436 """What show() returns: a picture of an object rather than the object -
437 its attributes and their values, already cut down to size. Echoed as
438 the last expression, it is laid out and coloured by the client like any
439 other value; `tree` is that picture, in _encode_value()'s terms."""
441 def __init__(self, tree: Any) -> None:
442 self.tree = tree
444 def __repr__(self) -> str:
445 return _tree_text(self.tree, "")
448def show(
449 thing: Any,
450 *,
451 private: bool = False,
452 methods: bool = False,
453 depth: int = 1,
454 max_items: int = 30,
455 max_string: int = 200,
456) -> Shown:
457 """Look inside an object: its attributes and their values, laid out
458 one to a line. Names starting with an underscore are left out unless
459 `private`, and methods unless `methods`, which lists them with their
460 signatures. Properties are read, as that is where much of an object's
461 state is.
463 Long values are cut short: a container to its first `max_items`, a
464 string or repr to `max_string` characters, each saying how much was
465 left out. `depth` is how many levels are opened up - with 1, the
466 object's own attributes and what is in any list or dict among them;
467 with 2, the attributes of the objects it holds as well.
468 """
469 look = _Look(private, methods, depth, max_items, max_string)
470 return Shown(look.at(thing, 0))
473class _Look:
474 def __init__(
475 self, private: bool, methods: bool, depth: int, max_items: int, max_string: int
476 ) -> None:
477 self.private = private
478 self.methods = methods
479 self.depth = depth
480 self.max_items = max(max_items, 1)
481 self.max_string = max(max_string, 1)
482 self.budget = _SHOW_BUDGET
483 self.ancestors: set[int] = set()
485 def at(self, value: Any, level: int) -> Any:
486 """The tree for `value`, `level` levels below what show() was given."""
487 kind = type(value)
488 if value is None or kind is bool:
489 return value
490 if kind is int and -(2**63) <= value < 2**63:
491 return value
492 if kind is float and math.isfinite(value):
493 return value
494 if self.budget < 0:
495 return _cut("...")
496 if kind is str:
497 self.budget -= min(len(value), self.max_string)
498 if len(value) <= self.max_string:
499 return value
500 return _cut(f"{value[: self.max_string]!r}+{len(value) - self.max_string}")
501 if kind is _Shown:
502 return self._repr(value)
503 if id(value) in self.ancestors:
504 return _cut("...")
505 try:
506 parts = _parts(value, kind)
507 except Exception: # noqa: BLE001 - a property or descriptor can raise anything
508 parts = None
509 if parts is None:
510 # What show() was given is always opened up, whatever the depth.
511 below = level >= max(self.depth, 1)
512 if below or isinstance(value, (bytes, bytearray)):
513 return self._repr(value)
514 parts = ("obj", kind.__qualname__, self._attributes(value))
515 tag, name, items = parts
516 items = list(items)
517 if level > self.depth:
518 if tag == "obj":
519 return self._repr(value)
520 # Not its repr(): building that for a big container costs as
521 # much as sending it would.
522 return _cut(f"<{kind.__name__} of {len(items)}>")
523 # An object's own attributes are what was asked for, however many.
524 more = 0 if tag == "obj" else len(items) - self.max_items
525 if more > 0:
526 items = items[: self.max_items]
527 self.ancestors.add(id(value))
528 try:
529 if tag == "dict":
530 encoded: Any = [
531 [self.at(k, level + 1), self.at(v, level + 1)] for k, v in items
532 ]
533 if more > 0:
534 encoded.append([_cut("..."), _cut(f"+{more}")])
535 elif tag == "obj":
536 encoded = [[k, self.at(v, level + 1)] for k, v in items]
537 else:
538 encoded = [self.at(item, level + 1) for item in items]
539 if more > 0:
540 encoded.append(_cut(f"... +{more}"))
541 finally:
542 self.ancestors.discard(id(value))
543 if tag == "list":
544 return encoded
545 if tag == "obj":
546 return {"t": "obj", "n": name, "f": encoded}
547 return {"t": tag, "v": encoded}
549 def _repr(self, value: Any) -> Any:
550 try:
551 text = repr(value)
552 except Exception as err: # noqa: BLE001 - a broken __repr__ can raise anything
553 text = f"<repr-error {str(err)!r}>"
554 if len(text) > self.max_string:
555 text = f"{text[: self.max_string]}...+{len(text) - self.max_string}"
556 self.budget -= len(text)
557 return _cut(text)
559 def _attributes(self, value: Any) -> list[tuple[str, Any]]:
560 try:
561 names = dir(value)
562 except Exception: # noqa: BLE001 - a __dir__ of its own can raise anything
563 names = []
564 found: list[tuple[str, Any]] = []
565 for name in names:
566 if name.startswith("__") or (name.startswith("_") and not self.private):
567 continue
568 try:
569 attr = getattr(value, name)
570 except Exception as err: # noqa: BLE001 - a property can raise anything
571 attr = _Shown(f"<{type(err).__name__}: {err}>")
572 if inspect.isroutine(attr) or inspect.isclass(attr):
573 if not self.methods:
574 continue
575 attr = _Shown(_callable_text(name, attr))
576 found.append((name, attr))
577 return found
580def _cut(text: str) -> dict[str, str]:
581 return {"t": "repr", "r": text}
584def _callable_text(name: str, attr: Any) -> str:
585 if inspect.isclass(attr): 585 ↛ 586line 585 didn't jump to line 586 because the condition on line 585 was never true
586 return f"class {attr.__qualname__}"
587 try:
588 signature = str(inspect.signature(attr))
589 except TypeError, ValueError:
590 signature = "(...)"
591 prefix = "async def" if inspect.iscoroutinefunction(attr) else "def"
592 return f"{prefix} {name}{signature}"
595_BRACKETS = {
596 "dict": ("{", "}"),
597 "tuple": ("(", ")"),
598 "set": ("{", "}"),
599 "frozenset": ("frozenset({", "})"),
600 "iter": ("<iterator [", "]>"),
601}
604def _tree_text(tree: Any, indent: str) -> str:
605 """A show() tree as plain text, an attribute or item to a line - for a
606 client that asks for no more than text, as `ha-repl --json` does."""
607 inner = indent + " "
608 if isinstance(tree, list):
609 opening, closing, lines = "[", "]", [_tree_text(i, inner) for i in tree]
610 elif not isinstance(tree, dict):
611 return repr(tree)
612 elif tree["t"] == "repr":
613 return tree["r"]
614 elif tree["t"] == "obj":
615 opening, closing = f"{tree['n']}(", ")"
616 lines = [f"{k}={_tree_text(v, inner)}" for k, v in tree["f"]]
617 elif tree["t"] == "dict":
618 opening, closing = _BRACKETS["dict"]
619 lines = [
620 f"{_tree_text(k, inner)}: {_tree_text(v, inner)}" for k, v in tree["v"]
621 ]
622 else:
623 opening, closing = _BRACKETS[tree["t"]]
624 lines = [_tree_text(i, inner) for i in tree["v"]]
625 if not lines:
626 return opening + closing
627 body = "".join(f"{inner}{line},\n" for line in lines)
628 return f"{opening}\n{body}{indent}{closing}"
631async def _maybe_await(value: Any) -> Any:
632 """Finish a coroutine (or other awaitable) the user forgot to `await`;
633 anything else passes straight through. Used both by the AST rewrite below
634 (an unawaited call nested inside a larger expression) and _run_code's own
635 check (a bare reference to one created earlier, e.g. `c = f(); c`)."""
636 return await value if inspect.isawaitable(value) else value
639def unawait(value: Any) -> Any:
640 """Identity function and auto-await escape hatch: `unawait(f())` returns
641 f()'s bare, un-awaited result (a coroutine, if f is async) - for when
642 that's genuinely wanted, e.g. batching into `asyncio.gather(*[unawait(f())
643 for f in ...])`. Recognised by name in the `_AutoAwait` rewrite below,
644 which skips its whole argument rather than calling this at runtime; this
645 plain version only runs if auto-await itself is off (`auto_await=False`)
646 or `unawait` is used somewhere the rewrite doesn't reach.
647 """
648 return value
651class _AutoAwait(ast.NodeTransformer):
652 """Rewrites every call not already explicitly awaited to go through
653 _maybe_await() first, so `hass.async_foo()` works whether or not the
654 user remembered `await` - including nested inside attribute access
655 (`hass.async_foo().attr`), a comprehension, or an argument list. Leaves
656 nested (synchronous) function/lambda bodies alone: `await` there is a
657 SyntaxError, and those calls run later, not as part of this statement
658 anyway. A class body is left alone for the same first reason. `unawait(expr)` is the escape hatch - its argument is left
659 completely untouched for when the bare coroutine is wanted. Opt out
660 entirely with `auto_await=False` on the exec call (strict mode:
661 forgetting await behaves exactly as in component code).
662 """
664 def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef:
665 return node
667 def visit_Lambda(self, node: ast.Lambda) -> ast.Lambda:
668 return node
670 def visit_ClassDef(self, node: ast.ClassDef) -> ast.ClassDef:
671 # A class body runs synchronously, so nothing evaluated in it can be
672 # awaited: not its own statements, nor its decorators and bases, nor
673 # the decorators and defaults of its methods. Only what's inside an
674 # async method's body can be.
675 for stmt in node.body:
676 if isinstance(stmt, ast.AsyncFunctionDef):
677 stmt.body = [self.visit(inner) for inner in stmt.body]
678 elif isinstance(stmt, ast.ClassDef):
679 self.visit(stmt)
680 return node
682 def visit_Await(self, node: ast.Await) -> ast.Await:
683 # Already explicit: don't double-await this call, but still rewrite
684 # anything nested inside its own arguments.
685 if isinstance(node.value, ast.Call): 685 ↛ 690line 685 didn't jump to line 690 because the condition on line 685 was always true
686 node.value.func = self.visit(node.value.func)
687 node.value.args = [self.visit(a) for a in node.value.args]
688 node.value.keywords = [self.visit(k) for k in node.value.keywords]
689 else:
690 node.value = self.visit(node.value)
691 return node
693 def visit_Call(self, node: ast.Call) -> ast.AST:
694 if (
695 isinstance(node.func, ast.Name)
696 and node.func.id == "unawait"
697 and len(node.args) == 1
698 and not node.keywords
699 ):
700 return node.args[0]
701 self.generic_visit(node)
702 wrapped = ast.Call(
703 func=ast.Name(id="_maybe_await", ctx=ast.Load()), args=[node], keywords=[]
704 )
705 return ast.Await(value=wrapped)
708async def _outcome(run: Any) -> tuple[Any, BaseException | None]:
709 """What `run` returned, or what it raised. A task raising SystemExit or
710 KeyboardInterrupt would take them out of the event loop rather than to
711 whoever awaits it - out of Home Assistant itself."""
712 try:
713 return await run, None
714 except asyncio.CancelledError:
715 raise
716 except BaseException as err: # noqa: BLE001 - handed back, to be reported
717 return None, err
720async def _run_code(code: Any, globals_: dict[str, Any]) -> Any:
721 # No separate "bare coroutine" backstop here: when auto_await is on, the
722 # _AutoAwait rewrite already resolves every call site, and NOT doing so
723 # unconditionally is exactly what `unawait(...)` asks for - a backstop
724 # here would silently defeat it for a trailing `unawait(f())`.
725 result = eval(code, globals_) # nosec B307 - the whole point of a dev shell
726 if code.co_flags & inspect.CO_COROUTINE:
727 result = await result
728 return result
731def _capturing_print(out: io.StringIO):
732 def shell_print(*args: Any, file: Any = None, **kwargs: Any) -> None:
733 # stdout and stderr both come back to the client; other files are honoured.
734 if file is None or file is sys.stdout or file is sys.stderr: 734 ↛ 736line 734 didn't jump to line 736 because the condition on line 734 was always true
735 file = out
736 builtins.print(*args, file=file, **kwargs)
738 return shell_print
741def _capturing_help(out: io.StringIO, *, color: bool, width: int):
742 # A fresh Helper per call, output redirected into the same buffer as print().
743 helper = pydoc.Helper(input=io.StringIO(), output=out)
745 def shell_help(*args: Any, full: bool = False) -> None:
746 if not args:
747 # help()'s real interactive loop (reading "help> " commands) spins the
748 # CPU forever on this Python version when its input isn't a real tty -
749 # verified in isolation, nothing project-specific about it - and there's no
750 # live stdin to browse with anyway over this request/response API. Show
751 # the same intro banner and stop there instead of entering interact().
752 helper.intro()
753 out.write(
754 "\nGet help on any object, with links for known Home Assistant classes\n"
755 )
756 out.write("\ne.g. help(hass) or help(obj['/sun/sun']).\n")
757 out.write(
758 "\nhelp(thing, full=True) is Python's own full help page: every "
759 "method's docstring, special methods, inherited members and data "
760 "descriptors.\n"
761 )
762 return
763 if len(args) > 1: 763 ↛ 764line 763 didn't jump to line 764 because the condition on line 763 was never true
764 helper(*args) # raises the same TypeError real help() would
765 return
766 (thing,) = args
767 if _is_summarisable(thing) and not full:
768 out.write(_class_summary(thing, color=color, width=width))
769 else:
770 helper(thing)
771 url = _doc_url(thing)
772 if url: 772 ↛ 773line 772 didn't jump to line 773 because the condition on line 772 was never true
773 out.write(f"\nSee also: {url}\n")
775 return shell_help
778def _doc_url(obj: Any) -> str | None:
779 cls = obj if inspect.isclass(obj) else type(obj)
780 return _DOC_URLS.get(f"{cls.__module__}.{cls.__qualname__}")
783def _is_summarisable(obj: Any) -> bool:
784 """Classes and plain instances get the condensed summary below; modules,
785 functions/methods, and primitives go through pydoc as usual (already short)."""
786 return not (
787 obj is None
788 or isinstance(obj, (bool, int, float, complex, str, bytes))
789 or inspect.ismodule(obj)
790 or inspect.isroutine(obj)
791 )
794_SIGNATURE_LEXER = PythonLexer()
795# The 16 named ANSI colours rather than a truecolor style: they follow the
796# terminal's own palette, and travel through a websocket/terminal pair more
797# predictably.
798_SIGNATURE_FORMATTER = TerminalFormatter(bg="dark")
801def _styled(text: str, codes: str, *, color: bool) -> str:
802 return f"\x1b[{codes}m{text}\x1b[0m" if color and text else text
805def _signature_line(line: str, *, color: bool, width: int) -> str:
806 """A class/method signature, syntax-highlighted (pygments' Python lexer
807 tokenizes it fine even though, as a bare "name(args) -> ret" fragment,
808 it isn't valid standalone Python) - so type annotations, defaults and
809 operators get real highlighting instead of being one flat-coloured
810 string.
812 Home Assistant's own methods lean hard on generics (Callable[[Unpack[
813 _Ts]], ...]), so a real signature routinely runs past any reasonable
814 width - wrapped here with a hanging indent *before* lexing (so the
815 inserted newlines/spaces are just more whitespace tokens to pygments)
816 rather than left to the terminal, which breaks at its own width with no
817 indent at all and reads as a jumble of unrelated lines once there are
818 dozens of methods back to back.
819 """
820 wrapped = "\n".join(
821 textwrap.wrap(
822 line,
823 width=max(width, 20),
824 subsequent_indent=" ",
825 break_long_words=False,
826 break_on_hyphens=False,
827 )
828 )
829 if not color:
830 return wrapped
831 tokens = list(lex(wrapped, _SIGNATURE_LEXER))
832 while tokens and not tokens[-1][1].strip():
833 tokens.pop() # pygments always appends a trailing "\n" token
834 return format_tokens(tokens, _SIGNATURE_FORMATTER)
837def _class_summary(thing: Any, *, color: bool, width: int) -> str:
838 """A class's full pydoc page repeats its docstring once per method, which
839 balloons for a class like HomeAssistant with hundreds of methods. A method's
840 own docstring is one `help(hass.the_method)` away, so here we only show the
841 class docstring, the constructor signature, and the methods' names and
842 signatures (no live attribute values either - that's what `hass.foo` is for).
843 """
844 cls = thing if inspect.isclass(thing) else type(thing)
845 header = (
846 f"Help on class {cls.__qualname__} in module {cls.__module__}:"
847 if inspect.isclass(thing)
848 else f"Help on {cls.__qualname__} object in module {cls.__module__}:"
849 )
850 parts = [_styled(header, "1", color=color), ""]
851 doc = inspect.getdoc(cls)
852 if doc:
853 parts += [doc, ""]
854 # A constructor "returning Self" is implied, not useful to state.
855 ctor_sig = f"{cls.__qualname__}{_format_signature(cls, drop_return=(typing.Self,))}"
856 parts.append(_signature_line(ctor_sig, color=color, width=width))
857 method_names = sorted(
858 name
859 for name in dir(cls)
860 if not name.startswith("_") and _is_plain_method(getattr(cls, name, None))
861 )
862 if method_names:
863 parts += ["", _styled("Methods:", "1;4", color=color)]
864 for name in method_names:
865 sig = _format_signature(getattr(cls, name), drop_self=True)
866 parts.append(_signature_line(f" {name}{sig}", color=color, width=width))
867 property_names = sorted(
868 name
869 for name in dir(cls)
870 if not name.startswith("_") and isinstance(getattr(cls, name, None), property)
871 )
872 if property_names:
873 parts += ["", _styled("Properties:", "1;4", color=color)]
874 for name in property_names:
875 doc = inspect.getdoc(getattr(cls, name))
876 summary = doc.strip().splitlines()[0] if doc else ""
877 line = f" {name}" + (f" - {summary}" if summary else "")
878 parts.append(
879 textwrap.fill(line, width=max(width, 20), subsequent_indent=" ")
880 )
881 return "\n".join(parts)
884def _is_plain_method(obj: Any) -> bool:
885 # inspect.isroutine() also matches any non-data descriptor (defines __get__ but
886 # not __set__) via its ismethoddescriptor() check - which, alongside genuine
887 # methods, catches cached_property (both functools's and propcache's, used all
888 # over Home Assistant's own entity classes), listing a read-only property as a
889 # fake "name(...)" method. isfunction/ismethod is the properly narrow check.
890 return inspect.isfunction(obj) or inspect.ismethod(obj)
893# Matches a dotted path ending in an identifier, e.g. "homeassistant.core.State"
894# or the "collections.abc.Coroutine" inside a bigger type expression - used to
895# shorten type annotations down to just the class name.
896_DOTTED_NAME = re.compile(r"\b(?:[A-Za-z_]\w*\.)+([A-Za-z_]\w*)\b")
898# Python 3.14+ (PEP 649): __annotations__ access eagerly evaluates every annotation
899# by default, which raises for names only imported under TYPE_CHECKING - common in
900# HA's own codebase (e.g. Entity methods taking an "EntityPlatform"). FORWARDREF
901# format resolves what it can and leaves the rest as an inert placeholder instead
902# of raising. Not available before 3.14, hence the getattr dance.
903_FORWARDREF_FORMAT = getattr(getattr(inspect, "Format", None), "FORWARDREF", None)
906def _format_signature(
907 target: Any, *, drop_self: bool = False, drop_return: tuple = ()
908) -> str:
909 """Render target's signature, trimmed down for a quick overview:
910 self dropped (when `drop_self`), a void or otherwise uninformative return
911 annotation dropped (`drop_return`), type annotations shortened to their bare
912 class name, and no padding around `=` for default values.
913 """
914 sig = None
915 if _FORWARDREF_FORMAT is not None: 915 ↛ 920line 915 didn't jump to line 920 because the condition on line 915 was always true
916 try:
917 sig = inspect.signature(target, annotation_format=_FORWARDREF_FORMAT)
918 except Exception: # noqa: BLE001 - fall through to the attempts below
919 sig = None
920 if sig is None: 920 ↛ 921line 920 didn't jump to line 921 because the condition on line 920 was never true
921 try:
922 sig = inspect.signature(target, eval_str=True)
923 except Exception: # noqa: BLE001 - unresolvable forward refs can raise almost
924 # anything (NameError, AttributeError, ...); a signature with raw/partial
925 # annotations is still better than losing the method entirely.
926 try:
927 sig = inspect.signature(target)
928 except TypeError, ValueError:
929 return "(...)"
930 params = list(sig.parameters.values())
931 if drop_self and params and params[0].name == "self":
932 sig = sig.replace(parameters=params[1:])
933 ret = sig.return_annotation
934 if ret is not sig.empty and (
935 ret is None or ret is type(None) or any(ret is d for d in drop_return)
936 ):
937 sig = sig.replace(return_annotation=sig.empty)
938 # Annotations are plain strings in a module using `from __future__ import
939 # annotations` - shown as written, not as quoted strings.
940 text = _DOTTED_NAME.sub(r"\1", sig.format(quote_annotation_strings=False))
941 return re.sub(r"\s*=\s*", "=", text)
944def _format_error(err: BaseException) -> dict[str, Any]:
945 """An error as data: its type and message, the standard traceback text,
946 and - for the client to draw a fuller traceback from - each exception in
947 its cause/context chain as "stacks", outermost (the one raised) first.
948 """
949 tb = err.__traceback__
950 # Drop the frames belonging to this module so the traceback starts at user code.
951 while tb is not None and tb.tb_frame.f_code.co_filename == __file__:
952 tb = tb.tb_next
953 error: dict[str, Any] = {"type": type(err).__name__, "message": str(err)}
954 if isinstance(err, SyntaxError):
955 # No frames worth showing for this one, just the offending line and caret.
956 error["traceback"] = "".join(traceback.format_exception_only(type(err), err))
957 return error
958 error["traceback"] = "".join(traceback.format_exception(type(err), err, tb))
959 stacks = _stacks(err, tb)
960 if stacks is not None:
961 error["stacks"] = stacks
962 return error
965def _stacks(err: BaseException, tb: Any) -> list[dict[str, Any]] | None:
966 """None if there's an exception group anywhere in the chain: the
967 standard traceback text already lays those out as the tree they are."""
968 stacks: list[dict[str, Any]] = []
969 seen: set[int] = set()
970 is_cause = False
971 current: BaseException | None = err
972 while current is not None and id(current) not in seen:
973 if isinstance(current, BaseExceptionGroup):
974 return None
975 seen.add(id(current))
976 frames = []
977 while tb is not None:
978 if tb.tb_frame.f_code.co_filename != __file__:
979 frames.append(_frame(tb))
980 tb = tb.tb_next
981 hidden = max(len(frames) - _MAX_FRAMES, 0)
982 if hidden:
983 del frames[_MAX_FRAMES // 2 : _MAX_FRAMES // 2 + hidden]
984 try:
985 message = str(current)
986 except Exception: # noqa: BLE001 - a broken __str__ can raise anything
987 message = "<exception str() failed>"
988 stacks.append({
989 "type": type(current).__name__,
990 "message": message,
991 "is_cause": is_cause,
992 "notes": [str(n) for n in getattr(current, "__notes__", None) or ()],
993 "frames": frames,
994 "hidden": hidden,
995 })
996 if current.__cause__ is not None:
997 current, is_cause = current.__cause__, True
998 elif not current.__suppress_context__: 998 ↛ 1001line 998 didn't jump to line 1001 because the condition on line 998 was always true
999 current, is_cause = current.__context__, False
1000 else:
1001 break
1002 tb = current.__traceback__ if current is not None else None
1003 return stacks
1006def _frame(tb: Any) -> dict[str, Any]:
1007 code = tb.tb_frame.f_code
1008 lineno = tb.tb_lineno
1009 # Where in the line(s) it went wrong, for the client to mark. tb_lasti,
1010 # not the frame's own f_lasti: an outer frame has usually moved on (into
1011 # an except block, say) by the time anyone looks.
1012 start_line, end_line, start_col, end_col = next(
1013 itertools.islice(code.co_positions(), tb.tb_lasti // 2, None),
1014 (None, None, None, None),
1015 )
1016 position = (
1017 None
1018 if None in (start_line, end_line, start_col, end_col)
1019 else [start_line, start_col, end_line, end_col]
1020 )
1021 first = max(lineno - _CONTEXT_LINES, 1)
1022 last = max(lineno, min(end_line or lineno, lineno + 10)) + _CONTEXT_LINES
1023 return {
1024 "file": code.co_filename,
1025 "line": lineno,
1026 "name": code.co_name,
1027 "first": first,
1028 "source": linecache.getlines(code.co_filename)[first - 1 : last],
1029 "position": position,
1030 }
1033class SessionManager:
1034 """Holds sessions by name; a session lives until reset or process restart."""
1036 def __init__(
1037 self,
1038 bindings: dict[str, Any],
1039 features: frozenset[str] = frozenset(),
1040 *,
1041 complete_limit: int = 500,
1042 complete_budget: float = 0.5,
1043 unavailable: dict[str, str] | None = None,
1044 ) -> None:
1045 self._bindings = bindings
1046 self._features = features
1047 # Most items, and seconds, ha_repl_server/complete spends on one answer.
1048 self.complete_limit = complete_limit
1049 self.complete_budget = complete_budget
1050 # Features switched on, but which couldn't be loaded - and why.
1051 self.unavailable = unavailable or {}
1052 self._sessions: dict[str, Session] = {}
1054 def get(self, name: str) -> Session:
1055 if (session := self._sessions.get(name)) is None:
1056 globals_ = {
1057 "__name__": "__ha_repl__",
1058 "__builtins__": builtins,
1059 **self._bindings,
1060 }
1061 session = self._sessions[name] = Session(
1062 name, globals_, dict(self._bindings)
1063 )
1064 return session
1066 def namespace(self, name: str) -> dict[str, Any]:
1067 """A copy of what session `name` holds, or of the bindings alone if
1068 there is no such session - without creating it."""
1069 if (session := self._sessions.get(name)) is None:
1070 return {"__builtins__": builtins, **self._bindings}
1071 return {**session.globals_, **session.protected}
1073 def has_feature(self, name: str) -> bool:
1074 """Whether an optional capability that isn't a session binding is
1075 switched on - "sql" (the integration's expose_sql option) is served
1076 by its own websocket commands, not through exec."""
1077 return name in self._features
1079 def reset(self, name: str) -> bool:
1080 return self._sessions.pop(name, None) is not None
1082 def cancel(self, name: str | None, reason: str) -> list[str]:
1083 """Stop what's running in session `name`, or in every session if
1084 None, returning the names of those that had something to stop."""
1085 if name is None:
1086 sessions = list(self._sessions.values())
1087 else:
1088 sessions = [s] if (s := self._sessions.get(name)) else []
1089 return [s.name for s in sessions if s.cancel(reason)]
1091 def describe(self) -> list[dict[str, Any]]:
1092 return [
1093 {
1094 "name": s.name,
1095 "created": s.created,
1096 "last_used": s.last_used,
1097 "executions": s.executions,
1098 "variables": sorted(
1099 k
1100 for k in s.globals_
1101 if not k.startswith("__")
1102 and k not in ("print", "help", "show", "_maybe_await", "unawait")
1103 ),
1104 }
1105 for s in self._sessions.values()
1106 ]