SuperAPI AI 工具集

ha-async-patterns

编程与开发

查看项目

更新于 10-15 23:48

技能介绍

用途:为 Home Assistant 集成编写正确的异步 Python 代码,适用于涉及 async、await、事件循环、阻塞、executor、async_add_executor_job 等场景。Home Assistant 运行在单线程 asyncio 事件循环上,所有 I/O 必须非阻塞;阻塞事件循环会冻结自动化、UI 与实体更新。

主要能力(以模式形式给出):

  1. 优先使用异步库,例如用 aiohttp 发起请求并 await 响应。
  2. 无异步库时包装同步库:通过 await self.hass.async_add_executor_job(self._sync_get_data) 在线程池执行同步调用;位置参数直接跟在可调用对象后传入,关键字参数需用 functools.partial 包装,因为 async_add_executor_job 不能传关键字参数。
  3. 区分回调与协程:@callback 装饰的是同步函数,运行在事件循环上,禁止 I/O;async 协程可以做 I/O。
  4. 超时处理:用 asyncio.timeout(10) 包裹调用,捕获 TimeoutError 并抛出 UpdateFailed。
  5. 事件监听:在 @callback 处理函数中不执行 I/O,用 hass.async_create_task 调度异步处理;通过 hass.bus.async_listen 注册,并用 entry.async_on_unload(unsub) 注销。
  6. 后台任务:短任务用 hass.async_create_task 以便跟踪并在卸载时等待、防止被垃圾回收;长时间运行的后台任务用 entry.async_create_background_task。

常见错误:直接 requests.get(url)、time.sleep(5)、同步 open().read() 会阻塞事件循环;同步方法即使被 async 函数调用仍会阻塞;使用 asyncio.create_task 创建的任务可能被垃圾回收,应改用 HA 的任务管理。资料未提供安装命令、价格、平台或效果等信息。