消息¶

概要

`Message`(*[, attributes, chat, author, ...])	一条消息。
`LinkAttribute`(title[, description, image, url])	链接消息的属性。
`LocationAttribute`(latitude, longitude)	位置消息的属性。
`StatusAttribute`(status_type[, timeout])	状态消息的属性。
`MessageCommands`(commands)	消息指令列表。
`MessageCommand`(name, callable_name[, args, ...])	消息指令。
`Substitutions`(substitutions)	消息文本的替换，也称作「@ 引用」。

类

class ehforwarderbot.message.Message(*, attributes=None, chat=None, author=None, commands=None, deliver_to=None, edit=False, edit_media=False, file=None, filename=None, is_system=False, mime=None, path=None, reactions=None, substitutions=None, target=None, text='', type=MsgType.Unsupported, uid=None, vendor_specific=None)[源代码]¶

一条消息。

备注

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

关键字参数

attributes (Optional[MessageAttribute]) – 用于特定消息类型的属性。只有特定的消息类型才需要此属性。默认为 None。 - 链接： LinkAttribute - 位置： LocationAttribute - 状态：正在输入、正在发送文件等。StatusAttribute
chat (Chat) – 该消息的发送者。
author (ChatMember) – 此消息的发件人。消息的发件人必须（MUST）来自这条消息所标注的 Chat。如果消息是用户自己发送的，则必须是 SelfChatMember 类的对象。注意：发件人可能不在此消息标注会话的 members 属性之内。发件人可以（MAY）来自与 chat 不同的 module_id，或可能无法检索。
commands (Optional[MessageCommands]) – 消息附带的命令。此属性会在「状态」（Status）类消息中被忽略。
deliver_to (Channel) – 接收消息的信道。
edit (bool) – 如果这条消息被编辑过，此属性的值应为真。如果消息附带的媒体文件没有被编辑，请只标记此属性。如果媒体文件也被编辑，则应同时标记此属性和 edit_media 属性。如果未修改任何媒体文件，那么编辑后的消息可能（MAY）不会附带有关该文件的信息。「状态」（Status）类消息会忽略此属性。
edit_media (bool) – 如果消息附带的媒体文件被变更，须标记此值为 True。如果此值为 True，edit 的值也必须（MUST）为 True。如果消息类型是无媒体消息类型（如 Text、 Location 等），此属性将被忽略。此属性在「状态」（Status）类消息中被忽略。
file (Optional[BinaryIO]) – 多媒体文件对应的文件对象，文件指针类型为「rb」。如果不适用的话则为 None。推荐使用 NamedTemporaryFile 对象，在文件被关闭后如不再被需要，该文件应当（SHOULD）能被安全删除。所有文件对象必须（MUST）在发送前复位到 0（file.seek(0)）。
filename (Optional[str]) – 多媒体文件的文件名。如果不适用的话则为 None
is_system (bool) – 如果此消息为一个系统消息，则标记为 true。
mime (Optional[str]) – 文件的 MIME 类型，如果不适用的话则为 None
path (Optional[Path]) – 多媒体文件的本地路径。如果不适用的话则值为 None
reactions (Dict[str, Collection[Chat]]) – 指定对消息的回应。字典的键表示回应名，通常是一个 emoji；值为使用此 emoji 对该消息作出回应的用户列表。字典中所有 Chat 对象必须（MUST）为会话的成员。此属性在「状态」（Status）类消息中被忽略。
substitutions (Optional[Substitutions]) – 消息的替代指示。通常在当消息文本的一部分指代其他用户或会话时使用。此属性在「状态」（Status）类消息中被忽略。
target (Optional[Message]) – 目标消息（通常用于「引用回复」）。此属性会在「状态」（Status）类消息中被忽略。
text (str) – 消息文本。此属性会在「状态」（Status）类消息中被忽略。
type (MsgType) – 消息类型
uid (str) – 消息的唯一标识符。通常使用从端的消息标识符。此标识符在同一信道中的所有会话中必须唯一。
vendor_specific (Dict[str, Any]) – 附上一系列供应商特定的属性。它可以被任何兼容的其他信道或中间件使用。注意这部分的信息并无任何保证。

property link: Optional[ehforwarderbot.message.LinkAttribute]¶

获取当前消息的链接属性（如果可用）。

返回类型: Optional[LinkAttribute]

property location: Optional[ehforwarderbot.message.LocationAttribute]¶

获取当前消息的位置属性（如果可用）。

返回类型: Optional[LocationAttribute]

property status: Optional[ehforwarderbot.message.StatusAttribute]¶

获取当前消息的状态属性（如果可用）。

