信道

class ehforwarderbot.channel.Channel(instance_id=None)

抽象信道类。

channel_name

面向用户的信道名称。

类型

str

channel_emoji

信道的 emoji 图标。建议使用视觉长度为一（即单个字形簇（grapheme cluster））的 emoji 或其他最能代表此信道的符号。

类型

str

channel_id

信道的唯一标识符。ID 的命名规范在打包与发布中有说明。在适当的时候，这个 ID 将被附加实例 ID。

类型

ModuleID (str)

instance_id

实例 ID（若可用）。

类型

str

__init__(instance_id=None)

初始化信道。继承初始化方法必须（MUST）在最初调用父类的初始化方法。

参数

instance_id (Optional[NewType()(InstanceID, str)]) – 信道的实例 ID。

get_message_by_id(chat, msg_id)

按照 ID 获取消息实体，适用于主端和从端。若无结果，返回 None。

如果该操作无法在你的平台上执行，覆盖该方法并抛出 EFBOperationNotSupported。

参数

• chat (Chat) – 从端 / 中间件中的会话。

• msg_id (NewType()(MessageID, str)) – 从端 / 中间件中会话的消息 ID 。

返回类型

Optional[Message]

abstract poll()

用来轮询消息的方法。在初始化框架时被调用。此方法应（SHOULD）为阻塞型方法。

abstract send_message(msg)

处理发送到此信道或在此信道中编辑的消息。

提示

主端必须处理包含新消息 ID 的返回对象。取决于从端的实现，消息 ID 在编辑后也可能被更改。新消息 ID 可能（MAY）会取代旧消息 ID。

参数

msg (Message) – 需要处理的消息对象。

返回

相同的消息对象。对象的消息 ID 在发送后可能会被从端更新。即使发送的消息是经过编辑的消息，也可能会有消息 ID 变更。

返回类型

Message

引发

• EFBChatNotFound – 当请求当会话无法找到时被抛出。

• EFBMessageTypeNotSupported – 当此信道不支持发出当消息类型时被抛出。

• EFBOperationNotSupported – 当发出编辑消息的请求，但此信道不支持此功能时被抛出。

• EFBMessageNotFound – 当应该存在的指定消息（例如将被编辑的消息，或者在 msg.target 属性中被引用的消息）无法找到时被抛出。

• EFBMessageError – 当在发送或编辑消息过程中有其他错误发生时被抛出。

abstract send_status(status)

处理发送到此信道的状态。

参数

status (Status) – 状态对象。

引发

• EFBChatNotFound – 当请求当会话无法找到时被抛出。

• EFBMessageNotFound – 当应该存在的指定消息（例如将被移除的消息）无法找到时被抛出。

• EFBOperationNotSupported – 当此信道不支持移除消息功能时被抛出。

• EFBMessageError – 当在移除消息消息的过程中有发生其他错误时被抛出。

备注

主端不应（SHOULD NOT）在这个方法中抛出异常。此类异常在从端中很难妥善处理。

从端不需要继承该方法。

stop_polling()

当 EFB 框架被要求正常停止时，此方法用于停止信道中的所有进程，并根据需要保存所有状态且终止轮询。

当信道准备停止时，轮询功能必须停止阻塞。当所有轮询线程结束时，EFB 框架将完全退出。

class ehforwarderbot.channel.MasterChannel(instance_id=None)

抽象主端类。所有主端必须（MUST）继承此类。

class ehforwarderbot.channel.SlaveChannel(instance_id=None)

抽象从端类。所有从端必须（MUST）继承此类。

supported_message_types

从端能够接受的传入消息类型。主端可能使用此值来决定要发送到从端的消息类型。

将此留空可能会导致主端拒绝向从端发送任何内容。

类型

Set[MsgType]

suggested_reactions

从端默认建议使用的消息回应的列表。

回应应该（SHOULD）按照某种有意义的方式排序，例如，对应 IM 平台所使用的顺序，或者按照使用频率的排序。请注意，如果建议的回应列表过长，或在其他完全列举不可行的情况下，没有必要列出所有建议的回应。

若已知在此信道中任何消息均不支持回应，设置此值为 None。在无法提供建议回应列表时，例如当对每个会话或消息的回应均不同时，设置此值为空列表，

类型

Optional[Sequence[str]]

abstract get_chat(chat_uid)

获取来自从端的会话对象。

参数

chat_uid (NewType()(ChatID, str)) – 会话的 ID。

返回

获取到的会话。

返回类型

.Chat

引发

EFBChatNotFound – 当请求当会话无法找到时被抛出。

abstract get_chat_picture(chat)

获取一个会话的头像。

参数

chat (.Chat) – 需要获取头像的会话。

返回

已打开的临时文件对象。文件对象必须（MUST）具有和发送的图片格式相匹配的文件扩展名，并文件指针移动（seek）到 0。如果该文件在消息被处理后不再需要，可以（MAY）选择在文件被关闭时删除该文件。

返回类型

BinaryIO

引发

• EFBChatNotFound – 当请求当会话无法找到时被抛出。

• EFBOperationNotSupported – 当此会话不提供头像时被抛出。

实际案例

if chat.channel_uid != self.channel_uid:
    raise EFBChannelNotFound()
file = tempfile.NamedTemporaryFile(suffix=".png")
response = requests.post("https://api.example.com/get_profile_picture/png",
                         data={"uid": chat.uid})
if response.status_code == 404:
    raise EFBChatNotFound()
file.write(response.content)
file.seek(0)
return file

abstract get_chats()

返回信道中可用的会话列表。

返回

信道中可用会话列表。

返回类型

Collection[Chat]

get_extra_functions()

获取附加功能列表

返回类型

Dict[NewType()(ExtraCommandName, str), Callable]

返回

被标记为附加功能的方法的字典。这些方法可以通过 get_extra_functions()["methodName"]() 调用。

通用操作

发送消息和状态

发送消息和状态给其他信道是最常见的操作。当信道从外部获取到足够信息时，信道应该进一步处理并打包这些信息到相应的对象中，即 Message 与 Status。

构建对象时，信道应将对象发送给协调器进行后续处理。

就目前而言，message.Message 和 status.Status 都包含有一个属性来指明此对象的目的地信道（Message.Message.deliver_to 和 status.Status.destination_channel）。在发送消息时,协调器会使用这些属性。

消息必须（MUST）使用 coordinator.send_message() 发送。状态必须（MUST）使用 coordinator.send_status() 发送。

当对象被传递给了协调器，它会被中间件做进一步的处理，最终递送给收件信道。

例如，要向主端发送消息

def on_message(self, data: Dict[str, Any]):
    """从端从 IM 平台收到消息时的回调函数。"""
    # 提取消息内容……
    message = coordinator.send_message(Message(
        chat=chat,
        author=author,
        type=message_type,
        text=text,
        # 其他参数……
        uid=data['uid'],
        deliver_to=coordinator.master
    ))
    # 善后处理……

关于信道 ID

随着实例 ID 的引入，在程序代码中需要使用信道 ID 时，如检索配置文件的路径、创建会话和消息对象等情况时，需动态调用 self.channel_id 或其他等效变量，避免任何硬编码或常量 ID。