ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ErisPulse.Core.Event.session_type 模块


模块概述

ErisPulse 会话类型管理模块

提供会话类型的标准化定义、映射、转换和推断功能

提示

  1. 定义了通用的会话类型和ID字段映射
  2. 提供接收类型到发送类型的自动转换(如 private → user)
  3. 支持根据ID字段自动推断会话类型
  4. 允许适配器注册自定义类型映射

函数列表

register_custom_type(receive_type: str, send_type: str, id_field: str, platform: str | None = None) -> bool

注册自定义会话类型

注册期间若处于模块加载 / 适配器启动上下文(current_owner 已设置), 会自动记录归属,模块卸载或适配器关闭时自动注销对应类型。

  • receive_type: 接收事件类型(detail_type)
  • send_type: 发送目标类型
  • id_field: 对应的ID字段名
  • platform: 平台名称(可选,用于区分同名不同平台的类型)

返回值: 是否注册成功


unregister_custom_type(receive_type: str, platform: str | None = None) -> bool

注销自定义会话类型

  • receive_type: 接收事件类型
  • platform: 平台名称

返回值: 是否注销成功


unregister_custom_types_by_owner(owner: str) -> int

注销指定归属者注册的全部自定义会话类型

供模块卸载 / 适配器关闭时兜底清理,避免适配器重载或模块卸载后 旧的自定义类型映射残留。

  • owner: 归属者(模块名或适配器平台名)

返回值: 注销的类型数量


get_id_field(receive_type: str, platform: str | None = None) -> str

根据接收类型获取对应的ID字段名

  • receive_type: 接收事件类型
  • platform: 平台名称(可选)

返回值 (ID): 字段名


get_receive_type(id_field: str, platform: str | None = None) -> str

根据ID字段获取对应的接收类型

  • id_field (ID): 字段名
  • platform: 平台名称(可选)

返回值: 接收类型


convert_to_send_type(receive_type: str | None, platform: str | None = None) -> str

将接收类型转换为发送目标类型

  • receive_type: 接收事件类型(None 时返回默认值 "user")
  • platform: 平台名称(可选)

返回值: 发送目标类型

示例:

convert_to_send_type("private")  # 返回 "user"
convert_to_send_type("group")   # 返回 "group"
convert_to_send_type(None)       # 返回 "user"

convert_to_receive_type(send_type: str, platform: str | None = None) -> str

将发送目标类型转换为接收类型

  • send_type: 发送目标类型
  • platform: 平台名称(可选)

返回值: 接收类型

示例:

convert_to_receive_type("user")   # 返回 "private"
convert_to_receive_type("group")  # 返回 "group"

infer_receive_type(event: dict, platform: str | None = None) -> str

根据事件数据自动推断接收类型

检查顺序:

  1. 如果 detail_type 是已知的会话类型(标准或自定义),直接使用
  2. notice/request 事件的 detail_type 是语义子类型(如 group_member_increase), 不是会话类型,此时根据 ID 字段推断
  3. 最后根据存在的 ID 字段,按优先级返回
  • event: 事件数据字典
  • platform: 平台名称(可选)

返回值: 推断的接收类型

示例:

# 消息事件:detail_type 就是会话类型
event = {"type": "message", "detail_type": "group", "group_id": "123"}
infer_receive_type(event)  # 返回 "group"

# 通知事件:detail_type 是语义子类型,从 ID 字段推断
event = {"type": "notice", "detail_type": "group_member_increase", "group_id": "123"}
infer_receive_type(event)  # 返回 "group"(而非 "group_member_increase")

event = {"type": "notice", "detail_type": "friend_increase", "user_id": "456"}
infer_receive_type(event)  # 返回 "private"

get_target_id(event: dict, platform: str | None = None) -> str

获取事件的目标ID(根据推断的会话类型)

  • event: 事件数据字典
  • platform: 平台名称(可选)

返回值: 目标ID

示例:

event = {"detail_type": "group", "group_id": "123"}
get_target_id(event)  # 返回 "123"

get_send_type_and_target_id(event: dict, platform: str | None = None) -> tuple[str, str]

获取发送类型和目标ID(一步完成类型转换和ID获取)

  • event: 事件数据字典
  • platform: 平台名称(可选)

返回值: (发送类型, 目标ID)

示例:

event = {"detail_type": "private", "user_id": "123"}
get_send_type_and_target_id(event)  # 返回 ("user", "123")

is_standard_type(receive_type: str) -> bool

检查是否为标准接收类型

  • receive_type: 接收事件类型

返回值: 是否为标准类型


is_valid_send_type(send_type: str) -> bool

检查是否为有效的发送类型

  • send_type: 发送目标类型

返回值: 是否为有效类型


get_standard_types() -> set[str]

获取所有标准接收类型

返回值: 标准类型集合


get_send_types() -> set[str]

获取所有发送类型

返回值: 发送类型集合


clear_custom_types(platform: str | None = None) -> int

清除自定义类型映射

  • platform: 平台名称(可选,如果指定则只清除该平台的类型)

返回值: 清除的类型数量


类列表

class StrEnum(str, Enum)

字符串枚举:成员值同时是 str,可直接用于字符串上下文。