返回类型: Optional[StatusAttribute]

verify()[源代码]¶

验证消息的有效性。

引发: AssertionError – 当消息无效时

class ehforwarderbot.message.MessageAttribute[源代码]¶

基类：abc.ABC

消息属性的抽象类。

class ehforwarderbot.message.LinkAttribute(title, description=None, image=None, url='')[源代码]¶

基类：ehforwarderbot.message.MessageAttribute

链接消息的属性。

title¶

链接标题。

类型: str

description¶

链接描述信息。

类型: str，可选

image¶

链接的图像/缩略图的 URL。

类型: str，可选

url¶

链接的 URL。

类型: str

__init__(title, description=None, image=None, url='')[源代码]¶

参数

title (str) – 链接标题。
description (str, optional) – 链接描述信息。
image (str, optional) – 链接的图像/缩略图的 URL。
url (str) – 链接的 URL。

class ehforwarderbot.message.LocationAttribute(latitude, longitude)[源代码]¶

基类：ehforwarderbot.message.MessageAttribute

位置消息的属性。

latitude¶

位置的纬度。

类型: float

longitude¶

位置的经度。

类型: float

__init__(latitude, longitude)[源代码]¶

参数

latitude (float) – 位置的纬度。
longitude (float) – 位置的经度。

class ehforwarderbot.message.MessageCommand(name, callable_name, args=None, kwargs=None)[源代码]¶

基类：object

消息指令。

此对象记录如何调用某个组件对象中的方法（method）。如果消息的 chat 和 author 来自同一组件，那么这个方法必须（MUST）在 author 的组件上调用。

该方法必须（MUST）返回一个 str 作为执行结果，或返回 None 如果该消息会被进一步编辑或删除。

name¶

面向用户的命令名称。

类型: str

callable_name¶

命令的方法名称。

类型: str

args¶

传递给函数的参数。

类型: Collection[Any]

kwargs¶

传给函数的关键字参数。

类型: Mapping[str, Any]

__init__(name, callable_name, args=None, kwargs=None)[源代码]¶

参数

name (str) – 面向用户的命令名称。
callable_name (str) – 命令的方法名称。
args (Optional[Collection[Any]]) – 传递给函数的参数。默认为空列表；
kwargs (Optional[Mapping[str, Any]]) – 传递给函数的关键字参数。默认为空字典。

class ehforwarderbot.message.MessageCommands(commands)[源代码]¶

基类：List[ehforwarderbot.message.MessageCommand]

消息指令列表。

消息命令允许用户针对某条特定消息进行操作，例如投票，添加朋友等。

commands¶

消息指令列表。

类型: MessageCommand 列表

__init__(commands)[源代码]¶

参数: commands (list of MessageCommand) – 消息指令列表。

class ehforwarderbot.message.StatusAttribute(status_type, timeout=5000)[源代码]¶

基类：ehforwarderbot.message.MessageAttribute

状态消息的属性。

包含 Status 类型的消息会通知另一端来更新聊天的特定状态，例如正在输入，发送文件等。

status_type¶: 状态的类型，仅可以为 StatusAttribute 中定义的值。

timeout¶

此状态到期的毫秒数。默认值为 5 秒。

类型: Optional[int]

Types[源代码]¶: 支持的状态类型列表

class Types(value)[源代码]¶

基类：enum.Enum

TYPING¶: 在 status_type 中使用。代表正在输入状态。

UPLOADING_FILE¶: 在 status_type 中使用。代表正在上传文件状态。

UPLOADING_IMAGE¶: 在 status_type 中使用，代表上传图像状态。

UPLOADING_VOICE¶: 在 status_type 中使用。代表正在上传语音消息状态。

UPLOADING_VIDEO¶: 在 status_type 中使用，代表上传视频状态。

__init__(status_type, timeout=5000)[源代码]¶

参数

status_type (Types) – 状态类型。
timeout (Optional[int]) – 此状态到期的毫秒数。默认值为 5 秒。

class ehforwarderbot.message.Substitutions(substitutions)[源代码]¶

基类：Dict[Tuple[int, int], Union[ehforwarderbot.chat.Chat, ehforwarderbot.chat.ChatMember]]

消息文本的替换，也称作「@ 引用」。

适用于消息中 @ 其他用户的情况。这里的替换（substitution）指的是一个在「消息文本中指代用户或会话的子字符串」与「该用户或会话的对象」之间对应关系的字典。

字典的值必须（MUST）是该会话中的成员（私聊中的自己 self 或对方，群组中的成员）或同一从端的其他会话。

