nonebot2/website/versioned_docs/version-2.4.0/api/adapters/index.md

mdx, sidebar_position, description

mdx	sidebar_position	description
format md	0	nonebot.adapters 模块

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