Coverage for src/homeassistant_repl/completer.py: 93%

256 statements  

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

1"""Tab completion in the shells - see RFC 0002. 

2 

3Local code is completed by complete.py's walk, which runs nothing, and by 

4jedi where the walk can't follow the expression (a loop variable, an 

5import). In live mode, a statement that reads anything living in Home 

6Assistant is completed there instead, by ha_repl_server/complete running 

7the same walk against the server session - the rule LiveSession.run() uses 

8to decide where it runs, so the two can't disagree. A bare name completes 

9from both sides at once. 

10 

11Inside a call's brackets, SignatureHelp shows its signature under the 

12prompt, decided the same way. 

13 

14Completion pops up while typing after a `.`, inside a key or path string, 

15and after two letters of a name; Tab always asks. A remote answer slower 

16than REMOTE_WAIT shows nothing rather than holding up the prompt, and is 

17kept for the next keystroke - answers are kept until the next command runs, 

18and narrowed locally as more is typed. 

19""" 

20 

21from __future__ import annotations 

22 

23import asyncio 

24import contextlib 

25import io 

26import keyword 

27import tokenize 

28from collections.abc import Iterable, Iterator 

29from typing import TYPE_CHECKING, Any 

30 

31import jedi # type: ignore[import-untyped] 

32from prompt_toolkit.application.current import get_app 

33from prompt_toolkit.buffer import Buffer 

34from prompt_toolkit.completion import CompleteEvent, Completer, Completion 

35from prompt_toolkit.document import Document 

36from prompt_toolkit.formatted_text import StyleAndTextTuples 

37 

38from .client import HaReplError, client_version 

39from .complete import ( 

40 Doc, 

41 Item, 

42 Signature, 

43 Source, 

44 call_at, 

45 complete, 

46 context_start, 

47 describe, 

48 kind_at, 

49 matches, 

50 rank, 

51 signature, 

52 source, 

53) 

54 

55if TYPE_CHECKING: 

56 from prompt_toolkit import PromptSession 

57 

58 from .repl import LiveSession 

59 

60# The same rule as complete.py's, for jedi: nothing is evaluated (though 

61# jedi still calls __getattr__ and __dir__ - see RFC 0002's Step 0 Findings). 

62jedi.settings.allow_unsafe_interpreter_executions = False # ty: ignore[invalid-assignment] 

63 

64# Seconds to wait for Home Assistant while typing, and after Tab. 

65REMOTE_WAIT = 0.3 

66TAB_WAIT = 2.0 

67 

68 

69def names_read(text: str) -> set[str]: 

70 """The names in `text`, which may well not be finished Python.""" 

71 names: set[str] = set() 

72 try: 

73 for token in tokenize.generate_tokens(io.StringIO(text).readline): 

74 if token.type == tokenize.NAME and not keyword.iskeyword(token.string): 

75 names.add(token.string) 

76 except tokenize.TokenError, SyntaxError: 

77 pass # what's typed so far still counts 

78 return names 

79 

80 

81class HaCompleter(Completer): 

82 def __init__( 

83 self, namespace: dict[str, Any], live: LiveSession | None = None 

84 ) -> None: 

85 self.namespace = namespace 

86 self.live = live 

87 # Whether the server can complete: False for one older than this. 

88 self.remote = live is not None 

89 self._answers: dict[str, dict[str, Any]] = {} 

90 self._asking: dict[str, asyncio.Future[dict[str, Any] | None]] = {} 

91 self.signatures = SignatureHelp(self) 

92 

93 def forget(self) -> None: 

94 """Drop what Home Assistant said - after a command, which may have 

95 changed what's there.""" 

96 self._answers.clear() 

97 self.signatures.forget() 

98 

99 async def locate(self, expression: str) -> Source | None: 

100 """Where the source of what `expression` names is, for `thing??` - 

101 asked of Home Assistant if that's where it lives.""" 

102 if self.asks_remotely(expression + "."): 102 ↛ 105line 102 didn't jump to line 105 because the condition on line 102 was always true

103 found = await self._ask_about("source", expression) 

104 return Source(**found) if found else None 

105 return source( 

106 expression, self.namespace, {"homeassistant_repl": client_version()} 

107 ) 

108 

109 async def describe(self, expression: str) -> Doc | None: 

110 """What `expression` names, for Ctrl-Space and `ha-repl inspect` - 

111 asked of Home Assistant if that's where it lives.""" 

