Coverage for src/homeassistant_repl/apirepl.py: 0%
46 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"""API client mode's interactive shell: same line editing/history as
2repl.py, but code runs right here (LocalSession) - no `hass`, no
3ha_repl_server/exec call, no Marketplace component required on the HA side at
4all. `obj` is bound the same name as live mode, just to an ApiObjTree
5instead of the live ObjTree, so a snippet that only touches `obj` runs
6unchanged in either mode. `hass_api` is bound the same way - an
7already-connected homeassistant_api.AsyncClient, not a function to call.
9The cache refresh happens here, between prompts, not inside ApiObjTree's own
10Mapping methods - see api_objtree.py's module docstring for why (asyncio
11reentrancy: this loop is the one safe place that's both async and knows when
12"between commands" is).
13"""
15from __future__ import annotations
17import sys
18from collections.abc import Sequence
19from pathlib import Path
21from .api_objtree import ApiObjTree, Cache
22from .client import Client, HaReplError, client_version
23from .completer import HaCompleter
24from .editor import python_prompt, run_interruptibly
25from .local_session import LocalSession
26from .plugins import bind_context, bind_rebind, local_runner, run_plugins
27from .repl import banner_address, banner_plugins, is_quit_call
28from .rest import hass_api
29from .shellhelp import answer, help_request
31HISTORY = Path.home() / ".ha_repl_api_history"
34async def run_api_repl(
35 client: Client,
36 ttl: float,
37 *,
38 auto_await: bool = True,
39 server_name: str | None = None,
40 plugins: Sequence[Path] = (),
41) -> int:
42 cache = Cache(client, ttl)
43 await cache.refresh()
44 try:
45 rest_client = await hass_api(client.url, client.token)
46 except HaReplError as err:
47 print(f"ha-repl: hass_api unavailable: {err}", file=sys.stderr)
48 rest_client = None
50 session = LocalSession(
51 {"obj": ApiObjTree(cache), "hass_api": rest_client}, auto_await=auto_await
52 )
54 completer = HaCompleter(session.globals_)
55 prompt = python_prompt(HISTORY, completer)
56 bind_context(session.globals_, "api", server_name)
57 bind_rebind(session.globals_, plugins, local_runner(session))
58 loaded = await run_plugins(plugins, local_runner(session))
59 print(
60 f"API connected to {banner_address(client.url, server_name)}. "
61 f"Client v{client_version()}. "
62 "`obj` (entities and actions) and `hass_api` (REST client) - no `hass`. Ctrl-D to exit."
63 f"{banner_plugins(loaded)}"
64 )
65 while True:
66 try:
67 source = await prompt.prompt_async(">>> ")
68 except KeyboardInterrupt:
69 continue
70 except EOFError:
71 return 0
72 if not source.strip():
73 continue
74 if (asked := help_request(source)) is not None:
75 await answer(
76 asked, "api", session.run, completer.locate, completer.describe
77 )
78 continue
79 if is_quit_call(source):
80 return 0
81 if cache.is_stale():
82 await cache.refresh()
83 await run_interruptibly(session.run(source))