This is unreleased documentation for NoneBot Next version.

For up-to-date documentation, see the latest version (2.0.0rc2).

Version: Next

nonebot.adapters

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

使用 Driver.register_adapter 注册适配器。

abstract class `Bot(adapter, self_id)`

说明
Bot 基类。
用于处理上报消息，并提供 API 调用接口。
参数
- adapter (Adapter): 协议适配器实例
- self_id (str): 机器人 ID

property `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

classmethod `validate(cls, value)`

参数
- value (Any)
返回
- E

abstract class `Adapter(driver, **kwargs)`

说明
协议适配器基类。
通常，在 Adapter 中编写协议通信相关代码，如: 建立通信连接、处理接收与发送 data 等。
参数
- driver (nonebot.internal.driver.driver.Driver): Driver 实例
- **kwargs (Any): 其他由 Driver.register_adapter 传入的额外参数

property `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 (str | (~ TM)): 模板
- factory (Type[str] | Type[(~ TM)]): 消息类型工厂，默认为 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)

abstract class Bot(adapter, self_id)#

property config#

property type#

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

classmethod on_called_api(cls, func)#

classmethod on_calling_api(cls, func)#

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

abstract class Event(**extra_data)#

abstract method get_event_description(self)#

abstract method get_event_name(self)#

method get_log_string(self)#

abstract method get_message(self)#

method get_plaintext(self)#

abstract method get_session_id(self)#

abstract method get_type(self)#

abstract method get_user_id(self)#

abstract method is_tome(self)#

classmethod validate(cls, value)#

abstract class Adapter(driver, **kwargs)#

property config#

method bot_connect(self, bot)#

method bot_disconnect(self, bot)#

abstract classmethod get_name(cls)#

async method request(self, setup)#

method setup_http_server(self, setup)#

method setup_websocket_server(self, setup)#

method websocket(self, setup)#

abstract class Message(message=None)#

method append(self, obj)#

method copy(self)#

method count(self, value)#

method extend(self, obj)#

method extract_plain_text(self)#

method get(self, type_, count=None)#

abstract classmethod get_segment_class(cls)#

method index(self, value, *args)#

classmethod template(cls, format_string)#

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

method copy(self)#

method get(self, key, default=None)#

abstract classmethod get_message_class(cls)#

abstract method is_text(self)#

method items(self)#

method keys(self)#

method values(self)#

class MessageTemplate(template, factory=str)#

method add_format_spec(self, spec, name=None)#

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

method format_field(self, value, format_spec)#

method format_map(self, mapping)#

method vformat(self, format_string, args, kwargs)#

abstract class `Bot(adapter, self_id)`

property `config`

property `type`

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

classmethod `on_called_api(cls, func)`

classmethod `on_calling_api(cls, func)`

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

abstract class `Event(**extra_data)`

abstract method `get_event_description(self)`

abstract method `get_event_name(self)`

method `get_log_string(self)`

abstract method `get_message(self)`

method `get_plaintext(self)`

abstract method `get_session_id(self)`

abstract method `get_type(self)`

abstract method `get_user_id(self)`

abstract method `is_tome(self)`

classmethod `validate(cls, value)`

abstract class `Adapter(driver, **kwargs)`

property `config`

method `bot_connect(self, bot)`

method `bot_disconnect(self, bot)`

abstract classmethod `get_name(cls)`

async method `request(self, setup)`

method `setup_http_server(self, setup)`

method `setup_websocket_server(self, setup)`

method `websocket(self, setup)`

abstract class `Message(message=None)`

method `append(self, obj)`

method `copy(self)`

method `count(self, value)`

method `extend(self, obj)`

method `extract_plain_text(self)`

method `get(self, type_, count=None)`

abstract classmethod `get_segment_class(cls)`

method `index(self, value, *args)`

classmethod `template(cls, format_string)`

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

method `copy(self)`

method `get(self, key, default=None)`

abstract classmethod `get_message_class(cls)`

abstract method `is_text(self)`

method `items(self)`

method `keys(self)`

method `values(self)`

class `MessageTemplate(template, factory=str)`

method `add_format_spec(self, spec, name=None)`

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

method `format_field(self, value, format_spec)`

method `format_map(self, mapping)`

method `vformat(self, format_string, args, kwargs)`