112 if self.asks_remotely(expression + "."): 

113 found = await self._ask_about("doc", expression) 

114 return Doc(**found) if found else None 

115 return describe(expression, self.namespace) 

116 

117 async def _ask_about(self, kind: str, expression: str) -> dict[str, Any] | None: 

118 assert self.live is not None 

119 try: 

120 answer = await self.live.client.call( 

121 "ha_repl_server/complete", 

122 kind=kind, 

123 session=self.live.session_name, 

124 source=expression, 

125 cursor=len(expression), 

126 ) 

127 except Exception: # noqa: BLE001 - not answered, for whatever reason 

128 return None 

129 return answer.get(kind) 

130 

131 def asks_remotely(self, text: str) -> bool: 

132 return ( 

133 self.live is not None and self.remote and self.live.completes_remotely(text) 

134 ) 

135 

136 def get_completions( 

137 self, document: Document, complete_event: CompleteEvent 

138 ) -> Iterable[Completion]: 

139 """Local only, and waiting for jedi: for a caller that can't wait 

140 asynchronously. The shells use get_completions_async.""" 

141 text = document.text_before_cursor 

142 if (found := self._walk(document)) is not None: 

143 yield from found 

144 else: 

145 yield from self._jedi(document) 

146 if kind_at(text) == "name": 

147 yield from self._remote_names(text) 

148 

149 async def get_completions_async( 

150 self, document: Document, complete_event: CompleteEvent 

151 ) -> Any: 

152 text = document.text_before_cursor 

153 if not _worth_asking(text, complete_event): 

154 return 

155 if self.asks_remotely(text): 

156 wait = TAB_WAIT if complete_event.completion_requested else REMOTE_WAIT 

157 answer = await self._ask_remote(text, wait) 

158 if answer is not None: 

159 for completion in answer: 

160 yield completion 

161 return 

162 # Not something Home Assistant could follow: try here instead. 

163 if (found := self._walk(document)) is None: 

164 found = await asyncio.to_thread(self._jedi, document) 

165 for completion in found: 

166 yield completion 

167 if kind_at(text) == "name": 

168 for completion in self._remote_names(text): 

169 yield completion 

170 

171 def _walk(self, document: Document) -> list[Completion] | None: 

172 found = complete(document.text, document.cursor_position, self.namespace) 

173 if found is None: 

174 return None 

175 return [_completion(item, found.replace) for item in found.items] 

176 

177 def _jedi(self, document: Document) -> list[Completion]: 

178 # Asked with the word being typed left out, since jedi only matches 

179 # the start of a name, and narrowed here by matches(). 

180 typed = _typed(document.text_before_cursor) 

181 start = document.cursor_position - len(typed) 

182 bare = Document( 

183 document.text[:start] + document.text[document.cursor_position :], start 

184 ) 

185 try: 

186 script = jedi.Interpreter(bare.text, [self.namespace]) 

187 found = script.complete( 

188 bare.cursor_position_row + 1, bare.cursor_position_col 

189 ) 

190 except Exception: # noqa: BLE001 - jedi failing is nothing to complete 

191 return [] 

192 found = sorted( 

193 (c for c in found if matches(c.name, typed)), 

194 key=lambda c: rank(c.name, typed), 

195 ) 

196 return [ 

197 Completion(c.name_with_symbols, -len(typed), display_meta=c.type) 

198 for c in found 

199 ] 

200 

201 def _remote_names(self, text: str) -> Iterator[Completion]: 

202 """A bare name can be one living in Home Assistant too.""" 

203 if self.live is None: 

204 return 

205 typed = _typed(text) 

206 for name in sorted(self.live.remote_names_now() - set(self.namespace)): 

207 if matches(name, typed): 

208 yield Completion(name, -len(typed), display_meta="HA") 

209 

210 async def _ask_remote(self, text: str, wait: float) -> list[Completion] | None: 

211 """Home Assistant's completions, None if it couldn't follow the 

212 expression (or didn't answer in time, or can't complete at all).""" 

213 typed = _typed(text) 

214 # Ask about the context alone, and narrow by what's typed here. 

215 source = text[: len(text) - len(typed)] + ("_" if typed.startswith("_") else "") 

216 answer = self._answers.get(source) 

217 if answer is None: 

218 asking = self._asking.get(source) 

