会话与会话成员

继承图

Inheritance diagram of ehforwarderbot.chat

概要

PrivateChat(*[, channel, middleware, ...])

私聊会话。会话中通常只有用户自己和另一参与者。

SystemChat(*[, channel, middleware, ...])

系统会话。会话中通常只有用户自己和一个系统类会话成员。

GroupChat(*[, channel, middleware, ...])

群聊，通常有多个成员。

ChatMember(chat, *[, name, alias, uid, id, ...])

会话成员。

SelfChatMember(chat, *[, name, alias, id, ...])

用户自己作为会话的成员。

SystemChatMember(chat, *[, name, alias, id, ...])

系统账号/提示作为会话的成员。

ChatNotificationState(value)

指定此会话在对应从端（或中间件）中的通知设定。

类

class ehforwarderbot.chat.BaseChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, uid='', id='', vendor_specific=None, description='')[源代码]

基类：abc.ABC

基础会话类，这是一个抽象类，定义了所有的会话和成员对象之间共有的属性。这个类不能直接创建实例。

备注

BaseChat 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

module_id

组件的唯一 ID。

类型

ModuleID (str)

channel_emoji

信道的表情符号，如果会话来自中间件，则为空字符串。

类型

str

module_name

组件名称。

类型

ModuleID (str)

name

会话名称

类型

str

alias

会话的别名，通常由用户设置。

类型

Optional[str]

uid

会话的唯一 ID。该 ID 必须（MUST）在信道内唯一。

类型

ChatID (str)

description

会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

类型

str

vendor_specific

任何供应商特定属性。

类型

Dict[str, Any]

__init__(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, uid='', id='', vendor_specific=None, description='')[源代码]
参数

  • channel (Optional[SlaveChannel]) – 提供信道对象来自动填充 module_name、channel_emoji、以及 module_id。

  • middleware (Optional[Middleware]) – 提供中间软件对象来自动填充 module_name 和 module_id。

  • module_id (NewType()(ModuleID, str)) – 组件的唯一 ID。

  • channel_emoji (str) – 信道的表情符号，如果会话来自中间件，则为空字符串。

  • module_name (str) – 组件名称。

  • name (str) – 会话名称

  • alias (Optional[str]) – 会话的别名，通常由用户设置。

  • uid (NewType()(ChatID, str)) – 会话的唯一 ID。该 ID 必须（MUST）在信道内唯一。

  • description (str) – 会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

  • vendor_specific (Dict[str, Any]) – 任何供应商特定属性。

copy()[源代码]

返回对象的浅拷贝。

返回类型

TypeVar(_BaseChatSelf, bound= BaseChat, covariant=True)

property display_name: str

快捷属性，等同于 alias or name

返回类型

str

property long_name: str

快捷属性。如果存在别名，此属性将返回别名，并在括号内提供原名；否则此属性将返回原名。

返回类型

str

abstract verify()[源代码]

验证数据的完整性。

引发

AssertionError – 当此会话无效时。

class ehforwarderbot.chat.Chat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', members=None, notification=ChatNotificationState.ALL, with_self=True)[源代码]

基类：ehforwarderbot.chat.BaseChat, abc.ABC

会话对象，可以表示用户、群组或系统会话。这个类是抽象类。不能直接从此类创建任何实例。

如果 IM 平台正在提供用户自己的 ID，并且使用此 ID 来标注消息的发件人，那么应该（SHOULD）相应地更新 Chat.self.uid 的值。

>>> channel.my_chat_id
"david_divad"
>>> chat = Chat(channel=channel, name="爱丽丝 Alice", uid=ChatID("alice123"))
>>> chat.self.uid = channel.my_chat_id

这样，您可以一步直接获取消息作者：

author = chat.get_member(author_id)

… 而不必使用条件检查：

if author_id == channel.my_chat_id:
    author = chat.self
else:
    author = chat.get_member(author_id)

备注

Chat 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

module_id

组件的唯一 ID。

类型

ModuleID (str)

channel_emoji

信道的表情符号，如果会话来自中间件，则为空字符串。

类型

str

module_name

组件名称。

