This is unreleased documentation for NoneBot Next version.

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

Version: Next

nonebot.adapters

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

使用 Driver.register_adapter 注册适配器。

abstract class `Bot(adapter, self_id)`

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

instance-var `adapter`

类型: Adapter
说明: 协议适配器实例

instance-var `self_id`

类型: str
说明: 机器人 ID

property `type`

类型: str
说明: 协议适配器名称

property `config`

类型: Config
说明: 全局 NoneBot 配置

async method `call_api(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")

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

说明: 调用机器人基础发送消息接口
参数
- event (Event): 上报事件
- message (str | Message | MessageSegment): 要发送的消息
- **kwargs (Any): 任意额外参数
返回
- Any

classmethod `on_calling_api(func)`

说明
调用 api 预处理。
钩子函数参数:
- bot: 当前 bot 对象
- api: 调用的 api 名称
- data: api 调用的参数字典
参数
- func (T_CallingAPIHook)
返回
- T_CallingAPIHook

classmethod `on_called_api(func)`

说明
调用 api 后处理。
钩子函数参数:
- bot: 当前 bot 对象
- exception: 调用 api 时发生的错误
- api: 调用的 api 名称
- data: api 调用的参数字典
- result: api 调用的返回
参数
- func (T_CalledAPIHook)
返回
- T_CalledAPIHook

abstract class `Event(<auto>)`

说明: Event 基类。提供获取关键信息的方法，其余信息可直接获取。
参数
auto

classmethod `validate(value)`

参数
- value (Any)
返回
- E

abstract method `get_type()`

说明: 获取事件类型的方法，类型通常为 NoneBot 内置的四种类型。
参数
empty
返回
- str

abstract method `get_event_name()`

说明: 获取事件名称的方法。
参数
empty
返回
- str

abstract method `get_event_description()`

说明: 获取事件描述的方法，通常为事件具体内容。
参数
empty
返回
- str

method `get_log_string()`

说明
获取事件日志信息的方法。
通常你不需要修改这个方法，只有当希望 NoneBot 隐藏该事件日志时，可以抛出 NoLogException 异常。
参数
empty
返回
- str
异常
- NoLogException

abstract method `get_user_id()`

说明: 获取事件主体 id 的方法，通常是用户 id 。
参数
empty
返回
- str

abstract method `get_session_id()`

说明: 获取会话 id 的方法，用于判断当前事件属于哪一个会话，通常是用户 id、群组 id 组合。
参数
empty
返回
- str

abstract method `get_message()`

说明: 获取事件消息内容的方法。
参数
empty
返回
- Message

method `get_plaintext()`

说明
获取消息纯文本的方法。
通常不需要修改，默认通过 get_message().extract_plain_text 获取。
参数
empty
返回
- str

abstract method `is_tome()`

说明: 获取事件是否与机器人有关的方法。
参数
empty
返回
- bool

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

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

instance-var `driver`

类型: Driver
说明: 实例

instance-var `bots`

类型: dict[str, Bot]
说明: 本协议适配器已建立连接的 Bot 实例

abstract classmethod `get_name()`

说明: 当前协议适配器的名称
参数
empty
返回
- str

property `config`

类型: Config
说明: 全局 NoneBot 配置

method `bot_connect(bot)`

说明
告知 NoneBot 建立了一个新的 Bot 连接。
当有新的 Bot 实例连接建立成功时调用。
参数
- bot (Bot): Bot 实例
返回
- None

method `bot_disconnect(bot)`

说明
告知 NoneBot Bot 连接已断开。
当有 Bot 实例连接断开时调用。
参数
- bot (Bot): Bot 实例
返回
- None

method `setup_http_server(setup)`

说明: 设置一个 HTTP 服务器路由配置
参数
- setup (HTTPServerSetup)
返回
- untyped

method `setup_websocket_server(setup)`

说明: 设置一个 WebSocket 服务器路由配置
参数
- setup (WebSocketServerSetup)
返回
- untyped

async method `request(setup)`

说明: 进行一个 HTTP 客户端请求
参数
- setup (Request)
返回
- Response

method `websocket(setup)`

说明: 建立一个 WebSocket 客户端连接请求
参数
- setup (Request)
返回
- AsyncGenerator[WebSocket, None]

abstract class `Message(<auto>)`

说明: 消息数组
参数
- message: 消息内容

classmethod `template(format_string)`

说明
创建消息模板。
用法和 str.format 大致相同, 但是可以输出消息对象, 并且支持以 Message 对象作为消息模板
并且提供了拓展的格式化控制符, 可以用适用于该消息类型的 MessageSegment 的工厂方法创建消息
参数
- format_string (str | TM): 格式化模板
返回
- MessageTemplate[TM]: 消息格式化器

abstract classmethod `get_segment_class()`

说明: 获取消息段类型
参数
empty
返回
- type[TMS]

method `index(value, *args)`

参数
- value (TMS | str)
- *args
返回
- int

method `get(type_, count=None)`

参数
- type_ (str)
- count (int | None)
返回
- TM

method `count(value)`

参数
- value (TMS | str)
返回
- int

method `append(obj)`

说明: 添加一个消息段到消息数组末尾。
参数
- obj (str | TMS): 要添加的消息段
返回
- TM

method `extend(obj)`

说明: 拼接一个消息数组或多个消息段到消息数组末尾。
参数
- obj (TM | Iterable[TMS]): 要添加的消息数组
返回
- TM

method `copy()`

参数
empty
返回
- TM

method `extract_plain_text()`

说明: 提取消息内纯文本消息
参数
empty
返回
- str

abstract class `MessageSegment(<auto>)`

说明: 消息段基类
参数
auto

instance-var `type`

类型: str
说明: 消息段类型

class-var `data`

类型: dict[str, Any]
说明: 消息段数据

abstract classmethod `get_message_class()`

说明: 获取消息数组类型
参数
empty
返回
- type[TM]

method `get(key, default=None)`

参数
- key (str)
- default (Any)
返回
- untyped

method `keys()`

参数
empty
返回
- untyped

method `values()`

参数
empty
返回
- untyped

method `items()`

参数
empty
返回
- untyped

method `copy()`

参数
empty
返回
- T

abstract method `is_text()`

说明: 当前消息段是否为纯文本
参数
empty
返回
- bool

class `MessageTemplate(template, factory=str)`

说明: 消息模板格式化实现类。
参数
- template (str | TM): 模板
- factory (type[str] | type[TM]): 消息类型工厂，默认为 str

method `add_format_spec(spec, name=None)`

参数
- spec (FormatSpecFunc_T)
- name (str | None)
返回
- FormatSpecFunc_T

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

说明: 根据传入参数和模板生成消息对象
参数
- *args
- **kwargs
返回
- untyped

method `format_map(mapping)`

说明: 根据传入字典和模板生成消息对象, 在传入字段名不是有效标识符时有用
参数
- mapping (Mapping[str, Any])
返回
- TF

method `vformat(format_string, args, kwargs)`

参数
- format_string (str)
- args (Sequence[Any])
- kwargs (Mapping[str, Any])
返回
- TF

method `format_field(value, format_spec)`

参数
- value (Any)
- format_spec (str)
返回
- Any

abstract class Bot(adapter, self_id)#

instance-var adapter#

instance-var self_id#

property type#

property config#

async method call_api(api, **data)#

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

classmethod on_calling_api(func)#

classmethod on_called_api(func)#

abstract class Event(<auto>)#

classmethod validate(value)#

abstract method get_type()#

abstract method get_event_name()#

abstract method get_event_description()#

method get_log_string()#

abstract method get_user_id()#

abstract method get_session_id()#

abstract method get_message()#

method get_plaintext()#

abstract method is_tome()#

abstract class Adapter(driver, **kwargs)#

instance-var driver#

instance-var bots#

abstract classmethod get_name()#

property config#

method bot_connect(bot)#

method bot_disconnect(bot)#

method setup_http_server(setup)#

method setup_websocket_server(setup)#

async method request(setup)#

method websocket(setup)#

abstract class Message(<auto>)#

classmethod template(format_string)#

abstract classmethod get_segment_class()#

method index(value, *args)#

method get(type_, count=None)#

method count(value)#

method append(obj)#

method extend(obj)#

method copy()#

method extract_plain_text()#

abstract class MessageSegment(<auto>)#

instance-var type#

class-var data#

abstract classmethod get_message_class()#

method get(key, default=None)#

method keys()#

method values()#

method items()#

method copy()#

abstract method is_text()#

class MessageTemplate(template, factory=str)#

method add_format_spec(spec, name=None)#

method format(*args, **kwargs)#

method format_map(mapping)#

method vformat(format_string, args, kwargs)#

method format_field(value, format_spec)#

abstract class `Bot(adapter, self_id)`

instance-var `adapter`

instance-var `self_id`

property `type`

property `config`

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

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

classmethod `on_calling_api(func)`

classmethod `on_called_api(func)`

abstract class `Event(<auto>)`

classmethod `validate(value)`

abstract method `get_type()`

abstract method `get_event_name()`

abstract method `get_event_description()`

method `get_log_string()`

abstract method `get_user_id()`

abstract method `get_session_id()`

abstract method `get_message()`

method `get_plaintext()`

abstract method `is_tome()`

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

instance-var `driver`

instance-var `bots`

abstract classmethod `get_name()`

property `config`

method `bot_connect(bot)`

method `bot_disconnect(bot)`

method `setup_http_server(setup)`

method `setup_websocket_server(setup)`

async method `request(setup)`

method `websocket(setup)`

abstract class `Message(<auto>)`

classmethod `template(format_string)`

abstract classmethod `get_segment_class()`

method `index(value, *args)`

method `get(type_, count=None)`

method `count(value)`

method `append(obj)`

method `extend(obj)`

method `copy()`

method `extract_plain_text()`

abstract class `MessageSegment(<auto>)`

instance-var `type`

class-var `data`

abstract classmethod `get_message_class()`

method `get(key, default=None)`

method `keys()`

method `values()`

method `items()`

method `copy()`

abstract method `is_text()`

class `MessageTemplate(template, factory=str)`

method `add_format_spec(spec, name=None)`

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

method `format_map(mapping)`

method `vformat(format_string, args, kwargs)`

method `format_field(value, format_spec)`