nonebot2/website/versioned_docs/version-2.0.0-beta.2/api/adapters/index.md
2022-02-14 16:27:11 +00:00

10 KiB

sidebar_position description
0 nonebot.adapters 模块

nonebot.adapters

本模块定义了协议适配基类,各协议请继承以下基类。

使用 Driver.register_adapter 注册适配器。

abstract class Bot(adapter, self_id)

  • 说明

    Bot 基类。

    用于处理上报消息,并提供 API 调用接口。

  • 参数

    • adapter (Adapter): 协议适配器实例

    • self_id (str): 机器人 ID

property config

  • 类型: nonebot.config.Config

  • 说明: 全局 NoneBot 配置

property type

  • 类型: str

  • 说明: 协议适配器名称

async method call_api(self, api, **data)

  • 说明

    调用机器人 API 接口,可以通过该函数或直接通过 bot 属性进行调用

  • 参数

    • api (str): API 名称

    • **data (Any): API 数据

  • 返回

    • Any
  • 用法

    await bot.call_api("send_msg", message="hello world")
    await bot.send_msg(message="hello world")
    

classmethod on_called_api(cls, func)

  • 说明

    调用 api 后处理。

    钩子函数参数:

    • bot: 当前 bot 对象
    • exception: 调用 api 时发生的错误
    • api: 调用的 api 名称
    • data: api 调用的参数字典
    • result: api 调用的返回
  • 参数

    • func ((Bot, Exception | None, str, dict[str, Any], Any) -> Awaitable[Any])
  • 返回

    • (Bot, Exception | None, str, dict[str, Any], Any) -> Awaitable[Any]

classmethod on_calling_api(cls, func)

  • 说明

    调用 api 预处理。

    钩子函数参数:

    • bot: 当前 bot 对象
    • api: 调用的 api 名称
    • data: api 调用的参数字典
  • 参数

    • func ((Bot, str, dict[str, Any]) -> Awaitable[Any])
  • 返回

    • (Bot, str, dict[str, Any]) -> Awaitable[Any]

abstract async method send(self, event, message, **kwargs)

  • 说明

    调用机器人基础发送消息接口

  • 参数

    • event (Event): 上报事件

    • message (str | Message | MessageSegment): 要发送的消息

    • **kwargs (Any): 任意额外参数

  • 返回

    • Any

abstract class Event(**extra_data)

  • 说明

    Event 基类。提供获取关键信息的方法,其余信息可直接获取。

  • 参数

    • **extra_data (Any)

abstract method get_event_description(self)

  • 说明

    获取事件描述的方法,通常为事件具体内容。

  • 返回

    • str

abstract method get_event_name(self)

  • 说明

    获取事件名称的方法。

  • 返回

    • str

method get_log_string(self)

  • 说明

    获取事件日志信息的方法。

    通常你不需要修改这个方法,只有当希望 NoneBot 隐藏该事件日志时,可以抛出 NoLogException 异常。

  • 返回

    • str
  • 异常

    NoLogException

abstract method get_message(self)

  • 说明

    获取事件消息内容的方法。

  • 返回

    • Message

method get_plaintext(self)

  • 说明

    获取消息纯文本的方法。

    通常不需要修改,默认通过 get_message().extract_plain_text 获取。

  • 返回

    • str

abstract method get_session_id(self)

  • 说明

    获取会话 id 的方法,用于判断当前事件属于哪一个会话,通常是用户 id、群组 id 组合。

  • 返回

    • str

abstract method get_type(self)

  • 说明

    获取事件类型的方法,类型通常为 NoneBot 内置的四种类型。

  • 返回

    • str

abstract method get_user_id(self)

  • 说明

    获取事件主体 id 的方法,通常是用户 id 。

  • 返回

    • str

abstract method is_tome(self)

  • 说明

    获取事件是否与机器人有关的方法。

  • 返回

    • bool

abstract class Adapter(driver, **kwargs)

  • 说明

    协议适配器基类。

    通常,在 Adapter 中编写协议通信相关代码,如: 建立通信连接、处理接收与发送 data 等。

  • 参数

property config

  • 类型: nonebot.config.Config

  • 说明: 全局 NoneBot 配置

method bot_connect(self, bot)

  • 说明

    告知 NoneBot 建立了一个新的 Bot 连接。

    当有新的 Bot 实例连接建立成功时调用。

  • 参数

    • bot (nonebot.internal.adapter.bot.Bot): Bot 实例
  • 返回

    • None

method bot_disconnect(self, bot)

  • 说明

    告知 NoneBot Bot 连接已断开。

    当有 Bot 实例连接断开时调用。

  • 参数

    • bot (nonebot.internal.adapter.bot.Bot): Bot 实例
  • 返回

    • None