类型

str

name

会话名称

类型

str

alias

会话的别名，通常由用户设置。

类型

Optional[str]

uid

会话的唯一 ID。该 ID 必须（MUST）在信道内唯一。

类型

ChatID (str)

description

会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

类型

str

notification

指定此会话在对应从端（或中间件）中的通知设定。默认为 ALL。

类型

ChatNotificationState

members

提供会话成员列表。默认为空 list。

您可以继承此类，并实现一套 @property 方法来延迟加载会话成员。

注意：当此会话对象作为消息的一部分时，此列表可能包含中间件创建的成员。在通过从端的直接取得本会话对象时，可能（MAY）不会包括这些成员。这些成员与消息标注的会话可能具有不同的 module_id。

类型

ChatMember 列表

vendor_specific

任何供应商特定属性。

类型

Dict[str, Any]

self

用户自己作为会话的成（若存在）。

类型

Optional[SelfChatMember]

__init__(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', members=None, notification=ChatNotificationState.ALL, with_self=True)[源代码]
关键字参数

  • module_id (str) – 组件的唯一 ID。

  • channel_emoji (str) – 信道的表情符号，如果会话来自中间件，则为空字符串。

  • module_name – 组件名称。

  • name (str) – 会话名称

  • alias (Optional[str]) – 会话的别名，通常由用户设置。

  • id – 会话的唯一 ID。该 ID 必须（MUST）在信道内唯一。

  • description (str) – 会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

  • notification (ChatNotificationState) – 指定此会话在对应从端（或中间件）中的通知设定。默认为 ALL。

  • members (MutableSequence[ChatMember]) – 提供会话成员列表。默认为空 list。

  • vendor_specific (Dict[str, Any]) – 任何供应商特定属性。

  • with_self (bool) – 初始化会话。将用户自己加入到会话成员中。

add_member(name, uid, alias=None, id='', vendor_specific=None, description='', middleware=None)[源代码]

将成员添加到该会话。

小技巧

此方法不会检查重复项。仅当您确定这些成员尚未添加时，才使用此方法添加成员。要在添加成员前检查成员是否已添加，您可以执行以下操作：

with contextlib.suppress(KeyError):
    return chat.get_member(uid)
return chat.add_member(name, uid, alias=..., vendor_specific=...)
参数

  • name (str) – 成员名称。

  • uid (NewType()(ChatID, str)) – 成员 ID。

关键字参数

  • alias (Optional[str]) – 成员别名。

  • vendor_specific (Dict[str, Any]) – 任何供应商特定属性。

  • description (str) – 会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

  • middleware (Optional[Middleware]) – 初始化此会话作为中间件的一部分。

返回类型

ChatMember

add_self()[源代码]

将自我添加到成员列表中。

引发

AssertionError – 当成员列表中已有用户自己时。

返回类型

SelfChatMember

add_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]

将系统成员添加到该会话。

当「系统」成员需要被包含在会话成员列表内时，从端和中间件可以使用此方法创建来自系统消息的发件人。

小技巧

此方法不会检查重复项。仅当您确定这些成员尚未添加时，才使用此方法添加成员。

关键字参数

  • name (str) – 成员名称。

  • uid – 成员 ID。

  • alias (Optional[str]) – 成员别名。

  • vendor_specific (Dict[str, Any]) – 任何供应商特定属性。

  • description (str) – 会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

  • middleware (Optional[Middleware]) – 初始化此会话作为中间件的一部分。

返回类型

SystemChatMember

get_member(member_id)[源代码]

通过成员 ID 查找会话成员。

参数

member_id (NewType()(ChatID, str)) – 成员 ID。

返回类型

ChatMember

返回

会话成员。

引发

KeyError – 当提供的 ID 无法找到时。

property has_self: bool

显示此聊天是否包含用户自己。

返回类型

bool

make_system_member(name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]

构建与该会话相关联的系统成员。

当「系统」成员不包含在会话成员列表内时，从端和中间件可以使用此方法创建来自系统消息的发件人。

