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)
返回
classmethod on_called_api(func)
说明
调用 api 后处理。
钩子函数参数:
- bot: 当前 bot 对象
- exception: 调用 api 时发生的错误
- api: 调用的 api 名称
- data: api 调用的参数字典
- result: api 调用的返回
参数
func
(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
返回
method get_plaintext()
说明
获取消息纯文本的方法。
通常不需要修改,默认通过
get_message().extract_plain_text
获取。参数
empty
返回
- str
abstract method is_tome()
说明: 获取事件是否与机器人有关的方法。
参数
empty
返回
- bool
abstract class Adapter(driver, **kwargs)
说明
协议适配器基类。
通常,在 Adapter 中编写协议通信相关代码,如: 建立通信连接、处理接收与发送 data 等。
参数
**kwargs
(Any): 其他由 Driver.register_adapter 传入的额外参数
instance-var driver
类型: Driver
说明: 实例
instance-var bots
abstract classmethod get_name()
说明: 当前协议适配器的名称
参数
empty
返回
- str
property config
类型: Config
说明: 全局 NoneBot 配置
method bot_connect(bot)
method bot_disconnect(bot)
method setup_http_server(setup)
说明: 设置一个 HTTP 服务器路由配置
参数
setup
(HTTPServerSetup)
返回
- untyped
method setup_websocket_server(setup)
说明: 设置一个 WebSocket 服务器路由配置
参数
setup
(WebSocketServerSetup)
返回
- untyped
async method request(setup)
method websocket(setup)
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
的消息段
- Self: 所有类型为
2.
(args) -> TMS
参数
args
(tuple[str, int]): 消息段类型和索引
返回
- TMS: 类型为
args[0]
的消息段第args[1]
个
- TMS: 类型为
3.
(args) -> Self
参数
args
(tuple[str, slice]): 消息段类型和切片
返回
- Self: 类型为
args[0]
的消息段切片args[1]
- Self: 类型为
4.
(args) -> TMS
参数
args
(int): 索引
返回
- TMS: 第
args
个消息段
- TMS: 第
5.
(args) -> Self
参数
args
(slice): 切片
返回
- Self: 消息切片
args
- Self: 消息切片
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