nonebot2/website/versioned_docs/version-2.3.2/api/adapters/index.md
noneflow[bot] 4d070f5b48 🔖 Release 2.3.2
2024-07-06 12:34:00 +00:00

14 KiB
Raw Blame History

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

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)

  • 说明: 调用机器人基础发送消息接口

  • 参数

  • 返回

    • Any

classmethod on_calling_api(func)

  • 说明

    调用 api 预处理。

    钩子函数参数:

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

  • 返回

classmethod on_called_api(func)

  • 说明

    调用 api 后处理。

    钩子函数参数:

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

  • 返回

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

  • 返回

method get_plaintext()

  • 说明

    获取消息纯文本的方法。

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

  • 参数

    empty

  • 返回

    • str

abstract method is_tome()

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

  • 参数

    empty

  • 返回

    • bool

abstract class Adapter(driver, **kwargs)

  • 说明

    协议适配器基类。

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

  • 参数

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 实例连接建立成功时调用。

  • 参数

  • 返回

    • None

method bot_disconnect(bot)

  • 说明

    告知 NoneBot Bot 连接已断开。

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

  • 参数

  • 返回

    • None

method setup_http_server(setup)

  • 说明: 设置一个 HTTP 服务器路由配置

  • 参数

  • 返回

    • untyped

method setup_websocket_server(setup)

  • 说明: 设置一个 WebSocket 服务器路由配置

  • 参数

  • 返回

    • untyped

async method request(setup)

  • 说明: 进行一个 HTTP 客户端请求

  • 参数

  • 返回

method websocket(setup)

  • 说明: 建立一个 WebSocket 客户端连接请求

  • 参数

  • 返回

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): 格式化模板
  • 返回

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