ErisPulse ErisPulse
在互動式文檔中心打開 →
本頁章節
本文為靜態鏡像,內容以互動版為準 在互動式文檔中心打開 →

ErisPulse.loaders.adapter 模块


模块概述

ErisPulse 适配器加载器

从 PyPI entry-points 与本地插件文件夹加载和初始化适配器

提示

  1. 适配器必须通过 entry-points 机制注册到 erispulse.adapter 组, 或放入本地插件目录(默认 plugins/,经 discover_adapters 发现)
  2. 适配器类必须继承 BaseAdapter
  3. 适配器不适用懒加载

类列表

class _AdapterReloadSnapshot

内部方法 适配器热重载回滚快照(引用级别)

记录重载前与目标适配器相关的全部注册状态:adapterInfo(含类引用)、 实例、启动态、启动任务、bots 记录与将被清除的 sys.modules 条目。 任一重载步骤失败时按序恢复,旧适配器继续服务。

尽力而为语义:unload 已执行的副作用(断连 / bot offline / 事件注销) 不可撤销——恢复后旧实例处于"已收尾"状态,快照中的 bots 记录仅为登记。

class AdapterLoader(BaseLoader)

适配器加载器

负责从 PyPI entry-points 与本地插件文件夹加载适配器 (本地插件优先:与 entry-point 适配器同名时覆盖,便于本地覆盖调试)

提示 使用方式:

loader = AdapterLoader()
adapter_objs, enabled, disabled = await loader.load(adapter_manager)

方法列表

__init__()

初始化适配器加载器


_get_entry_point_group() -> str

获取 entry-point 组名

返回值: 入口点组名字符串


async load(manager_instance: Any, *, quiet: bool = False) -> tuple[dict[str, Any], list[str], list[str]]

从 entry-points 加载对象(使用 AdapterFinder)

  • manager_instance: 管理器实例
  • quiet: 抑制发现横幅日志(restart 内部重发现时避免每次保存刷屏)

返回值:

dict[str, Any]: 对象字典
list[str]: 启用列表
list[str]: 禁用列表

异常: ImportError - 当加载失败时抛出


async _process_entry_point(entry_point: Any, objs: dict[str, Any], enabled_list: list[str], disabled_list: list[str], manager_instance: Any) -> tuple[dict[str, Any], list[str], list[str], bool]

处理单个适配器 entry-point

  • entry_point: entry-point 对象
  • objs: 适配器对象字典
  • enabled_list: 启用的适配器列表
  • disabled_list: 停用的适配器列表
  • manager_instance: 适配器管理器实例

返回值:

dict[str, Any]: 更新后的适配器对象字典
list[str]: 更新后的启用适配器列表
list[str]: 更新后的禁用适配器列表
bool: 是否为新适配器

异常: ImportError - 当适配器加载失败时抛出


_merge_plugin_folder(objs: dict[str, Any], enabled_list: list[str], disabled_list: list[str], manager_instance: Any) -> None

内部方法 发现本地适配器插件并并入加载结果

本地插件优先:与 entry-point 适配器同名时,本地插件覆盖安装包条目 (便于本地覆盖调试)。启用状态沿用 ErisPulse.adapters.status。

  • objs: 适配器对象字典(原地修改)
  • enabled_list: 启用列表(原地修改)
  • disabled_list: 禁用列表(原地修改)
  • manager_instance: 适配器管理器实例

async load_new_adapter_plugin(adapter_name: str, manager_instance: Any, sdk_instance: Any) -> 'bool | None'

内部方法 热装载新出现的本地适配器插件(插件目录热发现:on_created 消费)

与单适配器重载的差异:无旧实例可卸载,直接走 发现 → 注册 → 按启用状态拉起。

  • adapter_name: 适配器名(平台名)
  • manager_instance: 适配器管理器实例
  • sdk_instance (SDK): 实例

返回值: True 装载成功 / False 装载失败 / None 该名字不是本地适配器插件