关键字参数

  • name (str) – 成员名称。

  • uid – 成员 ID。

  • alias (Optional[str]) – 成员别名。

  • vendor_specific (Dict[str, Any]) – 任何供应商特定属性。

  • description (str) – 会话附带的文字说明，通常也称作「简介」、「自我介绍」、「群公告」、「个性签名」等。

  • middleware (Optional[Middleware]) – 初始化此会话作为中间件的一部分。

返回类型

SystemChatMember

self: Optional[ehforwarderbot.chat.SelfChatMember]

用户自己作为会话的成（若存在）。

class ehforwarderbot.chat.ChatMember(chat, *, name='', alias=None, uid='', id='', vendor_specific=None, description='', middleware=None)[源代码]

基类：ehforwarderbot.chat.BaseChat

会话的成员。通常表示群组的成员或私聊中的另一名参与者。由 IM 平台用户创建的聊天机器人也应被视为一个 ChatMember。

若要表示用户自己，请使用 SelfChatMember。

若要表示由系统、从端或中间件生成的会话成员，请使用 SystemChatMember。

ChatMember 对象必须依照其所属的会话来创建。即使同一人出现在不同的群组或私聊中，也必须创建不同的对象。

建议（RECOMMEND）使用 Chat.add_member() 方法创建 ChatMember。

备注

ChatMember 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

__init__(chat, *, name='', alias=None, uid='', id='', vendor_specific=None, description='', middleware=None)[源代码]
参数

chat (Chat) – 此成员所属的会话。

关键字参数

  • name (str) – 成员名称。

  • alias (Optional[str]) – 会话成员的别名，通常由用户设置。

  • uid (ChatID (str)) – 成员的唯一 ID。此 ID 必须在信道中是唯一的。此 ID 可以与同一用户的私聊会话 ID 相同。

  • description (str) – 成员的文本描述，通常称为成员的「自我介绍」、「描述」、「个性签名」等。

  • middleware (Middleware) – 初始化此会话作为中间件的一部分。

verify()[源代码]

验证数据的完整性。

引发

AssertionError – 当此会话无效时。

class ehforwarderbot.chat.ChatNotificationState(value)[源代码]

基类：enum.Enum

标注在从端或中间件中此会话的通知设置。如果没有完全符合的选项，请选择其中最相似的。

ALL = -1

会话中的所有消息都会触发通知。

MENTIONS = 1

仅当消息中通过 @ 用户或引用回复（即目标消息）提及用户时，才会发送通知。

NONE = 0

从端对应的 IM 平台不接收任何通知。

class ehforwarderbot.chat.GroupChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True)[源代码]

基类：ehforwarderbot.chat.Chat

群聊，通常有多个成员。

可以使用 add_member() 添加成员。

如果 with_self 参数的值是 ``True``（默认），则用户自己也将被初始化为此会话的成员。

实际案例

>>> group = GroupChat(channel=slave_channel, name="Wonderland", uid=ChatID("wonderland001"))
>>> group.add_member(name="Alice", uid=ChatID("alice"))
ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='Alice', alias=None, uid='alice', vendor_specific={}, description='')
>>> group.add_member(name="bob", alias="Bob James", uid=ChatID("bob"))
ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='bob', alias='Bob James', uid='bob', vendor_specific={}, description='')
>>> from pprint import pprint
>>> pprint(group.members)
[SelfChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='You', alias=None, uid='__self__', vendor_specific={}, description=''),
 ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='Alice', alias=None, uid='alice', vendor_specific={}, description=''),
 ChatMember(chat=<GroupChat: Wonderland (wonderland001) @ Example slave channel>, name='bob', alias='Bob James', uid='bob', vendor_specific={}, description='')]

备注

GroupChat 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

verify()[源代码]

验证数据的完整性。

引发

AssertionError – 当此会话无效时。

class ehforwarderbot.chat.PrivateChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True, other_is_self=False)[源代码]

基类：ehforwarderbot.chat.Chat

私聊会话。会话中通常只有用户自己和另一参与者。聊天机器人也应该（SHOULD）归属于此类型。

会话中除了用户自己和系统成员外，最多只能有一个成员，否则可能导致意外行为。