abstract classmethod get_name(cls)

  • 说明

    当前协议适配器的名称

  • 返回

    • str

async method request(self, setup)

  • 说明

    进行一个 HTTP 客户端请求

  • 参数

    • setup (nonebot.internal.driver.model.Request)
  • 返回

    • nonebot.internal.driver.model.Response

method setup_http_server(self, setup)

  • 说明

    设置一个 HTTP 服务器路由配置

  • 参数

    • setup (nonebot.internal.driver.model.HTTPServerSetup)
  • 返回

    • Unknown

method setup_websocket_server(self, setup)

  • 说明

    设置一个 WebSocket 服务器路由配置

  • 参数

    • setup (nonebot.internal.driver.model.WebSocketServerSetup)
  • 返回

    • Unknown

method websocket(self, setup)

  • 说明

    建立一个 WebSocket 客户端连接请求

  • 参数

    • setup (nonebot.internal.driver.model.Request)
  • 返回

    • AsyncGenerator[nonebot.internal.driver.model.WebSocket, NoneType]

abstract class Message(message=None)

  • 说明

    消息数组

  • 参数

    • message (str | NoneType | Iterable[(~ TMS)] | (~ TMS)): 消息内容

method append(self, obj)

  • 说明

    添加一个消息段到消息数组末尾。

  • 参数

    • obj (str | (~ TMS)): 要添加的消息段
  • 返回

    • (~ TM)

method copy(self)

  • 返回

    • (~ TM)

method count(self, value)

  • 参数

    • value ((~ TMS) | str)
  • 返回

    • int

method extend(self, obj)

  • 说明

    拼接一个消息数组或多个消息段到消息数组末尾。

  • 参数

    • obj ((~ TM) | Iterable[(~ TMS)]): 要添加的消息数组
  • 返回

    • (~ TM)

method extract_plain_text(self)

  • 说明

    提取消息内纯文本消息

  • 返回

    • str

method get(self, type_, count=None)

  • 参数

    • type_ (str)

    • count (int | None)

  • 返回

    • (~ TM)

abstract classmethod get_segment_class(cls)

  • 说明

    获取消息段类型

  • 返回

    • Type[(~ TMS)]

method index(self, value, *args)

  • 参数

    • value ((~ TMS) | str)

    • *args

  • 返回

    • int

classmethod template(cls, format_string)

  • 说明

    创建消息模板。

    用法和 str.format 大致相同, 但是可以输出消息对象, 并且支持以 Message 对象作为消息模板

    并且提供了拓展的格式化控制符, 可以用适用于该消息类型的 MessageSegment 的工厂方法创建消息

  • 参数

    • format_string (str | (~ TM)): 格式化模板
  • 返回

    • nonebot.internal.adapter.template.MessageTemplate[(~ TM)]: 消息格式化器

abstract class MessageSegment(type, data=<factory>)

  • 说明

    消息段基类

  • 参数

    • type (str)

    • data (dict[str, Any])

method copy(self)

  • 返回

    • (~ T)

method get(self, key, default=None)

  • 参数

    • key (str)

    • default (Any)

  • 返回

    • Unknown

abstract classmethod get_message_class(cls)

  • 说明

    获取消息数组类型

  • 返回

    • Type[(~ TM)]

abstract method is_text(self)

  • 说明

    当前消息段是否为纯文本

  • 返回

    • bool

method items(self)

  • 返回

    • Unknown

method keys(self)

  • 返回

    • Unknown

method values(self)

  • 返回

    • Unknown

class MessageTemplate(template, factory=str)

  • 说明

    消息模板格式化实现类。

  • 参数

    • template: 模板

    • factory: 消息类型工厂,默认为 str

method add_format_spec(self, spec, name=None)

  • 参数

    • spec ((~ FormatSpecFunc_T))

    • name (str | None)

  • 返回

    • (~ FormatSpecFunc_T)

method format(self, *args, **kwargs)

  • 说明

    根据传入参数和模板生成消息对象

  • 参数

    • *args

    • **kwargs

  • 返回

    • Unknown

method format_field(self, value, format_spec)

  • 参数

    • value (Any)

    • format_spec (str)

  • 返回

    • Any

method format_map(self, mapping)

  • 说明

    根据传入字典和模板生成消息对象, 在传入字段名不是有效标识符时有用

  • 参数

    • mapping (Mapping[str, Any])
  • 返回

    • (~ TF)

method vformat(self, format_string, args, kwargs)

  • 参数

    • format_string (str)

    • args (Sequence[Any])

    • kwargs (Mapping[str, Any])

  • 返回

    • (~ TF)