_build_adapter_info(entry_point: Any, loaded_class: type, adapter_obj: Any, meta_name: str, dist: Any = None) -> dict[str, Any]

内部方法 构造适配器 adapterInfo(首次加载与热重载共用)

  • entry_point: entry-point 对象
  • loaded_class: entry-point 加载出的适配器类
  • adapter_obj: 适配器类定义所在的模块对象
  • meta_name: 平台名
  • dist: 发行版元数据(可为 None)

返回值 (adapterInfo): 字典


_infer_adapter_top_level(info: 'dict | None') -> 'list[str]'(staticmethod)

内部方法 适配器清理范围兜底推导:适配器类 __module__ 的顶层段

  • info (adapterInfo): 字典(可为 None)

返回值: 顶层模块名列表(无法推导时为空)


_invalidate_source_caches_from(entries: 'dict[str, Any]') -> None(staticmethod)

内部方法 按捕获的 sys.modules 条目清除源文件字节码缓存(__pycache__)

须在 purge sys.modules 之前用快照条目调用(快照条目持有 __file__)。

  • entries: 将被清除的 sys.modules 条目快照

_precheck_adapter_sources(adapter_name: str, old_obj: Any, old_info: 'dict | None', purge_names: 'list[str]') -> bool

内部方法 重载卸载前的语法预检:对目标源码树逐文件 ast.parse

失败(语法错误)即拒绝重载——旧适配器未卸载、继续服务。源码无法 定位时跳过预检并记 debug。

  • adapter_name: 适配器名(日志用)
  • old_obj: 重载前的快照条目(适配器模块对象)
  • old_info: 重载前的 adapterInfo
  • purge_names: 清理名单

返回值: 是否通过(True = 允许继续重载流程)


_capture_adapter_state(adapter_name: str, manager_instance: Any, purge_names: 'list[str]') -> '_AdapterReloadSnapshot'

内部方法 采集适配器重载回滚快照(引用级别)

  • adapter_name: 适配器名
  • manager_instance: 适配器管理器实例
  • purge_names: 将要清除的 sys.modules 顶层名

返回值: 回滚快照


async _restore_adapter_snapshot(snapshot: '_AdapterReloadSnapshot', adapter_name: str, manager_instance: Any) -> None

内部方法 恢复适配器重载快照(重发现 / 注册失败时调用)

恢复顺序:sys.modules 条目 → 注册存根与实例 → 启动态 / bots / 启动任务。原实例处于运行态且旧启动任务已结束时,重放 start(); 其余情况只恢复登记状态。unload 已执行的副作用(断连 / bot offline) 不可撤销。

  • snapshot: 重载前采集的快照
  • adapter_name: 适配器名
  • manager_instance: 适配器管理器实例

async reload_adapter(adapter_name: str, manager_instance: Any, sdk_instance: Any, *, full: bool = True) -> bool

热重载单个适配器(支持本地插件 / PyPI 安装包两种来源)

完整执行 语法预检 → 卸载(shutdown 即清理 + 注销)→ 清理源码字节码 缓存与 sys.modules 子树 → 重新发现/导入 → 重新注册 → 原运行态则 重新拉起 流程;任一步失败自动回滚旧注册状态(尽力而为语义:断连 / bot offline 等 unload 副作用不可撤销)。不重载依赖它的其它适配器 (仅告警)。

  • adapter_name: 适配器名(平台名)
  • manager_instance: 适配器管理器实例
  • sdk_instance (SDK): 实例
  • full: 保留参数位(当前两种来源均执行全量清理,与模块语义对齐)

返回值: 是否重载成功(适配器被移除视为成功)


async register_to_manager(adapters: list[str], adapter_objs: dict[str, Any], manager_instance: Any) -> bool

将适配器注册到管理器

  • adapters: 适配器名称列表
  • adapter_objs: 适配器对象字典
  • manager_instance: 适配器管理器实例

返回值: 适配器注册是否成功

提示 此方法由初始化协调器调用