默认情况下，此对象初始化时会在成员列表中包含此会话的另一个参与者（即「对方」）。

如果 with_self 参数的值是 ``True``（默认），则用户自己也将被初始化为此会话的成员。

参数

other – 会话的另一个成员参与者

备注

PrivateChat 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

verify()[源代码]

验证数据的完整性。

引发

AssertionError – 当此会话无效时。

class ehforwarderbot.chat.SelfChatMember(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]

基类：ehforwarderbot.chat.ChatMember

用户自己作为会话的成员。

创建 SelfChatMember 对象时，建议（RECOMMEND）在创建会话对象时将参数 with_self 设置为 True 来创建此对象。创建出的对象可以通过 chat.self 访问。

SelfChatMember 对象的默认 ID 为 SelfChatMember.SELF_ID，默认名称为「您」或「您」的其他语言翻译。

如果 IM 平台有提供相应 ID，建议（RECOMMEND）您更改此对象的 ID，并且您可以（MAY）根据您的需要更改此对象的名称或别名。

备注

SelfChatMember 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

SELF_ID

SelfChatMember 的默认 ID。

__init__(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]
参数

chat (Chat) – 此成员所属的会话。

关键字参数

  • name (str) – 成员名称。

  • alias (Optional[str]) – 会话成员的别名，通常由用户设置。

  • uid (ChatID (str)) – 成员的唯一 ID。此 ID 必须在信道中是唯一的。此 ID 可以与同一用户的私聊会话 ID 相同。

  • description (str) – 成员的文本描述，通常称为成员的「自我介绍」、「描述」、「个性签名」等。

  • middleware (Middleware) – 初始化此会话作为中间件的一部分。

class ehforwarderbot.chat.SystemChat(*, channel=None, middleware=None, module_name='', channel_emoji='', module_id='', name='', alias=None, id='', uid='', vendor_specific=None, description='', notification=ChatNotificationState.ALL, with_self=True)[源代码]

基类：ehforwarderbot.chat.Chat

系统会话，通常只有用户自己和另一名参与者（系统会话成员）在此会话之中。此对象用于表示系统会话，其中另一名参与者既不是远端 IM 的用户，也不是聊天机器人。

建议（RECOMMEND）中间件在要发送系统消息时创建系统会话。

默认情况下，此对象初始化时会在成员列表中包含一个系统成员（即「对方」）。

如果 with_self 参数的值是 ``True``（默认），则用户自己也将被初始化为此会话的成员。

参数

other – 会话的另一个成员参与者

备注

SystemChat 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

verify()[源代码]

验证数据的完整性。

引发

AssertionError – 当此会话无效时。

class ehforwarderbot.chat.SystemChatMember(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]

基类：ehforwarderbot.chat.ChatMember

系统账号/提示作为会话的成员。

使用此会话发送不是来自任何特定成员的消息。建议（RECOMMEND）中间件使用此成员类型在在现有会话中与用户沟通。

由 IM 平台用户创建的聊天机器人不应（SHOULD NOT）创建为 SystemChatMember，而应（SHOULD）是一个普通的 ChatMember。

建议（RECOMMENDED）使用 Chat.add_system_member() 或 Chat.mak_system_member() 方法创建 SystemChatMember 对象。

备注

SystemChatMember 对象是可序列化的，因此我们建议（RECOMMEND）保持它的子类对象可序列化。

SYSTEM_ID

SystemChatMember 的默认 ID。

__init__(chat, *, name='', alias=None, id='', uid='', vendor_specific=None, description='', middleware=None)[源代码]
参数

chat (Chat) – 此成员所属的会话。

关键字参数

  • name (str) – 成员名称。

  • alias (Optional[str]) – 会话成员的别名，通常由用户设置。

  • uid (ChatID (str)) – 成员的唯一 ID。此 ID 必须在信道中是唯一的。此 ID 可以与同一用户的私聊会话 ID 相同。

  • description (str) – 成员的文本描述，通常称为成员的「自我介绍」、「描述」、「个性签名」等。

  • middleware (Middleware) – 初始化此会话作为中间件的一部分。