219 if asking is None: 219 ↛ 224line 219 didn't jump to line 224 because the condition on line 219 was always true

220 asking = self._asking[source] = asyncio.ensure_future( 

221 self._fetch(source) 

222 ) 

223 asking.add_done_callback(lambda _: self._asking.pop(source, None)) 

224 done, _ = await asyncio.wait({asking}, timeout=wait) 

225 if not done: 

226 return [] 

227 answer = asking.result() 

228 if answer is None: 

229 return None 

230 if answer["incomplete"] and typed: 230 ↛ 232line 230 didn't jump to line 232 because the condition on line 230 was never true

231 # More than one answer holds: ask about exactly what's typed. 

232 answer = await self._fetch(text, keep=False) 

233 if answer is None: 

234 return None 

235 typed = "" 

236 if not answer["resolved"]: 

237 return None 

238 items = [ 

239 Item(**item) for item in answer["items"] if matches(item["label"], typed) 

240 ] 

241 if typed: 

242 items.sort(key=lambda i: (i.kind != "parameter", *rank(i.label, typed))) 

243 return [_completion(item, len(_typed(text)), remote=True) for item in items] 

244 

245 async def _fetch(self, source: str, *, keep: bool = True) -> dict[str, Any] | None: 

246 assert self.live is not None 

247 try: 

248 answer = await self.live.client.call( 

249 "ha_repl_server/complete", 

250 session=self.live.session_name, 

251 source=source, 

252 cursor=len(source), 

253 ) 

254 except HaReplError as err: 

255 if err.code == "unknown_command": 255 ↛ 257line 255 didn't jump to line 257 because the condition on line 255 was always true

256 self.remote = False 

257 return None 

258 except Exception: # noqa: BLE001 - a lost connection is no completions 

259 return None 

260 if keep: 260 ↛ 262line 260 didn't jump to line 262 because the condition on line 260 was always true

261 self._answers[source] = answer 

262 return answer 

263 

264 

265class SignatureHelp: 

266 """The signature of the call being typed, under the prompt, with the 

267 argument the cursor is on in bold - shown only inside a call's brackets. 

268 Found locally, or by Home Assistant by the same rule as completion, and 

269 kept, by the call, until the next command runs.""" 

270 

271 def __init__(self, completer: HaCompleter) -> None: 

272 self.completer = completer 

273 self._session: PromptSession[str] | None = None 

274 # By the text up to the call's `(`; (signature, from Home Assistant) 

275 self._found: dict[str, tuple[Signature | None, bool]] = {} 

276 self._asking: set[str] = set() 

277 self._fetches: set[asyncio.Task[None]] = set() 

278 

279 def attach(self, session: PromptSession[str]) -> None: 

280 self._session = session 

281 session.default_buffer.on_text_changed += self._moved 

282 session.default_buffer.on_cursor_position_changed += self._moved 

283 

284 def forget(self) -> None: 

285 self._found.clear() 

286 

287 def _moved(self, buffer: Buffer) -> None: 

288 assert self._session is not None 

289 inside = call_at(buffer.document.text_before_cursor) is not None 

290 self._session.bottom_toolbar = self.toolbar if inside else None 

291 

292 def toolbar(self) -> StyleAndTextTuples: 

293 assert self._session is not None 

294 return self.render( 

295 self._session.default_buffer.document.text_before_cursor, 

296 get_app().output.get_size().columns, 

297 ) 

298 

299 def render(self, text: str, width: int | None = None) -> StyleAndTextTuples: 

300 """The toolbar for `text`: nothing yet if Home Assistant hasn't 

301 answered, the toolbar being redrawn when it does.""" 

302 if (call := call_at(text)) is None: 

303 return [] 

304 key = text[: call[0] + 1] 

305 if key not in self._found: 

306 if self.completer.asks_remotely(key): 

307 self._ask(key) 

308 return [] 

309 self._found[key] = (self._local(key), False) 

310 found, remote = self._found[key] 

311 if found is None: 

312 return [] 

313 return _formatted( 

314 found, found.active(call[1], call[2]), remote=remote, width=width 

315 ) 

316 

317 def _local(self, key: str) -> Signature | None: 

318 return signature(key, len(key), self.completer.namespace) 

319 

320 def _ask(self, key: str) -> None: 

321 if key in self._asking: 321 ↛ 322line 321 didn't jump to line 322 because the condition on line 321 was never true

322 return 