字典的键值为一个包含两个 int 的元组，其中第一个是在字符串中的起始位置，第二个则是和 Python 中的 substring 函数功能类似的结束位置。元组 (3, 15) 对应于 msg.text[3:15]。元组 (a, b) 必须（MUST）满足 \(0 ≤ a < b ≤ l\)，其中 l 为消息文本的长度。

类型：: Dict[Tuple[int, int], Chat]

property is_mentioned: bool¶

用户在此消息被中提及时，返回 True。

如果此消息中提到私聊或群组会话（消息中通常提到的应是群组成员），在用户为该会话的成员的情况下，这条消息也会被视为提及了该用户。

返回类型: bool

示例¶

初始化和标记会话¶

一条由从端传递到主端的消息

message = Message(
    deliver_to=master,
    chat=wonderland,
    author=wonderland_alice,
    # 其他属性……
)

一条由主端传递到从端的消息

message = Message(
    deliver_to=slave,
    chat=alice,
    author=alice.self,
    # 其他属性……
)

引用先前的消息（目标消息）¶

引用消息的数据（SHOULD）来自消息历史记录。引用消息对象不要求包含 Message.deliver_at 属性，¸并且不是所有属性都必须存在。有关详细信息，请参阅 Message.target。

您可以（MAY）使用 Channel.get_message() 方法从发件信道获取消息对象，但有的信道可能没有提供这个功能。

message.target = Message(
    chat=alice,
    author=alice.other,
    text="问天地好在。",
    type=MsgType.Text,
    uid=MessageID("100000002")
)

编辑一个先前发送的消息¶

无论此消息将被发送至何处，其消息 ID 必须（MUST）由从端指定。

message.edit = True
message.uid = MessageID("100000003")

和类型相关的信息¶

文本消息

message.type = MsgType.Text
message.text = "Hello, Wonderland."

多媒体消息

和媒体处理相关的信息可以参考媒体处理。

下面范例是针对图片消息的。声音，文件，视频，贴纸等类型的与此类同。

对于非文本消息，text 可以（MAY）设为空字符串。
message.type = MsgType.Image
message.text = "图片标题"
message.file = NamedTemporaryFile(suffix=".png")
message.file.write(binary_data)
message.file.seek(0)
message.filename = "假期照片.png"
message.mime = "image/png"

位置消息

对于非文本消息，text 可以（MAY）设为空字符串。

message.type = MsgType.Location
message.text = "我在这儿，来找我吧！"
message.attributes = LocationAttribute(51.4826, -0.0077)

链接消息

对于非文本消息，text 可以（MAY）设为空字符串。

message.type = MsgType.Link
message.text = "来看看这个！"
message.attributes = LinkAttribute(
    title="示例域",
    description="此域旨在用于文档中的说明性示例。",
    image="https://example.com/thumbnail.png",
    url="https://example.com"
)

状态

Text 在状态消息中将会被忽略。

message.type = MsgType.Status
message.attributes = StatusAttribute(StatusAttribute.TYPING)

不支持的消息

该消息类型的 text 属性是必须的。

message.type = MsgType.Unsupported
message.text = "Alice 向你索要 10.00 元。"
               "请在您的 Bazinga App 中继续操作。"

额外信息¶

替代

在消息文本中 @ 用户自己、同一会话中的另一个成员以及整个会话。

message.text = "通知 @david， @bob 和 @所有人。请查收。"
message.substitutions = Substitutions({
    # text[3:9] == "@david"，此处 David 是用户自己。
    (3, 9): wonderland.self,
    # text[11:15] == "@bob"， Bob 是会话里的另一成员。
    (11, 15): wonderland.get_member("bob"),
    # text[18:22] == "@所有人"，这里指代整个群组会话，因此将
    # 会话对象设置为字典的值。
    (18, 22): wonderland
})

命令

message.text = "Carol 向您发送了好友请求。"
message.commands = MessageCommands([
    MessageCommand(name="接受", callable_name="accept_friend_request",
               kwargs={"username": "carol_jhonos", "hash": "2a9329bd93f"}),
    EFBCommand(name="拒绝", callable_name="decline_friend_request",
               kwargs={"username": "carol_jhonos", "hash": "2a9329bd93f"})
])

消息¶

示例¶

初始化和标记会话¶

引用先前的消息（目标消息）¶

编辑一个先前发送的消息¶

和类型相关的信息¶

额外信息¶

EH Forwarder Bot

导航

相关章节

捐赠/支持

参与翻译

消息¶

示例¶

入门：定义相关的会话¶

初始化和标记会话¶

引用先前的消息（目标消息）¶

编辑一个先前发送的消息¶

和类型相关的信息¶

额外信息¶