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
« 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.
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.
11Inside a call's brackets, SignatureHelp shows its signature under the
12prompt, decided the same way.
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"""
21from __future__ import annotations
23import asyncio
24import contextlib
25import io
26import keyword
27import tokenize
28from collections.abc import Iterable, Iterator
29from typing import TYPE_CHECKING, Any
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
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)
55if TYPE_CHECKING:
56 from prompt_toolkit import PromptSession
58 from .repl import LiveSession
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]
64# Seconds to wait for Home Assistant while typing, and after Tab.
65REMOTE_WAIT = 0.3
66TAB_WAIT = 2.0
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
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)
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()
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 )
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)
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)
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 )
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)
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
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]
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 ]
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")
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]
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
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."""
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()
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
284 def forget(self) -> None:
285 self._found.clear()
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
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 )
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 )
317 def _local(self, key: str) -> Signature | None:
318 return signature(key, len(key), self.completer.namespace)
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)
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()
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
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)
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
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) :]
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()
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 )