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

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: 希望 NoneBot 隐藏该事件日志

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]

method `on_ready(func)`

参数
- func (LIFESPAN_FUNC)
返回
- LIFESPAN_FUNC

abstract class `Message(<auto>)`

说明: 消息序列
参数
- message: 消息内容

classmethod `template(format_string)`

说明

创建消息模板。

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

abstract classmethod `get_segment_class()`

说明: 获取消息段类型
参数

empty
返回
- type[TMS]

abstract staticmethod `_construct(msg)`

说明: 构造消息数组
参数
- msg (str)
返回
- Iterable[TMS]

method `getitem(args)`

重载

1. (args) -> Self
- 参数
  - args (str): 消息段类型
- 返回
  - Self: 所有类型为 args 的消息段
2. (args) -> TMS
- 参数
  - args (tuple[str, int]): 消息段类型和索引
- 返回
  - TMS: 类型为 args[0] 的消息段第 args[1] 个
3. (args) -> Self
- 参数
  - args (tuple[str, slice]): 消息段类型和切片
- 返回
  - Self: 类型为 args[0] 的消息段切片 args[1]
4. (args) -> TMS
- 参数
  - args (int): 索引
- 返回
  - TMS: 第 args 个消息段
5. (args) -> Self
- 参数
  - args (slice): 切片
- 返回
  - Self: 消息切片 args

method `contains(value)`

说明: 检查消息段是否存在
参数
- value (TMS | str): 消息段或消息段类型
返回
- bool: 消息内是否存在给定消息段或给定类型的消息段

method `has(value)`

说明: 与 __contains__ 相同
参数
- value (TMS | str)
返回
- bool

method `index(value, *args)`

说明: 索引消息段
参数
- value (TMS | str): 消息段或者消息段类型
- *args (SupportsIndex)
- arg: start 与 end
返回
- int: 索引 index
异常
- ValueError: 消息段不存在

method `get(type_, count=None)`

说明: 获取指定类型的消息段
参数
- type_ (str): 消息段类型
- count (int | None): 获取个数
返回
- Self: 构建的新消息

method `count(value)`

说明: 计算指定消息段的个数
参数
- value (TMS | str): 消息段或消息段类型
返回
- int: 个数

method `only(value)`

说明: 检查消息中是否仅包含指定消息段
参数
- value (TMS | str): 指定消息段或消息段类型
返回
- bool: 是否仅包含指定消息段

method `append(obj)`

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

method `extend(obj)`

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

method `join(iterable)`

说明: 将多个消息连接并将自身作为分割
参数
- iterable (Iterable[TMS | Self]): 要连接的消息
返回
- Self: 连接后的消息

method `copy()`

说明: 深拷贝消息
参数

empty
返回
- Self

method `include(*types)`

说明: 过滤消息
参数
- *types (str): 包含的消息段类型
返回
- Self: 新构造的消息

method `exclude(*types)`

说明: 过滤消息
参数
- *types (str): 不包含的消息段类型
返回
- Self: 新构造的消息

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]

abstract method `str()`

说明: 该消息段所代表的 str，在命令匹配部分使用
参数

empty
返回
- str

method `add(other)`

参数
- other (str | TMS | Iterable[TMS])
返回
- TM

method `get(key, default=None)`

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

method `keys()`

参数

empty
返回
- untyped

method `values()`

参数

empty
返回
- untyped

method `items()`

参数

empty
返回
- untyped

method `join(iterable)`

参数
- iterable (Iterable[TMS | TM])
返回
- TM

method `copy()`

参数

empty
返回
- Self

abstract method `is_text()`

说明: 当前消息段是否为纯文本
参数

empty
返回
- bool

class `MessageTemplate(template, factory=str, private_getattr=False)`

说明: 消息模板格式化实现类。
参数
- template (str | TM): 模板
- factory (type[str] | type[TM]): 消息类型工厂，默认为 str
- private_getattr (bool): 是否允许在模板中访问私有属性，默认为 False

method `add_format_spec(spec, name=None)`

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

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

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

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 `get_field(field_name, args, kwargs)`

参数
- field_name (str)
- args (Sequence[Any])
- kwargs (Mapping[str, Any])
返回
- tuple[Any, int | str]

method `format_field(value, format_spec)`

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

2.4.0Stable

NextDevelopment

2.4.0Stable

NextDevelopment

2.4.0Stable

NextDevelopment

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>)​

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)​

method on_ready(func)​

abstract class Message(<auto>)​

classmethod template(format_string)​

abstract classmethod get_segment_class()​

abstract staticmethod _construct(msg)​

method __getitem__(args)​

method __contains__(value)​

method has(value)​

method index(value, *args)​

method get(type_, count=None)​

method count(value)​

method only(value)​

method append(obj)​

method extend(obj)​

method join(iterable)​

method copy()​

method include(*types)​

method exclude(*types)​

method extract_plain_text()​

abstract class MessageSegment(<auto>)​

instance-var type​

class-var data​

abstract classmethod get_message_class()​

abstract method __str__()​

method __add__(other)​

method get(key, default=None)​

method keys()​

method values()​

method items()​

method join(iterable)​

method copy()​

abstract method is_text()​

class MessageTemplate(template, factory=str, private_getattr=False)​

method add_format_spec(spec, name=None)​

method format(*args, **kwargs)​

method format_map(mapping)​

method vformat(format_string, args, kwargs)​

method get_field(field_name, 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>)`

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

method `on_ready(func)`

abstract class `Message(<auto>)`

classmethod `template(format_string)`

abstract classmethod `get_segment_class()`

abstract staticmethod `_construct(msg)`

method `getitem(args)`

method `contains(value)`

method `has(value)`

method `index(value, *args)`

method `get(type_, count=None)`

method `count(value)`

method `only(value)`

method `append(obj)`

method `extend(obj)`

method `join(iterable)`

method `copy()`

method `include(*types)`

method `exclude(*types)`

method `extract_plain_text()`

abstract class `MessageSegment(<auto>)`

instance-var `type`

class-var `data`

abstract classmethod `get_message_class()`

abstract method `str()`

method `add(other)`

method `get(key, default=None)`

method `keys()`

method `values()`

method `items()`

method `join(iterable)`

method `copy()`

abstract method `is_text()`

class `MessageTemplate(template, factory=str, private_getattr=False)`

method `add_format_spec(spec, name=None)`

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

method `format_map(mapping)`

method `vformat(format_string, args, kwargs)`

method `get_field(field_name, args, kwargs)`

method `format_field(value, format_spec)`