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

1"""REPL sessions: persistent namespaces that execute code on the running event loop. 

2 

3Deliberately free of Home Assistant imports so it can be tested standalone. 

4""" 

5 

6from __future__ import annotations 

7 

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 

32 

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 

38 

39MAX_OUTPUT_CHARS = 1_000_000 

40 

41# Variables bigger than this (as a tree) aren't handed back to the client. 

42MAX_FETCHED_CHARS = 100_000 

43 

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 

49 

50_cell_counter = itertools.count(1) 

51 

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) 

60 

61 

62@dataclass 

63class ExecResult: 

64 """Outcome of running one snippet.""" 

65 

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 

81 

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 } 

93 

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}" 

106 

107 

108@dataclass 

109class Session: 

110 """A named namespace that persists between executions until reset.""" 

111 

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 

120 

121 @property 

122 def busy(self) -> bool: 

123 return self._running is not None and not self._running.done() 

124 

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) 

132 

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 

199 

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) 

216 

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) 

223 

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 ) 

240 

241 

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}>" 

250 

251 

252class _TooBig(Exception): 

253 """The value doesn't fit in MAX_OUTPUT_CHARS as a tree.""" 

254 

255 

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 

272 

273 

274_NOT_PLAIN: Any = object() 

275 

276 

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 

288 

289 

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"]) 

300 

301 

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} 

344 

345 

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 

355 

356 

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) 

364 

365 

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 

418 

419 

420class _Shown: 

421 """A field that an attrs class formats with its own repr= callable.""" 

422 

423 def __init__(self, text: str) -> None: 

424 self.text = text 

425 

426 def __repr__(self) -> str: 

427 return self.text 

428 

429 

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 

433 

434 

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.""" 

440 

441 def __init__(self, tree: Any) -> None: 

442 self.tree = tree 

443 

444 def __repr__(self) -> str: 

445 return _tree_text(self.tree, "") 

446 

447 

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. 

462 

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)) 

471 

472 

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() 

484 

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} 

548 

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) 

558 

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 

578 

579 

580def _cut(text: str) -> dict[str, str]: 

581 return {"t": "repr", "r": text} 

582 

583 

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}" 

593 

594 

595_BRACKETS = { 

596 "dict": ("{", "}"), 

597 "tuple": ("(", ")"), 

598 "set": ("{", "}"), 

599 "frozenset": ("frozenset({", "})"), 

600 "iter": ("<iterator [", "]>"), 

601} 

602 

603 

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}" 

629 

630 

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 

637 

638 

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 

649 

650 

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 """ 

663 

664 def visit_FunctionDef(self, node: ast.FunctionDef) -> ast.FunctionDef: 

665 return node 

666 

667 def visit_Lambda(self, node: ast.Lambda) -> ast.Lambda: 

668 return node 

669 

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 

681 

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 

692 

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) 

706 

707 

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 

718 

719 

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 

729 

730 

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) 

737 

738 return shell_print 

739 

740 

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) 

744 

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") 

774 

775 return shell_help 

776 

777 

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__}") 

781 

782 

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 ) 

792 

793 

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") 

799 

800 

801def _styled(text: str, codes: str, *, color: bool) -> str: 

802 return f"\x1b[{codes}m{text}\x1b[0m" if color and text else text 

803 

804 

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. 

811 

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) 

835 

836 

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) 

882 

883 

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) 

891 

892 

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") 

897 

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) 

904 

905 

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) 

942 

943 

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 

963 

964 

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 

1004 

1005 

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 } 

1031 

1032 

1033class SessionManager: 

1034 """Holds sessions by name; a session lives until reset or process restart.""" 

1035 

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] = {} 

1053 

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 

1065 

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} 

1072 

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 

1078 

1079 def reset(self, name: str) -> bool: 

1080 return self._sessions.pop(name, None) is not None 

1081 

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)] 

1090 

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 ]