323 self._asking.add(key) 

324 fetch = asyncio.ensure_future(self._fetch(key)) 

325 self._fetches.add(fetch) 

326 fetch.add_done_callback(self._fetches.discard) 

327 

328 async def _fetch(self, key: str) -> None: 

329 live = self.completer.live 

330 assert live is not None 

331 try: 

332 answer = await live.client.call( 

333 "ha_repl_server/complete", 

334 kind="signature", 

335 session=live.session_name, 

336 source=key, 

337 cursor=len(key), 

338 ) 

339 except Exception: # noqa: BLE001 - remembered, so not asked again on every redraw 

340 answer = {"signature": None} 

341 finally: 

342 self._asking.discard(key) 

343 if answer["signature"] is not None: 

344 self._found[key] = (Signature.from_dict(answer["signature"]), True) 

345 else: 

346 # Not something Home Assistant could follow: try here instead. 

347 self._found[key] = (self._local(key), False) 

348 with contextlib.suppress(Exception): 

349 get_app().invalidate() 

350 

351 

352def _formatted( 

353 found: Signature, active: int | None, *, remote: bool, width: int | None = None 

354) -> StyleAndTextTuples: 

355 """One line: wider than `width`, the parameters before the one being 

356 typed are left out, so it stays in view, and the end is cut.""" 

357 parts: StyleAndTextTuples = [("class:signature.ha", "HA ")] if remote else [] 

358 parts.append(("class:signature", f"{found.name}(")) 

359 kinds = [p.kind for p in found.params] 

360 first = 0 

361 if width is not None and active is not None: 

362 while first < active and _length(found, first, active) > width: 

363 first += 1 

364 if first: 

365 parts.append(("class:signature", "…")) 

366 for i, param in enumerate(found.params): 

367 if i < first: 

368 continue 

369 if i: 

370 parts.append(("class:signature", ", ")) 

371 if ( 

372 param.kind == "KEYWORD_ONLY" 

373 and "VAR_POSITIONAL" not in kinds[:i] 

374 and (i == 0 or kinds[i - 1] != "KEYWORD_ONLY") 

375 ): 

376 parts.append(("class:signature", "*, ")) 

377 style = "class:signature.active" if i == active else "class:signature" 

378 parts.append((style, param.text)) 

379 if param.kind == "POSITIONAL_ONLY" and ( 

380 i + 1 == len(kinds) or kinds[i + 1] != "POSITIONAL_ONLY" 

381 ): 

382 parts.append(("class:signature", ", /")) 

383 parts.append(("class:signature", ")")) 

384 if found.returns: 

385 parts.append(("class:signature", f" -> {found.returns}")) 

386 if found.doc: 

387 parts.append(("class:signature.doc", f" {found.doc}")) 

388 if width is not None: 

389 parts = _cut(parts, width) 

390 return parts 

391 

392 

393def _length(found: Signature, first: int, active: int) -> int: 

394 """How far the line runs to the end of the active parameter, starting 

395 at parameter `first`.""" 

396 shown = found.params[first : active + 1] 

397 return len(found.name) + 6 + sum(len(p.text) + 4 for p in shown) 

398 

399 

400def _cut(parts: StyleAndTextTuples, width: int) -> StyleAndTextTuples: 

401 cut: StyleAndTextTuples = [] 

402 room = width - 1 

403 for fragment in parts: 

404 style, text = fragment[0], fragment[1] 

405 if len(text) > room: 

406 cut.append((style, text[: max(room - 1, 0)] + "…")) 

407 break 

408 cut.append((style, text)) 

409 room -= len(text) 

410 return cut 

411 

412 

413def _typed(text: str) -> str: 

414 """The part of the word or key being completed that's already typed.""" 

415 return text[context_start(text) :] 

416 

417 

418def _worth_asking(text: str, event: CompleteEvent) -> bool: 

419 """Tab always; while typing, only once there's something to go on.""" 

420 if event.completion_requested: 

421 return True 

422 kind = kind_at(text) 

423 if kind != "name": 

424 return True 

425 typed = _typed(text) 

426 return len(typed) >= 2 and not typed[0].isdigit() 

427 

428 

429def _completion(item: Item, replace: int, *, remote: bool = False) -> Completion: 

430 meta = item.detail or item.kind 

431 return Completion( 

432 item.label, -replace, display_meta=f"HA {meta}" if remote else meta 

433 )