diff --git a/archive/2.0.0a5/README.md b/archive/2.0.0a5/README.md new file mode 100644 index 00000000..a1607904 --- /dev/null +++ b/archive/2.0.0a5/README.md @@ -0,0 +1,15 @@ +--- +home: true +heroImage: /logo.png +tagline: An asynchronous QQ bot framework. +actionText: 开始使用 +actionLink: guide/ +features: + - title: 简洁 + details: 提供极其简洁易懂的 API，使你可以毫无压力地开始验证你的绝佳创意，只需编写最少量的代码，即可实现丰富的功能。 + - title: 易于扩展 + details: 精心设计的消息处理流程使得你可以很方便地将原型扩充为具有大量实用功能的完整聊天机器人，并持续保证扩展性。 + - title: 高性能 + details: 采用异步 I/O，利用 WebSocket 进行通信，以获得极高的性能；同时，支持使用多账号同时接入，减少业务宕机的可能。 +footer: MIT Licensed | Copyright © 2020 NoneBot Team +--- diff --git a/archive/2.0.0a5/api/README.md b/archive/2.0.0a5/api/README.md new file mode 100644 index 00000000..75132b72 --- /dev/null +++ b/archive/2.0.0a5/api/README.md @@ -0,0 +1,52 @@ +# NoneBot Api Reference + + +* **模块索引** + + + * [nonebot](nonebot.html) + + + * [nonebot.config](config.html) + + + * [nonebot.plugin](plugin.html) + + + * [nonebot.message](message.html) + + + * [nonebot.matcher](matcher.html) + + + * [nonebot.rule](rule.html) + + + * [nonebot.permission](permission.html) + + + * [nonebot.sched](sched.html) + + + * [nonebot.log](log.html) + + + * [nonebot.utils](utils.html) + + + * [nonebot.typing](typing.html) + + + * [nonebot.exception](exception.html) + + + * [nonebot.drivers](drivers/) + + + * [nonebot.drivers.fastapi](drivers/fastapi.html) + + + * [nonebot.adapters](adapters/) + + + * [nonebot.adapters.cqhttp](adapters/cqhttp.html) diff --git a/archive/2.0.0a5/api/adapters/README.md b/archive/2.0.0a5/api/adapters/README.md new file mode 100644 index 00000000..c2d2e399 --- /dev/null +++ b/archive/2.0.0a5/api/adapters/README.md @@ -0,0 +1,362 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.adapters 模块 + +## 协议适配基类 + +各协议请继承以下基类，并使用 `driver.register_adapter` 注册适配器 + + +## _class_ `BaseBot` + +基类：`abc.ABC` + +Bot 基类。用于处理上报消息，并提供 API 调用接口。 + + +### _abstract_ `__init__(driver, connection_type, config, self_id, *, websocket=None)` + + +* **参数** + + + * `driver: Driver`: Driver 对象 + + + * `connection_type: str`: http 或者 websocket + + + * `config: Config`: Config 对象 + + + * `self_id: str`: 机器人 ID + + + * `websocket: Optional[WebSocket]`: Websocket 连接对象 + + + +### `driver` + +Driver 对象 + + +### `connection_type` + +连接类型 + + +### `config` + +Config 配置对象 + + +### `self_id` + +机器人 ID + + +### `websocket` + +Websocket 连接对象 + + +### _abstract property_ `type` + +Adapter 类型 + + +### _abstract async classmethod_ `check_permission(driver, connection_type, headers, body)` + + +* **说明** + + 检查连接请求是否合法的函数，如果合法则返回当前连接 `唯一标识符`，通常为机器人 ID；如果不合法则抛出 `RequestDenied` 异常。 + + + +* **参数** + + + * `driver: Driver`: Driver 对象 + + + * `connection_type: str`: 连接类型 + + + * `headers: dict`: 请求头 + + + * `body: Optional[dict]`: 请求数据，WebSocket 连接该部分为空 + + + +* **返回** + + + * `str`: 连接唯一标识符 + + + +* **异常** + + + * `RequestDenied`: 请求非法 + + + +### _abstract async_ `handle_message(message)` + + +* **说明** + + 处理上报消息的函数，转换为 `Event` 事件后调用 `nonebot.message.handle_event` 进一步处理事件。 + + + +* **参数** + + + * `message: dict`: 收到的上报消息 + + + +### _abstract async_ `call_api(api, **data)` + + +* **说明** + + 调用机器人 API 接口，可以通过该函数或直接通过 bot 属性进行调用 + + + +* **参数** + + + * `api: str`: API 名称 + + + * `**data`: API 数据 + + + +* **示例** + + +```python +await bot.call_api("send_msg", message="hello world"}) +await bot.send_msg(message="hello world") +``` + + +### _abstract async_ `send(event, message, **kwargs)` + + +* **说明** + + 调用机器人基础发送消息接口 + + + +* **参数** + + + * `event: Event`: 上报事件 + + + * `message: Union[str, Message, MessageSegment]`: 要发送的消息 + + + * `**kwargs` + + + +## _class_ `BaseEvent` + +基类：`abc.ABC` + +Event 基类。提供上报信息的关键信息，其余信息可从原始上报消息获取。 + + +### `__init__(raw_event)` + + +* **参数** + + + * `raw_event: dict`: 原始上报消息 + + + +### _property_ `raw_event` + +原始上报消息 + + +### _abstract property_ `id` + +事件 ID + + +### _abstract property_ `name` + +事件名称 + + +### _abstract property_ `self_id` + +机器人 ID + + +### _abstract property_ `time` + +事件发生时间 + + +### _abstract property_ `type` + +事件主类型 + + +### _abstract property_ `detail_type` + +事件详细类型 + + +### _abstract property_ `sub_type` + +事件子类型 + + +### _abstract property_ `user_id` + +触发事件的主体 ID + + +### _abstract property_ `group_id` + +触发事件的主体群 ID + + +### _abstract property_ `to_me` + +事件是否为发送给机器人的消息 + + +### _abstract property_ `message` + +消息内容 + + +### _abstract property_ `reply` + +回复的消息 + + +### _abstract property_ `raw_message` + +原始消息 + + +### _abstract property_ `plain_text` + +纯文本消息 + + +### _abstract property_ `sender` + +消息发送者信息 + + +## _class_ `BaseMessageSegment` + +基类：`abc.ABC` + +消息段基类 + + +### `type` + + +* 类型: `str` + + +* 说明: 消息段类型 + + +### `data` + + +* 类型: `Dict[str, Union[str, list]]` + + +* 说明: 消息段数据 + + +## _class_ `BaseMessage` + +基类：`list`, `abc.ABC` + +消息数组 + + +### `__init__(message=None, *args, **kwargs)` + + +* **参数** + + + * `message: Union[str, dict, list, MessageSegment, Message]`: 消息内容 + + + +### `append(obj)` + + +* **说明** + + 添加一个消息段到消息数组末尾 + + + +* **参数** + + + * `obj: Union[str, MessageSegment]`: 要添加的消息段 + + + +### `extend(obj)` + + +* **说明** + + 拼接一个消息数组或多个消息段到消息数组末尾 + + + +* **参数** + + + * `obj: Union[Message, Iterable[MessageSegment]]`: 要添加的消息数组 + + + +### `reduce()` + + +* **说明** + + 缩减消息数组，即拼接相邻纯文本消息段 + + + +### `extract_plain_text()` + + +* **说明** + + 提取消息内纯文本消息 diff --git a/archive/2.0.0a5/api/adapters/cqhttp.md b/archive/2.0.0a5/api/adapters/cqhttp.md new file mode 100644 index 00000000..aa6ad47f --- /dev/null +++ b/archive/2.0.0a5/api/adapters/cqhttp.md @@ -0,0 +1,424 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.adapters.cqhttp 模块 + +## CQHTTP (OneBot) v11 协议适配 + +协议详情请看: [CQHTTP](http://cqhttp.cc/) | [OneBot](https://github.com/howmanybots/onebot) + + +## `log(level, message)` + + +* **说明** + + 用于打印 CQHTTP 日志。 + + + +* **参数** + + + * `level: str`: 日志等级 + + + * `message: str`: 日志信息 + + + +## `escape(s, *, escape_comma=True)` + + +* **说明** + + 对字符串进行 CQ 码转义。 + + + +* **参数** + + + * `s: str`: 需要转义的字符串 + + + * `escape_comma: bool`: 是否转义逗号（`,`）。 + + + +## `unescape(s)` + + +* **说明** + + 对字符串进行 CQ 码去转义。 + + + +* **参数** + + + * `s: str`: 需要转义的字符串 + + + +## `_b2s(b)` + +转换布尔值为字符串。 + + +## _async_ `_check_reply(bot, event)` + + +* **说明** + + 检查消息中存在的回复，去除并赋值 `event.reply`, `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_check_at_me(bot, event)` + + +* **说明** + + 检查消息开头或结尾是否存在 @机器人，去除并赋值 `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_check_nickname(bot, event)` + + +* **说明** + + 检查消息开头是否存在，去除并赋值 `event.to_me` + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +## `_handle_api_result(result)` + + +* **说明** + + 处理 API 请求返回值。 + + + +* **参数** + + + * `result: Optional[Dict[str, Any]]`: API 返回数据 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `ActionFailed`: API 调用失败 + + + +## _class_ `Bot` + +基类：[`nonebot.adapters.BaseBot`](README.md#nonebot.adapters.BaseBot) + +CQHTTP 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。 + + +### _property_ `type` + + +* 返回: `"cqhttp"` + + +### _async classmethod_ `check_permission(driver, connection_type, headers, body)` + + +* **说明** + + CQHTTP (OneBot) 协议鉴权。参考 [鉴权](https://github.com/howmanybots/onebot/blob/master/v11/specs/communication/authorization.md) + + + +### _async_ `handle_message(message)` + + +* **说明** + + 调用 [_check_reply](#async-check-reply-bot-event), [_check_at_me](#check-at-me-bot-event), [_check_nickname](#check-nickname-bot-event) 处理事件并转换为 [Event](#class-event) + + + +### _async_ `call_api(api, **data)` + + +* **说明** + + 调用 CQHTTP 协议 API + + + +* **参数** + + + * `api: str`: API 名称 + + + * `**data: Any`: API 参数 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `NetworkError`: 网络错误 + + + * `ActionFailed`: API 调用失败 + + + +### _async_ `send(event, message, at_sender=False, **kwargs)` + + +* **说明** + + 根据 `event` 向触发事件的主体发送消息。 + + + +* **参数** + + + * `event: Event`: Event 对象 + + + * `message: Union[str, Message, MessageSegment]`: 要发送的消息 + + + * `at_sender: bool`: 是否 @ 事件主体 + + + * `**kwargs`: 覆盖默认参数 + + + +* **返回** + + + * `Any`: API 调用返回数据 + + + +* **异常** + + + * `ValueError`: 缺少 `user_id`, `group_id` + + + * `NetworkError`: 网络错误 + + + * `ActionFailed`: API 调用失败 + + + +## _class_ `Event` + +基类：[`nonebot.adapters.BaseEvent`](README.md#nonebot.adapters.BaseEvent) + +CQHTTP 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent) 。 + + +### _property_ `id` + + +* 类型: `Optional[int]` + + +* 说明: 事件/消息 ID + + +### _property_ `name` + + +* 类型: `str` + + +* 说明: 事件名称，由类型与 `.` 组合而成 + + +### _property_ `self_id` + + +* 类型: `str` + + +* 说明: 机器人自身 ID + + +### _property_ `time` + + +* 类型: `int` + + +* 说明: 事件发生时间 + + +### _property_ `type` + + +* 类型: `str` + + +* 说明: 事件类型 + + +### _property_ `detail_type` + + +* 类型: `str` + + +* 说明: 事件详细类型 + + +### _property_ `sub_type` + + +* 类型: `Optional[str]` + + +* 说明: 事件子类型 + + +### _property_ `user_id` + + +* 类型: `Optional[int]` + + +* 说明: 事件主体 ID + + +### _property_ `group_id` + + +* 类型: `Optional[int]` + + +* 说明: 事件主体群 ID + + +### _property_ `to_me` + + +* 类型: `Optional[bool]` + + +* 说明: 消息是否与机器人相关 + + +### _property_ `message` + + +* 类型: `Optional[Message]` + + +* 说明: 消息内容 + + +### _property_ `reply` + + +* 类型: `Optional[dict]` + + +* 说明: 回复消息详情 + + +### _property_ `raw_message` + + +* 类型: `Optional[str]` + + +* 说明: 原始消息 + + +### _property_ `plain_text` + + +* 类型: `Optional[str]` + + +* 说明: 纯文本消息内容 + + +### _property_ `sender` + + +* 类型: `Optional[dict]` + + +* 说明: 消息发送者信息 + + +## _class_ `MessageSegment` + +基类：[`nonebot.adapters.BaseMessageSegment`](README.md#nonebot.adapters.BaseMessageSegment) + +CQHTTP 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。 + + +## _class_ `Message` + +基类：[`nonebot.adapters.BaseMessage`](README.md#nonebot.adapters.BaseMessage) + +CQHTTP 协议 Message 适配。 diff --git a/archive/2.0.0a5/api/config.md b/archive/2.0.0a5/api/config.md new file mode 100644 index 00000000..6943427b --- /dev/null +++ b/archive/2.0.0a5/api/config.md @@ -0,0 +1,265 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.config 模块 + +## 配置 + +NoneBot 使用 [pydantic](https://pydantic-docs.helpmanual.io/) 以及 [python-dotenv](https://saurabh-kumar.com/python-dotenv/) 来读取配置。 + +配置项需符合特殊格式或 json 序列化格式。详情见 [pydantic Field Type](https://pydantic-docs.helpmanual.io/usage/types/) 文档。 + + +## _class_ `Env` + +基类：`pydantic.env_settings.BaseSettings` + +运行环境配置。大小写不敏感。 + +将会从 `nonebot.init 参数` > `环境变量` > `.env 环境配置文件` 的优先级读取配置。 + + +### `environment` + + +* 类型: `str` + + +* 默认值: `"prod"` + + +* 说明: +当前环境名。 NoneBot 将从 `.env.{environment}` 文件中加载配置。 + + +## _class_ `Config` + +基类：`nonebot.config.BaseConfig` + +NoneBot 主要配置。大小写不敏感。 + +除了 NoneBot 的配置项外，还可以自行添加配置项到 `.env.{environment}` 文件中。 +这些配置将会在 json 反序列化后一起带入 `Config` 类中。 + + +### `driver` + + +* 类型: `str` + + +* 默认值: `"nonebot.drivers.fastapi"` + + +* 说明: +NoneBot 运行所使用的 `Driver` 。继承自 `nonebot.driver.BaseDriver` 。 + + +### `host` + + +* 类型: `IPvAnyAddress` + + +* 默认值: `127.0.0.1` + + +* 说明: +NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。 + + +### `port` + + +* 类型: `int` + + +* 默认值: `8080` + + +* 说明: +NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。 + + +### `debug` + + +* 类型: `bool` + + +* 默认值: `False` + + +* 说明: +是否以调试模式运行 NoneBot。 + + +### `api_root` + + +* 类型: `Dict[str, str]` + + +* 默认值: `{}` + + +* 说明: +以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。 + + +* 示例: + +```default +API_ROOT={"123456": "http://127.0.0.1:5700"} +``` + + +### `api_timeout` + + +* 类型: `Optional[float]` + + +* 默认值: `30.` + + +* 说明: +API 请求超时时间，单位: 秒。 + + +### `access_token` + + +* 类型: `Optional[str]` + + +* 默认值: `None` + + +* 说明: +API 请求以及上报所需密钥，在请求头中携带。 + + +* 示例: + +```http +POST /cqhttp/ HTTP/1.1 +Authorization: Bearer kSLuTF2GC2Q4q4ugm3 +``` + + +### `secret` + + +* 类型: `Optional[str]` + + +* 默认值: `None` + + +* 说明: +HTTP POST 形式上报所需签名，在请求头中携带。 + + +* 示例: + +```http +POST /cqhttp/ HTTP/1.1 +X-Signature: sha1=f9ddd4863ace61e64f462d41ca311e3d2c1176e2 +``` + + +### `superusers` + + +* 类型: `Set[int]` + + +* 默认值: `set()` + + +* 说明: +机器人超级用户。 + + +* 示例: + +```default +SUPER_USERS=[12345789] +``` + + +### `nickname` + + +* 类型: `Set[str]` + + +* 默认值: `set()` + + +* 说明: +机器人昵称。 + + +### `command_start` + + +* 类型: `Set[str]` + + +* 默认值: `{"/"}` + + +* 说明: +命令的起始标记，用于判断一条消息是不是命令。 + + +### `command_sep` + + +* 类型: `Set[str]` + + +* 默认值: `{"."}` + + +* 说明: +命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。 + + +### `session_expire_timeout` + + +* 类型: `timedelta` + + +* 默认值: `timedelta(minutes=2)` + + +* 说明: +等待用户回复的超时时间。 + + +* 示例: + +```default +SESSION_EXPIRE_TIMEOUT=120 # 单位: 秒 +SESSION_EXPIRE_TIMEOUT=[DD ][HH:MM]SS[.ffffff] +SESSION_EXPIRE_TIMEOUT=P[DD]DT[HH]H[MM]M[SS]S # ISO 8601 +``` + + +### `apscheduler_config` + + +* 类型: `dict` + + +* 默认值: `{"apscheduler.timezone": "Asia/Shanghai"}` + + +* 说明: +APScheduler 的配置对象，见 [Configuring the Scheduler](https://apscheduler.readthedocs.io/en/latest/userguide.html#configuring-the-scheduler) diff --git a/archive/2.0.0a5/api/drivers/README.md b/archive/2.0.0a5/api/drivers/README.md new file mode 100644 index 00000000..624220ba --- /dev/null +++ b/archive/2.0.0a5/api/drivers/README.md @@ -0,0 +1,246 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.drivers 模块 + +## 后端驱动适配基类 + +各驱动请继承以下基类 + + +## _class_ `BaseDriver` + +基类：`abc.ABC` + +Driver 基类。将后端框架封装，以满足适配器使用。 + + +### `_adapters` + + +* **类型** + + `Dict[str, Type[Bot]]` + + + +* **说明** + + 已注册的适配器列表 + + + +### _abstract_ `__init__(env, config)` + + +* **参数** + + + * `env: Env`: 包含环境信息的 Env 对象 + + + * `config: Config`: 包含配置信息的 Config 对象 + + + +### `env` + + +* **类型** + + `str` + + + +* **说明** + + 环境名称 + + + +### `config` + + +* **类型** + + `Config` + + + +* **说明** + + 配置对象 + + + +### `_clients` + + +* **类型** + + `Dict[str, Bot]` + + + +* **说明** + + 已连接的 Bot + + + +### _classmethod_ `register_adapter(name, adapter)` + + +* **说明** + + 注册一个协议适配器 + + + +* **参数** + + + * `name: str`: 适配器名称，用于在连接时进行识别 + + + * `adapter: Type[Bot]`: 适配器 Class + + + +### _abstract property_ `type` + +驱动类型名称 + + +### _abstract property_ `server_app` + +驱动 APP 对象 + + +### _abstract property_ `asgi` + +驱动 ASGI 对象 + + +### _abstract property_ `logger` + +驱动专属 logger 日志记录器 + + +### _property_ `bots` + + +* **类型** + + `Dict[str, Bot]` + + + +* **说明** + + 获取当前所有已连接的 Bot + + + +### _abstract_ `on_startup(func)` + +注册一个在驱动启动时运行的函数 + + +### _abstract_ `on_shutdown(func)` + +注册一个在驱动停止时运行的函数 + + +### _abstract_ `run(host=None, port=None, *args, **kwargs)` + + +* **说明** + + 启动驱动框架 + + + +* **参数** + + + * `host: Optional[str]`: 驱动绑定 IP + + + * `post: Optional[int]`: 驱动绑定端口 + + + * `*args` + + + * `**kwargs` + + + +### _abstract async_ `_handle_http()` + +用于处理 HTTP 类型请求的函数 + + +### _abstract async_ `_handle_ws_reverse()` + +用于处理 WebSocket 类型请求的函数 + + +## _class_ `BaseWebSocket` + +基类：`object` + +WebSocket 连接封装，统一接口方便外部调用。 + + +### _abstract_ `__init__(websocket)` + + +* **参数** + + + * `websocket: Any`: WebSocket 连接对象 + + + +### _property_ `websocket` + +WebSocket 连接对象 + + +### _abstract property_ `closed` + + +* **类型** + + `bool` + + + +* **说明** + + 连接是否已经关闭 + + + +### _abstract async_ `accept()` + +接受 WebSocket 连接请求 + + +### _abstract async_ `close(code)` + +关闭 WebSocket 连接请求 + + +### _abstract async_ `receive()` + +接收一条 WebSocket 信息 + + +### _abstract async_ `send(data)` + +发送一条 WebSocket 信息 diff --git a/archive/2.0.0a5/api/drivers/fastapi.md b/archive/2.0.0a5/api/drivers/fastapi.md new file mode 100644 index 00000000..1f7f96ee --- /dev/null +++ b/archive/2.0.0a5/api/drivers/fastapi.md @@ -0,0 +1,102 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.drivers.fastapi 模块 + +## FastAPI 驱动适配 + +后端使用方法请参考: [FastAPI 文档](https://fastapi.tiangolo.com/) + + +## _class_ `Driver` + +基类：[`nonebot.drivers.BaseDriver`](README.md#nonebot.drivers.BaseDriver) + +FastAPI 驱动框架 + + +### _property_ `type` + +驱动名称: `fastapi` + + +### _property_ `server_app` + +`FastAPI APP` 对象 + + +### _property_ `asgi` + +`FastAPI APP` 对象 + + +### _property_ `logger` + +fastapi 使用的 logger + + +### `on_startup(func)` + +参考文档: [Events](https://fastapi.tiangolo.com/advanced/events/#startup-event) + + +### `on_shutdown(func)` + +参考文档: [Events](https://fastapi.tiangolo.com/advanced/events/#startup-event) + + +### `run(host=None, port=None, *, app=None, **kwargs)` + +使用 `uvicorn` 启动 FastAPI + + +### _async_ `_handle_http(adapter, request, data=Body(Ellipsis))` + +用于处理 HTTP 类型请求的函数 + + +### _async_ `_handle_ws_reverse(adapter, websocket)` + +用于处理 WebSocket 类型请求的函数 + + +## _class_ `WebSocket` + +基类：[`nonebot.drivers.BaseWebSocket`](README.md#nonebot.drivers.BaseWebSocket) + + +### _property_ `closed` + + +* **类型** + + `bool` + + + +* **说明** + + 连接是否已经关闭 + + + +### _async_ `accept()` + +接受 WebSocket 连接请求 + + +### _async_ `close(code=1000)` + +关闭 WebSocket 连接请求 + + +### _async_ `receive()` + +接收一条 WebSocket 信息 + + +### _async_ `send(data)` + +发送一条 WebSocket 信息 diff --git a/archive/2.0.0a5/api/exception.md b/archive/2.0.0a5/api/exception.md new file mode 100644 index 00000000..0a9876a8 --- /dev/null +++ b/archive/2.0.0a5/api/exception.md @@ -0,0 +1,160 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.exception 模块 + +## 异常 + +下列文档中的异常是所有 NoneBot 运行时可能会抛出的。 +这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。 + + +## _exception_ `IgnoredException` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。 + + + +* **参数** + + + * `reason`: 忽略事件的原因 + + + +## _exception_ `PausedException` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 结束当前 `Handler` 并等待下一条消息后继续下一个 `Handler`。 + 可用于用户输入新信息。 + + + +* **用法** + + 可以在 `Handler` 中通过 `Matcher.pause()` 抛出。 + + + +## _exception_ `RejectedException` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 结束当前 `Handler` 并等待下一条消息后重新运行当前 `Handler`。 + 可用于用户重新输入。 + + + +* **用法** + + 可以在 `Handler` 中通过 `Matcher.reject()` 抛出。 + + + +## _exception_ `FinishedException` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 结束当前 `Handler` 且后续 `Handler` 不再被运行。 + 可用于结束用户会话。 + + + +* **用法** + + 可以在 `Handler` 中通过 `Matcher.finish()` 抛出。 + + + +## _exception_ `StopPropagation` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 终止事件向下层传播。 + + + +* **用法** + + 在 `Matcher.block == True` 时抛出。 + + + +## _exception_ `RequestDenied` + +基类：`Exception` + + +* **说明** + + Bot 连接请求不合法。 + + + +* **参数** + + + * `status_code: int`: HTTP 状态码 + + + * `reason: str`: 拒绝原因 + + + +## _exception_ `ApiNotAvailable` + +基类：`Exception` + + +* **说明** + + 在 API 连接不可用时抛出。 + + + +## _exception_ `NetworkError` + +基类：`Exception` + + +* **说明** + + 在网络出现问题时抛出，如: API 请求地址不正确, API 请求无返回或返回状态非正常等。 + + + +## _exception_ `ActionFailed` + +基类：`Exception` + + +* **说明** + + API 请求成功返回数据，但 API 操作失败。 + + + +* **参数** + + + * `retcode: Optional[int]`: 错误代码 diff --git a/archive/2.0.0a5/api/log.md b/archive/2.0.0a5/api/log.md new file mode 100644 index 00000000..77ce3609 --- /dev/null +++ b/archive/2.0.0a5/api/log.md @@ -0,0 +1,55 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.log 模块 + +## 日志 + +NoneBot 使用 [loguru](https://github.com/Delgan/loguru) 来记录日志信息。 + +自定义 logger 请参考 [loguru](https://github.com/Delgan/loguru) 文档。 + + +## `logger` + + +* **说明** + + NoneBot 日志记录器对象。 + + + +* **默认信息** + + + * 格式: `[%(asctime)s %(name)s] %(levelname)s: %(message)s` + + + * 等级: `DEBUG` / `INFO` ，根据 config 配置改变 + + + * 输出: 输出至 stdout + + + +* **用法** + + +```python +from nonebot.log import logger +``` + + +## _class_ `LoguruHandler` + +基类：`logging.Handler` + + +### `emit(record)` + +Do whatever it takes to actually log the specified logging record. + +This version is intended to be implemented by subclasses and so +raises a NotImplementedError. diff --git a/archive/2.0.0a5/api/matcher.md b/archive/2.0.0a5/api/matcher.md new file mode 100644 index 00000000..b061cd64 --- /dev/null +++ b/archive/2.0.0a5/api/matcher.md @@ -0,0 +1,497 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.matcher 模块 + +## 事件响应器 + +该模块实现事件响应器的创建与运行，并提供一些快捷方法来帮助用户更好的与机器人进行 对话 。 + + +## `matchers` + + +* **类型** + + `Dict[int, List[Type[Matcher]]]` + + + +* **说明** + + 用于存储当前所有的事件响应器 + + + +## _class_ `Matcher` + +基类：`object` + +事件响应器类 + + +### `module` + + +* **类型** + + `Optional[str]` + + + +* **说明** + + 事件响应器所在模块名称 + + + +### `type` + + +* **类型** + + `str` + + + +* **说明** + + 事件响应器类型 + + + +### `rule` + + +* **类型** + + `Rule` + + + +* **说明** + + 事件响应器匹配规则 + + + +### `permission` + + +* **类型** + + `Permission` + + + +* **说明** + + 事件响应器触发权限 + + + +### `priority` + + +* **类型** + + `int` + + + +* **说明** + + 事件响应器优先级 + + + +### `block` + + +* **类型** + + `bool` + + + +* **说明** + + 事件响应器是否阻止事件传播 + + + +### `temp` + + +* **类型** + + `bool` + + + +* **说明** + + 事件响应器是否为临时 + + + +### `expire_time` + + +* **类型** + + `Optional[datetime]` + + + +* **说明** + + 事件响应器过期时间点 + + + +### `_default_state` + + +* **类型** + + `dict` + + + +* **说明** + + 事件响应器默认状态 + + + +### `_default_parser` + + +* **类型** + + `Optional[ArgsParser]` + + + +* **说明** + + 事件响应器默认参数解析函数 + + + +### `__init__()` + +实例化 Matcher 以便运行 + + +### `handlers` + + +* **类型** + + `List[Handler]` + + + +* **说明** + + 事件响应器拥有的事件处理函数列表 + + + +### _classmethod_ `new(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)` + + +* **说明** + + 创建一个新的事件响应器，并存储至 [matchers](#matchers) + + + +* **参数** + + + * `type_: str`: 事件响应器类型，与 `event.type` 一致时触发，空字符串表示任意 + + + * `rule: Optional[Rule]`: 匹配规则 + + + * `permission: Optional[Permission]`: 权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器，即触发一次后删除 + + + * `priority: int`: 响应优先级 + + + * `block: bool`: 是否阻止事件向更低优先级的响应器传播 + + + * `module: Optional[str]`: 事件响应器所在模块名称 + + + * `default_state: Optional[dict]`: 默认状态 `state` + + + * `expire_time: Optional[datetime]`: 事件响应器最终有效时间点，过时即被删除 + + + +* **返回** + + + * `Type[Matcher]`: 新的事件响应器类 + + + +### _async classmethod_ `check_perm(bot, event)` + + +* **说明** + + 检查是否满足触发权限 + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: 上报事件 + + + +* **返回** + + + * `bool`: 是否满足权限 + + + +### _async classmethod_ `check_rule(bot, event, state)` + + +* **说明** + + 检查是否满足匹配规则 + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: 上报事件 + + + * `state: dict`: 当前状态 + + + +* **返回** + + + * `bool`: 是否满足匹配规则 + + + +### _classmethod_ `args_parser(func)` + + +* **说明** + + 装饰一个函数来更改当前事件响应器的默认参数解析函数 + + + +* **参数** + + + * `func: ArgsParser`: 参数解析函数 + + + +### _classmethod_ `handle()` + + +* **说明** + + 装饰一个函数来向事件响应器直接添加一个处理函数 + + + +* **参数** + + + * 无 + + + +### _classmethod_ `receive()` + + +* **说明** + + 装饰一个函数来指示 NoneBot 在接收用户新的一条消息后继续运行该函数 + + + +* **参数** + + + * 无 + + + +### _classmethod_ `got(key, prompt=None, args_parser=None)` + + +* **说明** + + 装饰一个函数来指示 NoneBot 当要获取的 `key` 不存在时接收用户新的一条消息并经过 `ArgsParser` 处理后再运行该函数，如果 `key` 已存在则直接继续运行 + + + +* **参数** + + + * `key: str`: 参数名 + + + * `prompt: Optional[Union[str, Message, MessageSegment]]`: 在参数不存在时向用户发送的消息 + + + * `args_parser: Optional[ArgsParser]`: 可选参数解析函数，空则使用默认解析函数 + + + +### _async classmethod_ `send(message, **kwargs)` + + +* **说明** + + 发送一条消息给当前交互用户 + + + +* **参数** + + + * `message: Union[str, Message, MessageSegment]`: 消息内容 + + + * `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api + + + +### _async classmethod_ `finish(message=None, **kwargs)` + + +* **说明** + + 发送一条消息给当前交互用户并结束当前事件响应器 + + + +* **参数** + + + * `message: Union[str, Message, MessageSegment]`: 消息内容 + + + * `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api + + + +### _async classmethod_ `pause(prompt=None, **kwargs)` + + +* **说明** + + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后继续下一个处理函数 + + + +* **参数** + + + * `prompt: Union[str, Message, MessageSegment]`: 消息内容 + + + * `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api + + + +### _async classmethod_ `reject(prompt=None, **kwargs)` + + +* **说明** + + 发送一条消息给当前交互用户并暂停事件响应器，在接收用户新的一条消息后重新运行当前处理函数 + + + +* **参数** + + + * `prompt: Union[str, Message, MessageSegment]`: 消息内容 + + + * `**kwargs`: 其他传递给 `bot.send` 的参数，请参考对应 adapter 的 bot 对象 api + + + +## _class_ `MatcherGroup` + +基类：`object` + +事件响应器组合，统一管理。用法同 `Matcher` + + +### `__init__(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)` + + +* **说明** + + 创建一个事件响应器组合，参数为默认值，与 `Matcher.new` 一致 + + + +### `matchers` + + +* **类型** + + `List[Type[Matcher]]` + + + +* **说明** + + 组内事件响应器列表 + + + +### `new(type_='', rule=None, permission=None, handlers=None, temp=False, priority=1, block=False, *, module=None, default_state=None, expire_time=None)` + + +* **说明** + + 在组中创建一个新的事件响应器，参数留空则使用组合默认值 + + +:::danger 警告 +如果使用 handlers 参数覆盖组合默认值则该事件响应器不会随组合一起添加新的事件处理函数 +::: diff --git a/archive/2.0.0a5/api/message.md b/archive/2.0.0a5/api/message.md new file mode 100644 index 00000000..c9d7c158 --- /dev/null +++ b/archive/2.0.0a5/api/message.md @@ -0,0 +1,143 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.message 模块 + +## 事件处理 + +NoneBot 内部处理并按优先级分发事件给所有事件响应器，提供了多个插槽以进行事件的预处理等。 + + +## `event_preprocessor(func)` + + +* **说明** + + 事件预处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之前执行。 + + + +* **参数** + + 事件预处理函数接收三个参数。 + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + * `state: dict`: 当前 State + + + +## `event_postprocessor(func)` + + +* **说明** + + 事件后处理。装饰一个函数，使它在每次接收到事件并分发给各响应器之后执行。 + + + +* **参数** + + 事件后处理函数接收三个参数。 + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + * `state: dict`: 当前事件运行前 State + + + +## `run_preprocessor(func)` + + +* **说明** + + 运行预处理。装饰一个函数，使它在每次事件响应器运行前执行。 + + + +* **参数** + + 运行预处理函数接收四个参数。 + + + * `matcher: Matcher`: 当前要运行的事件响应器 + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + * `state: dict`: 当前 State + + + +## `run_postprocessor(func)` + + +* **说明** + + 运行后处理。装饰一个函数，使它在每次事件响应器运行后执行。 + + + +* **参数** + + 运行后处理函数接收五个参数。 + + + * `matcher: Matcher`: 运行完毕的事件响应器 + + + * `exception: Optional[Exception]`: 事件响应器运行错误（如果存在） + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + * `state: dict`: 当前 State + + + +## _async_ `handle_event(bot, event)` + + +* **说明** + + 处理一个事件。调用该函数以实现分发事件。 + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + +* **示例** + + +```python +import asyncio +asyncio.create_task(handle_event(bot, event)) +``` diff --git a/archive/2.0.0a5/api/nonebot.md b/archive/2.0.0a5/api/nonebot.md new file mode 100644 index 00000000..cdb72bdb --- /dev/null +++ b/archive/2.0.0a5/api/nonebot.md @@ -0,0 +1,254 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot 模块 + +## 快捷导入 + +为方便使用，`nonebot` 模块从子模块导入了部分内容 + + +* `on_message` => `nonebot.plugin.on_message` + + +* `on_notice` => `nonebot.plugin.on_notice` + + +* `on_request` => `nonebot.plugin.on_request` + + +* `on_metaevent` => `nonebot.plugin.on_metaevent` + + +* `on_startswith` => `nonebot.plugin.on_startswith` + + +* `on_endswith` => `nonebot.plugin.on_endswith` + + +* `on_keyword` => `nonebot.plugin.on_keyword` + + +* `on_command` => `nonebot.plugin.on_command` + + +* `on_regex` => `nonebot.plugin.on_regex` + + +* `CommandGroup` => `nonebot.plugin.CommandGroup` + + +* `load_plugin` => `nonebot.plugin.load_plugin` + + +* `load_plugins` => `nonebot.plugin.load_plugins` + + +* `load_builtin_plugins` => `nonebot.plugin.load_builtin_plugins` + + +* `get_loaded_plugins` => `nonebot.plugin.get_loaded_plugins` + + +## `get_driver()` + + +* **说明** + + 获取全局 Driver 对象。可用于在计划任务的回调中获取当前 Driver 对象。 + + + +* **返回** + + + * `Driver`: 全局 Driver 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +driver = nonebot.get_driver() +``` + + +## `get_app()` + + +* **说明** + + 获取全局 Driver 对应 Server App 对象。 + + + +* **返回** + + + * `Any`: Server App 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +app = nonebot.get_app() +``` + + +## `get_asgi()` + + +* **说明** + + 获取全局 Driver 对应 Asgi 对象。 + + + +* **返回** + + + * `Any`: Asgi 对象 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +asgi = nonebot.get_asgi() +``` + + +## `get_bots()` + + +* **说明** + + 获取所有通过 ws 连接 NoneBot 的 Bot 对象。 + + + +* **返回** + + + * `Dict[str, Bot]`: 一个以字符串 ID 为键，Bot 对象为值的字典 + + + +* **异常** + + + * `ValueError`: 全局 Driver 对象尚未初始化 (nonebot.init 尚未调用) + + + +* **用法** + + +```python +bots = nonebot.get_bots() +``` + + +## `init(*, _env_file=None, **kwargs)` + + +* **说明** + + 初始化 NoneBot 以及 全局 Driver 对象。 + + NoneBot 将会从 .env 文件中读取环境信息，并使用相应的 env 文件配置。 + + 你也可以传入自定义的 _env_file 来指定 NoneBot 从该文件读取配置。 + + + +* **参数** + + + * `_env_file: Optional[str]`: 配置文件名，默认从 .env.{env_name} 中读取配置 + + + * `**kwargs`: 任意变量，将会存储到 Config 对象里 + + + +* **返回** + + + * `None` + + + +* **用法** + + +```python +nonebot.init(database=Database(...)) +``` + + +## `run(host=None, port=None, *args, **kwargs)` + + +* **说明** + + 启动 NoneBot，即运行全局 Driver 对象。 + + + +* **参数** + + + * `host: Optional[str]`: 主机名／IP，若不传入则使用配置文件中指定的值 + + + * `port: Optional[int]`: 端口，若不传入则使用配置文件中指定的值 + + + * `*args`: 传入 Driver.run 的位置参数 + + + * `**kwargs`: 传入 Driver.run 的命名参数 + + + +* **返回** + + + * `None` + + + +* **用法** + + +```python +nonebot.run(host="127.0.0.1", port=8080) +``` diff --git a/archive/2.0.0a5/api/permission.md b/archive/2.0.0a5/api/permission.md new file mode 100644 index 00000000..26d3cd34 --- /dev/null +++ b/archive/2.0.0a5/api/permission.md @@ -0,0 +1,121 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.permission 模块 + +## 权限 + +每个 `Matcher` 拥有一个 `Permission` ，其中是 **异步** `PermissionChecker` 的集合，只要有一个 `PermissionChecker` 检查结果为 `True` 时就会继续运行。 + +:::tip 提示 +`PermissionChecker` 既可以是 async function 也可以是 sync function +::: + + +## `MESSAGE` + + +* **说明**: 匹配任意 `message` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 message type 的 Matcher。 + + +## `NOTICE` + + +* **说明**: 匹配任意 `notice` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 notice type 的 Matcher。 + + +## `REQUEST` + + +* **说明**: 匹配任意 `request` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 request type 的 Matcher。 + + +## `METAEVENT` + + +* **说明**: 匹配任意 `meta_event` 类型事件，仅在需要同时捕获不同类型事件时使用。优先使用 meta_event type 的 Matcher。 + + +## `USER(*user, perm=)` + + +* **说明** + + 在白名单内且满足 perm + + + +* **参数** + + + * `*user: int`: 白名单 + + + * `perm: Permission`: 需要同时满足的权限 + + + +## `PRIVATE` + + +* **说明**: 匹配任意私聊消息类型事件 + + +## `PRIVATE_FRIEND` + + +* **说明**: 匹配任意好友私聊消息类型事件 + + +## `PRIVATE_GROUP` + + +* **说明**: 匹配任意群临时私聊消息类型事件 + + +## `PRIVATE_OTHER` + + +* **说明**: 匹配任意其他私聊消息类型事件 + + +## `GROUP` + + +* **说明**: 匹配任意群聊消息类型事件 + + +## `GROUP_MEMBER` + + +* **说明**: 匹配任意群员群聊消息类型事件 + +:::warning 警告 +该权限通过 event.sender 进行判断且不包含管理员以及群主！ +::: + + +## `GROUP_ADMIN` + + +* **说明**: 匹配任意群管理员群聊消息类型事件 + + +## `GROUP_OWNER` + + +* **说明**: 匹配任意群主群聊消息类型事件 + + +## `SUPERUSER` + + +* **说明**: 匹配任意超级用户消息类型事件 + + +## `EVERYBODY` + + +* **说明**: 匹配任意消息类型事件 diff --git a/archive/2.0.0a5/api/plugin.md b/archive/2.0.0a5/api/plugin.md new file mode 100644 index 00000000..42cdf84f --- /dev/null +++ b/archive/2.0.0a5/api/plugin.md @@ -0,0 +1,629 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.plugin 模块 + +## 插件 + +为 NoneBot 插件开发提供便携的定义函数。 + + +## `plugins` + + +* **类型** + + `Dict[str, Plugin]` + + + +* **说明** + + 已加载的插件 + + + +## _class_ `Plugin` + +基类：`object` + +存储插件信息 + + +### `name` + + +* **类型**: `str` + + +* **说明**: 插件名称，使用 文件/文件夹 名称作为插件名 + + +### `module` + + +* **类型**: `ModuleType` + + +* **说明**: 插件模块对象 + + +### `matcher` + + +* **类型**: `Set[Type[Matcher]]` + + +* **说明**: 插件内定义的 `Matcher` + + +## `on(type='', rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=False, state=None)` + + +* **说明** + + 注册一个基础事件响应器，可自定义类型。 + + + +* **参数** + + + * `type: str`: 事件响应器类型 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_metaevent(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None)` + + +* **说明** + + 注册一个元事件响应器。 + + + +* **参数** + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_message(rule=None, permission=None, *, handlers=None, temp=False, priority=1, block=True, state=None)` + + +* **说明** + + 注册一个消息事件响应器。 + + + +* **参数** + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_notice(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None)` + + +* **说明** + + 注册一个通知事件响应器。 + + + +* **参数** + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_request(rule=None, *, handlers=None, temp=False, priority=1, block=False, state=None)` + + +* **说明** + + 注册一个请求事件响应器。 + + + +* **参数** + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_startswith(msg, rule=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容开头时响应。 + + + +* **参数** + + + * `msg: str`: 指定消息开头内容 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_endswith(msg, rule=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器，并且当消息的\*\*文本部分\*\*以指定内容结尾时响应。 + + + +* **参数** + + + * `msg: str`: 指定消息结尾内容 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_keyword(keywords, rule=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器，并且当消息纯文本部分包含关键词时响应。 + + + +* **参数** + + + * `keywords: Set[str]`: 关键词列表 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_command(cmd, rule=None, aliases=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器，并且当消息以指定命令开头时响应。 + + 命令匹配规则参考: [命令形式匹配](rule.html#command-command) + + + +* **参数** + + + * `cmd: Union[str, Tuple[str, ...]]`: 指定命令内容 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `aliases: Optional[Set[Union[str, Tuple[str, ...]]]]`: 命令别名 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## `on_regex(pattern, flags=0, rule=None, **kwargs)` + + +* **说明** + + 注册一个消息事件响应器，并且当消息匹配正则表达式时响应。 + + 命令匹配规则参考: [正则匹配](rule.html#regex-regex-flags-0) + + + +* **参数** + + + * `pattern: str`: 正则表达式 + + + * `flags: Union[int, re.RegexFlag]`: 正则匹配标志 + + + * `rule: Optional[Union[Rule, RuleChecker]]`: 事件响应规则 + + + * `permission: Optional[Permission]`: 事件响应权限 + + + * `handlers: Optional[List[Handler]]`: 事件处理函数列表 + + + * `temp: bool`: 是否为临时事件响应器（仅执行一次） + + + * `priority: int`: 事件响应器优先级 + + + * `block: bool`: 是否阻止事件向更低优先级传递 + + + * `state: Optional[dict]`: 默认的 state + + + +* **返回** + + + * `Type[Matcher]` + + + +## _class_ `CommandGroup` + +基类：`object` + +命令组，用于声明一组有相同名称前缀的命令。 + + +### `__init__(cmd, **kwargs)` + + +* **参数** + + + * `cmd: Union[str, Tuple[str, ...]]`: 命令前缀 + + + * `**kwargs`: 其他传递给 `on_command` 的参数默认值，参考 [on_command](#on-command-cmd-rule-none-aliases-none-kwargs) + + + +### `basecmd` + + +* **类型**: `Tuple[str, ...]` + + +* **说明**: 命令前缀 + + +### `base_kwargs` + + +* **类型**: `Dict[str, Any]` + + +* **说明**: 其他传递给 `on_command` 的参数默认值 + + +### `command(cmd, **kwargs)` + + +* **说明** + + 注册一个新的命令。 + + + +* **参数** + + + * `cmd: Union[str, Tuple[str, ...]]`: 命令前缀 + + + * `**kwargs`: 其他传递给 `on_command` 的参数，将会覆盖命令组默认值 + + + +* **返回** + + + * `Type[Matcher]` + + + +## `load_plugin(module_path)` + + +* **说明** + + 使用 `importlib` 加载单个插件，可以是本地插件或是通过 `pip` 安装的插件。 + + + +* **参数** + + + * `module_path: str`: 插件名称 `path.to.your.plugin` + + + +* **返回** + + + * `Optional[Plugin]` + + + +## `load_plugins(*plugin_dir)` + + +* **说明** + + 导入目录下多个插件，以 `_` 开头的插件不会被导入！ + + + +* **参数** + + + * `*plugin_dir: str`: 插件路径 + + + +* **返回** + + + * `Set[Plugin]` + + + +## `load_builtin_plugins()` + + +* **说明** + + 导入 NoneBot 内置插件 + + + +* **返回** + + + * `Plugin` + + + +## `get_loaded_plugins()` + + +* **说明** + + 获取当前已导入的插件。 + + + +* **返回** + + + * `Set[Plugin]` diff --git a/archive/2.0.0a5/api/rule.md b/archive/2.0.0a5/api/rule.md new file mode 100644 index 00000000..dade2a5b --- /dev/null +++ b/archive/2.0.0a5/api/rule.md @@ -0,0 +1,210 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.rule 模块 + +## 规则 + +每个事件响应器 `Matcher` 拥有一个匹配规则 `Rule` ，其中是 **异步** `RuleChecker` 的集合，只有当所有 `RuleChecker` 检查结果为 `True` 时继续运行。 + +:::tip 提示 +`RuleChecker` 既可以是 async function 也可以是 sync function，但在最终会被 `nonebot.utils.run_sync` 转换为 async function +::: + + +## _class_ `Rule` + +基类：`object` + + +* **说明** + + `Matcher` 规则类，当事件传递时，在 `Matcher` 运行前进行检查。 + + + +* **示例** + + +```python +Rule(async_function) & sync_function +# 等价于 +from nonebot.utils import run_sync +Rule(async_function, run_sync(sync_function)) +``` + + +### `__init__(*checkers)` + + +* **参数** + + + * `*checkers: Callable[[Bot, Event, dict], Awaitable[bool]]`: **异步** RuleChecker + + + +### `checkers` + + +* **说明** + + 存储 `RuleChecker` + + + +* **类型** + + + * `Set[Callable[[Bot, Event, dict], Awaitable[bool]]]` + + + +### _async_ `__call__(bot, event, state)` + + +* **说明** + + 检查是否符合所有规则 + + + +* **参数** + + + * `bot: Bot`: Bot 对象 + + + * `event: Event`: Event 对象 + + + * `state: dict`: 当前 State + + + +* **返回** + + + * `bool` + + + +## `startswith(msg)` + + +* **说明** + + 匹配消息开头 + + + +* **参数** + + + * `msg: str`: 消息开头字符串 + + + +## `endswith(msg)` + + +* **说明** + + 匹配消息结尾 + + + +* **参数** + + + * `msg: str`: 消息结尾字符串 + + + +## `keyword(*keywords)` + + +* **说明** + + 匹配消息关键词 + + + +* **参数** + + + * `*keywords: str`: 关键词 + + + +## `command(*cmds)` + + +* **说明** + + 命令形式匹配，根据配置里提供的 `command_start`, `command_sep` 判断消息是否为命令。 + + 可以通过 `state["_prefix"]["command"]` 获取匹配成功的命令（例：`("test",)`），通过 `state["_prefix"]["raw_command"]` 获取匹配成功的原始命令文本（例：`"/test"`）。 + + + +* **参数** + + + * `*cmds: Union[str, Tuple[str, ...]]`: 命令内容 + + + +* **示例** + + 使用默认 `command_start`, `command_sep` 配置 + + 命令 `("test",)` 可以匹配：`/test` 开头的消息 + 命令 `("test", "sub")` 可以匹配”`/test.sub` 开头的消息 + + +:::tip 提示 +命令内容与后续消息间无需空格！ +::: + + +## `regex(regex, flags=0)` + + +* **说明** + + 根据正则表达式进行匹配。 + + 可以通过 `state["_matched"]` 获取正则表达式匹配成功的文本。 + + + +* **参数** + + + * `regex: str`: 正则表达式 + + + * `flags: Union[int, re.RegexFlag]`: 正则标志 + + +:::tip 提示 +正则表达式匹配使用 search 而非 match，如需从头匹配请使用 `r"^xxx"` 来确保匹配开头 +::: + + +## `to_me()` + + +* **说明** + + 通过 `event.to_me` 判断消息是否是发送给机器人 + + + +* **参数** + + + * 无 diff --git a/archive/2.0.0a5/api/sched.md b/archive/2.0.0a5/api/sched.md new file mode 100644 index 00000000..450fd7d0 --- /dev/null +++ b/archive/2.0.0a5/api/sched.md @@ -0,0 +1,41 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.sched 模块 + +## 计划任务 + +计划任务使用第三方库 [APScheduler](https://github.com/agronholm/apscheduler) ，使用文档请参考 [APScheduler使用文档](https://apscheduler.readthedocs.io/en/latest/) 。 + + +## `scheduler` + + +* **类型** + + `Optional[apscheduler.schedulers.asyncio.AsyncIOScheduler]` + + + +* **说明** + + 当可选依赖 `APScheduler` 未安装时，`scheduler` 为 None + + 使用 `pip install nonebot[scheduler]` 安装可选依赖 + + + +* **常用示例** + + +```python +from nonebot import scheduler + +@scheduler.scheduled_job("cron", hour="*/2", id="xxx", args=[1], kwargs={arg2: 2}) +async def run_every_2_hour(arg1, arg2): + pass + +scheduler.add_job(run_every_day_from_program_start, "interval", days=1, id="xxx") +``` diff --git a/archive/2.0.0a5/api/typing.md b/archive/2.0.0a5/api/typing.md new file mode 100644 index 00000000..8f8a2223 --- /dev/null +++ b/archive/2.0.0a5/api/typing.md @@ -0,0 +1,300 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.typing 模块 + +## 类型 + +下面的文档中，「类型」部分使用 Python 的 Type Hint 语法，见 [PEP 484](https://www.python.org/dev/peps/pep-0484/)、[PEP 526](https://www.python.org/dev/peps/pep-0526/) 和 [typing](https://docs.python.org/3/library/typing.html)。 + +除了 Python 内置的类型，下面还出现了如下 NoneBot 自定类型，实际上它们是 Python 内置类型的别名。 + +以下类型均可从 nonebot.typing 模块导入。 + + +## `Driver` + + +* **类型** + + `BaseDriver` + + + +* **说明** + + 所有 Driver 的基类。 + + + + +## `WebSocket` + + +* **类型** + + `BaseWebSocket` + + + +* **说明** + + 所有 WebSocket 的基类。 + + + + +## `Bot` + + +* **类型** + + `BaseBot` + + + +* **说明** + + 所有 Bot 的基类。 + + + + +## `Event` + + +* **类型** + + `BaseEvent` + + + +* **说明** + + 所有 Event 的基类。 + + + + +## `Message` + + +* **类型** + + `BaseMessage` + + + +* **说明** + + 所有 Message 的基类。 + + + + +## `MessageSegment` + + +* **类型** + + `BaseMessageSegment` + + + +* **说明** + + 所有 MessageSegment 的基类。 + + + + +## `EventPreProcessor` + + +* **类型** + + `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + 事件预处理函数 EventPreProcessor 类型 + + + + +## `EventPostProcessor` + + +* **类型** + + `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + 事件预处理函数 EventPostProcessor 类型 + + + + +## `RunPreProcessor` + + +* **类型** + + `Callable[[Matcher, Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + 事件响应器运行前预处理函数 RunPreProcessor 类型 + + + + +## `RunPostProcessor` + + +* **类型** + + `Callable[[Matcher, Optional[Exception], Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + 事件响应器运行前预处理函数 RunPostProcessor 类型，第二个参数为运行时产生的错误（如果存在） + + + + +## `Matcher` + + +* **类型** + + `Matcher` + + + +* **说明** + + Matcher 即响应事件的处理类。通过 Rule 判断是否响应事件，运行 Handler。 + + + + +## `MatcherGroup` + + +* **类型** + + `MatcherGroup` + + + +* **说明** + + MatcherGroup 为 Matcher 的集合。可以共享 Handler。 + + + + +## `Rule` + + +* **类型** + + `Rule` + + + +* **说明** + + Rule 即判断是否响应事件的处理类。内部存储 RuleChecker ，返回全为 True 则响应事件。 + + + + +## `RuleChecker` + + +* **类型** + + `Callable[[Bot, Event, dict], Union[bool, Awaitable[bool]]]` + + + +* **说明** + + RuleChecker 即判断是否响应事件的处理函数。 + + + + +## `Permission` + + +* **类型** + + `Permission` + + + +* **说明** + + Permission 即判断是否响应消息的处理类。内部存储 PermissionChecker ，返回只要有一个 True 则响应消息。 + + + + +## `PermissionChecker` + + +* **类型** + + `Callable[[Bot, Event], Union[bool, Awaitable[bool]]]` + + + +* **说明** + + RuleChecker 即判断是否响应消息的处理函数。 + + + + +## `Handler` + + +* **类型** + + `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + Handler 即事件的处理函数。 + + + + +## `ArgsParser` + + +* **类型** + + `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` + + + +* **说明** + + ArgsParser 即消息参数解析函数，在 Matcher.got 获取参数时被运行。 diff --git a/archive/2.0.0a5/api/utils.md b/archive/2.0.0a5/api/utils.md new file mode 100644 index 00000000..ed98fab9 --- /dev/null +++ b/archive/2.0.0a5/api/utils.md @@ -0,0 +1,62 @@ +--- +contentSidebar: true +sidebarDepth: 0 +--- + +# NoneBot.utils 模块 + + +## `escape_tag(s)` + + +* **说明** + + 用于记录带颜色日志时转义 `` 类型特殊标签 + + + +* **参数** + + + * `s: str`: 需要转义的字符串 + + + +* **返回** + + + * `str` + + + +## `run_sync(func)` + + +* **说明** + + 一个用于包装 sync function 为 async function 的装饰器 + + + +* **参数** + + + * `func: Callable[..., Any]`: 被装饰的同步函数 + + + +* **返回** + + + * `Callable[..., Awaitable[Any]]` + + + +## _class_ `DataclassEncoder` + +基类：`json.encoder.JSONEncoder` + + +* **说明** + + 在JSON序列化 `Message` (List[Dataclass]) 时使用的 `JSONEncoder` diff --git a/archive/2.0.0a5/guide/README.md b/archive/2.0.0a5/guide/README.md new file mode 100644 index 00000000..43b7f325 --- /dev/null +++ b/archive/2.0.0a5/guide/README.md @@ -0,0 +1,36 @@ +# 概览 + +:::tip 提示 +如果在阅读本文档时遇到难以理解的词汇，请随时查阅 [术语表](../glossary.md) 或使用 [Google 搜索](https://www.google.com/)。 +::: + +:::tip 提示 +初次使用时可能会觉得这里的概览过于枯燥，可以先简单略读之后直接前往 [安装](./installation.md) 查看安装方法，并进行后续的基础使用教程。 +::: + +NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的消息进行解析和处理，并以插件化的形式，分发给消息所对应的命令处理器和自然语言处理器，来完成具体的功能。 + +除了起到解析消息的作用，NoneBot 还为插件提供了大量实用的预设操作和权限控制机制，尤其对于命令处理器，它更是提供了完善且易用的会话机制和内部调用机制，以分别适应命令的连续交互和插件内部功能复用等需求。 + +目前 NoneBot2 在 [FastAPI](https://fastapi.tiangolo.com/) 的基础上封装了与 [CQHTTP(OneBot) 协议](http://cqhttp.cc/)插件的网络交互。 + +得益于 Python 的 [asyncio](https://docs.python.org/3/library/asyncio.html) 机制，NoneBot 处理消息的吞吐量有了很大的保障，再配合 WebSocket 通信方式（也是最建议的通信方式），NoneBot 的性能可以达到 HTTP 通信方式的两倍以上，相较于传统同步 I/O 的 HTTP 通信，更是有质的飞跃。 + +需要注意的是，NoneBot 仅支持 Python 3.7+ 及 CQHTTP(OneBot) 插件 v11+。 + +## 它如何工作？ + + + +~~未填坑~~ + +## 特色 + +- 提供直观的测试前端 +- 提供使用简易的脚手架 +- 基于异步 I/O +- 同时支持 HTTP 和反向 WebSocket 通信方式 +- 支持多个机器人账号负载均衡 +- 提供直观的交互式会话接口 +- 提供可自定义的权限控制机制 +- 多种方式渲染要发送的消息内容，使对话足够自然 diff --git a/archive/2.0.0a5/guide/basic-configuration.md b/archive/2.0.0a5/guide/basic-configuration.md new file mode 100644 index 00000000..e4c4449f --- /dev/null +++ b/archive/2.0.0a5/guide/basic-configuration.md @@ -0,0 +1,68 @@ +# 基本配置 + +到目前为止我们还在使用 NoneBot 的默认行为，在开始编写自己的插件之前，我们先尝试在配置文件上动动手脚，让 NoneBot 表现出不同的行为。 + +在上一章节中，我们创建了默认的项目结构，其中 `.env`, `.env.*` 均为项目的配置文件，下面将介绍几种 NoneBot 配置方式。 + +:::danger 警告 +请勿将敏感信息写入配置文件并提交至开源仓库！ +::: + +## .env 文件 + +NoneBot 在启动时将会从系统环境变量或者 `.env` 文件中寻找变量 `ENVIRONMENT` (大小写不敏感)，默认值为 `prod`。 +这将引导 NoneBot 从系统环境变量或者 `.env.{ENVIRONMENT}` 文件中进一步加载具体配置。 + +现在，我们在 `.env` 文件中写入当前环境信息 + +```bash +# .env +ENVIRONMENT=dev +``` + +## .env.\* 文件 + +详细配置文件，使用 [pydantic](https://pydantic-docs.helpmanual.io/) 加载配置。在 NoneBot 初始化时可以指定忽略 `.env` 中的环境信息转而加载某个配置文件: `nonebot.init(_env_file=".env.dev")`。 + +:::warning 提示 +由于 `pydantic` 使用 JSON 加载配置项，请确保配置项值为 JSON 能够解析的数据。如果 JSON 解析失败将作为字符串处理。 +::: + +示例及说明： + +```bash +HOST=0.0.0.0 # 配置 NoneBot 监听的 IP/主机名 +PORT=8080 # 配置 NoneBot 监听的端口 +DEBUG=true # 开启 debug 模式 **请勿在生产环境开启** +SUPERUSERS=["123456789", "987654321"] # 配置 NoneBot 超级用户 +NICKNAME=["awesome", "bot"] # 配置机器人的昵称 +COMMAND_START=["/", ""] # 配置命令起始字符 +COMMAND_SEP=["."] # 配置命令分割字符 + +# Custom Configs +CUSTOM_CONFIG1="config in env file" +CUSTOM_CONFIG2= # 留空则从系统环境变量读取，如不存在则为空字符串 +``` + +详细的配置项参考 [Config Reference](../api/config.md) 。 + +## bot.py 文件 + +配置项也可以在 NoneBot 初始化时传入。此处可以传入任意合法 Python 变量。当然也可以在初始化完成后修改或新增。 + +示例： + +```python +# bot.py +import nonebot + +nonebot.init(custom_config3="config on init") + +config = nonebot.get_driver().config +config.custom_config3 = "changed after init" +config.custom_config4 = "new config after init" +``` + +## 优先级 + +`bot.py init` > `env file` > `system env` diff --git a/archive/2.0.0a5/guide/creating-a-handler.md b/archive/2.0.0a5/guide/creating-a-handler.md new file mode 100644 index 00000000..725aaacf --- /dev/null +++ b/archive/2.0.0a5/guide/creating-a-handler.md @@ -0,0 +1,159 @@ +# 事件处理 + +在上一章中，我们已经注册了事件响应器，现在我们可以正式编写事件处理逻辑了！ + +## [事件处理函数](../api/typing.md#handler) + +```python{1,2,8,9} +@weather.handle() +async def handle_first_receive(bot: Bot, event: Event, state: dict): + args = str(event.message).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海 + if args: + state["city"] = args # 如果用户发送了参数则直接赋值 + + +@weather.got("city", prompt="你想查询哪个城市的天气呢？") +async def handle_city(bot: Bot, event: Event, state: dict): + city = state["city"] + if city not in ["上海", "北京"]: + await weather.reject("你想查询的城市暂不支持，请重新输入！") + city_weather = await get_weather(city) + await weather.finish(city_weather) +``` + +在之前的样例中，我们定义了两个函数 `handle_first_receive`, `handle_city`，他们被事件响应器的装饰器装饰从而成为事件响应器的事件处理函数。 + +:::tip 提示 +在事件响应器中，事件处理函数是**顺序**执行的！ +::: + +### 添加一个事件处理函数 + +事件响应器提供了三种装饰事件处理函数的装饰器，分别是： + +1. [handle()](../api/matcher.md#classmethod-handle) +2. [receive()](../api/matcher.md#classmethod-receive) +3. [got(key, prompt, args_parser)](../api/matcher.md#classmethod-got-key-prompt-none-args-parser-none) + +#### handle() + +简单的为事件响应器添加一个事件处理函数，这个函数将会在上一个处理函数正常返回执行完毕后立即执行。 + +#### receive() + +指示 NoneBot 接收一条新的用户消息后继续执行该处理函数。此时函数将会接收到新的消息而非前一条消息，之前相关信息可以存储在 state 中。 + +特别的，当装饰的函数前没有其他事件处理函数，那么 `receive()` 不会接收一条新的消息而是直接使用第一条接收到的消息。 + +#### got(key, prompt, args_parser) + +指示 NoneBot 当 `state` 中不存在 `key` 时向用户发送 `prompt` 等待用户回复并赋值给 `state[key]`。 + +`prompt` 可以为 `str`, `Message`, `MessageSegment`，若为空则不会向用户发送，若不为空则会在 format 之后发送，即 `prompt.format(**state)`，注意对 `{}` 进行转义。示例： + +```python +@matcher.receive() +async def handle(bot: Bot, event: Event, state: dict): + state["key"] = "hello" + + +@matcher.got("key2", prompt="{key}!") +async def handle2(bot: Bot, event: Event, state: dict): + pass +``` + +`args_parser` 为参数处理函数，在这里传入一个新的函数以覆盖默认的参数处理。详情参照 [args_parser](#参数处理函数-args-parser) + +特别的，这些装饰器都可以套娃使用： + +```python +@matcher.got("key1") +@matcher.got("key2") +async def handle(bot: Bot, event: Event, state: dict): + pass +``` + +### 事件处理函数参数 + +事件处理函数类型为 `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` 。 + +参数分别为： + +1. [nonebot.typing.Bot](../api/typing.md#bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。 +2. [nonebot.typing.Event](../api/typing.md#event): 即上报事件对象，可以获取到上报的所有信息。 +3. `state`: 状态字典，可以存储任意的信息，其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息，如： + +- `state["_current_key"]`: 存储当前 `got` 获取的参数名 +- `state["_prefix"]`, `state["_suffix"]`: 存储当前 TRIE 匹配的前缀/后缀，可以通过该值获取用户命令的原始命令 + +### 参数处理函数 args_parser + +在使用 `got` 获取用户输入参数时，需要对用户的消息进行处理以转换为我们所需要的信息。在默认情况下，NoneBot 会把用户的消息字符串原封不动的赋值给 `state[key]` 。可以通过以下两种方式修改默认处理逻辑： + +- `@matcher.args_parser` 装饰器：直接装饰一个函数作为参数处理器 +- `got(key, prompt, args_parser)`：直接把函数作为参数传入 + +参数处理函数类型为：`Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`，即： + +```python +async def parser(bot: Bot, event: Event, state: dict): + state[state["_current_key"]] = str(event.message) +``` + +特别的，`state["_current_key"]` 中存储了当前获取的参数名 + +### 逻辑控制 + +NoneBot 也为事件处理函数提供了一些便捷的逻辑控制函数： + +#### `matcher.send` + +这个函数用于发送一条消息给当前交互的用户。~~其实这并不是一个逻辑控制函数，只是不知道放在哪里……~~ + +#### `matcher.pause` + +这个函数用于结束当前事件处理函数，强制接收一条新的消息再运行**下一个消息处理函数**。 + +#### `matcher.reject` + +这个函数用于结束当前事件处理函数，强制接收一条新的消息再**再次运行当前消息处理函数**。常用于用户输入信息不符合预期。 + +#### `matcher.finish` + +这个函数用于直接结束当前事件处理。 + +以上三个函数都拥有一个参数 `message` / `prompt`，用于向用户发送一条消息。以及 `**kwargs` 直接传递给 `bot.send` 的额外参数。 + +## 常用事件处理结构 + +```python +matcher = on_command("test") + +# 修改默认参数处理 +@matcher.args_parser +async def parse(bot: Bot, event: Event, state: dict): + print(state["_current_key"], ":", str(event.message)) + state[state["_current_key"]] = str(event.message) + +@matcher.handle() +async def first_receive(bot: Bot, event: Event, state: dict): + # 获取用户原始命令，如：/test + print(state["_prefix"]["raw_command"]) + # 处理用户输入参数，如：/test arg1 arg2 + raw_args = str(event.message).strip() + if raw_args: + arg_list = raw_args.split() + # 将参数存入state以阻止后续再向用户询问参数 + state["arg1"] = arg_list[0] + + +@matcher.got("arg1", prompt="参数？") +async def arg_handle(bot: Bot, event: Event, state: dict): + # 在这里对参数进行验证 + if state["arg1"] not in ["allow", "list"]: + await matcher.reject("参数不正确！请重新输入") + # 发送一些信息 + await bot.send("message") + await matcher.send("message") + await matcher.finish("message") +``` diff --git a/archive/2.0.0a5/guide/creating-a-matcher.md b/archive/2.0.0a5/guide/creating-a-matcher.md new file mode 100644 index 00000000..b603449a --- /dev/null +++ b/archive/2.0.0a5/guide/creating-a-matcher.md @@ -0,0 +1,144 @@ +# 注册事件响应器 + +好了，现在插件已经创建完毕，我们可以开始编写实际代码了，下面将以一个简易单文件天气查询插件为例。 + +在插件目录下 `weather.py` 中添加如下代码： + +```python +from nonebot import on_command +from nonebot.rule import to_me +from nonebot.adapters.cqhttp import Bot, Event + +weather = on_command("天气", rule=to_me(), priority=5) + + +@weather.handle() +async def handle_first_receive(bot: Bot, event: Event, state: dict): + args = str(event.message).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海 + if args: + state["city"] = args # 如果用户发送了参数则直接赋值 + + +@weather.got("city", prompt="你想查询哪个城市的天气呢？") +async def handle_city(bot: Bot, event: Event, state: dict): + city = state["city"] + if city not in ["上海", "北京"]: + await weather.reject("你想查询的城市暂不支持，请重新输入！") + city_weather = await get_weather(city) + await weather.finish(city_weather) + + +async def get_weather(city: str): + return f"{city}的天气是..." +``` + +为了简单起见，我们在这里的例子中没有接入真实的天气数据，但要接入也非常简单，你可以使用中国天气网、和风天气等网站提供的 API。 + +接下来我们来说明这段代码是如何工作的。 + +:::tip 提示 +从这里开始，你需要对 Python 的 asyncio 编程有所了解，因为 NoneBot 是完全基于 asyncio 的，具体可以参考 [廖雪峰的 Python 教程](https://www.liaoxuefeng.com/wiki/1016959663602400/1017959540289152) +::: + +## [事件响应器](../api/matcher.md) + +```python{4} +from nonebot import on_command +from nonebot.rule import to_me +from nonebot.permission import Permission + +weather = on_command("天气", rule=to_me(), permission=Permission(), priority=5) +``` + +在上方代码中，我们注册了一个事件响应器 `Matcher`，它由几个部分组成： + +1. `on_command` 注册一个消息类型的命令处理器 +2. `"天气"` 指定 command 参数 - 命令名 +3. `rule` 补充事件响应器的匹配规则 +4. `priority` 事件响应器优先级 +5. `block` 是否阻止事件传递 + +其他详细配置可以参考 API 文档，下面我们详细说明各个部分： + +### 事件响应器类型 type + +事件响应器类型其实就是对应事件的类型 `Event.type` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些其他内置的事件响应器。 + +以下所有类型的事件响应器都是由 `on(type, rule)` 的形式进行了简化封装。 + +- `on("事件类型")`: 基础事件响应器，第一个参数为事件类型，空字符串表示不限 +- `on_metaevent()` ~ `on("meta_event")`: 元事件响应器 +- `on_message()` ~ `on("message")`: 消息事件响应器 +- `on_request()` ~ `on("request")`: 请求事件响应器 +- `on_notice()` ~ `on("notice")`: 通知事件响应器 +- `on_startswith(str)` ~ `on("message", startswith(str))`: 消息开头匹配响应器，参考 [startswith](../api/rule.md#startswith-msg) +- `on_endswith(str)` ~ `on("message", endswith(str))`: 消息结尾匹配响应器，参考 [endswith](../api/rule.md#endswith-msg) +- `on_keyword(set)` ~ `on("message", keyword(str))`: 消息关键词匹配响应器，参考 [keyword](../api/rule.md#keyword-keywords) +- `on_command(str|tuple)` ~ `on("message", command(str|tuple))`: 命令响应器，参考 [command](../api/rule.md#command-cmds) +- `on_regex(pattern_str)` ~ `on("message", regex(pattern_str))`: 正则匹配处理器，参考 [regex](../api/rule.md#regex-regex-flags-0) + +### 匹配规则 rule + +事件响应器的匹配规则即 `Rule`，详细内容在下方介绍。[直达](#自定义-rule) + +### 优先级 priority + +事件响应器的优先级代表事件响应器的执行顺序，同一优先级的事件响应器会 **同时执行！**，优先级数字**越小**越先响应！优先级请从 `1` 开始排序！ + +:::tip 提示 +使用 `nonebot-test` 可以看到当前所有事件响应器的执行流程，有助理解事件响应流程！ + +```bash +pip install nonebot2[test] +``` + +::: + +### 阻断 block + +当有任意事件响应器发出了阻止事件传递信号时，该事件将不再会传递给下一优先级，直接结束处理。 + +NoneBot 内置的事件响应器中，所有 `message` 类的事件响应器默认会阻断事件传递，其他则不会。 + +## 自定义 rule + +rule 的出现使得 nonebot 对事件的响应可以非常自由，nonebot 内置了一些规则： + +- [startswith(msg)](../api/rule.md#startswith-msg) +- [endswith(msg)](../api/rule.md#endswith-msg) +- [keyword(\*keywords)](../api/rule.md#keyword-keywords) +- [command(\*cmds)](../api/rule.md#command-cmds) +- [regex(regex, flag)](../api/rule.md#regex-regex-flags-0) + +以上规则都是返回类型为 `Rule` 的函数，`Rule` 由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `Rule`, `RuleChecker` 的形式如下： + +```python +from nonebot.rule import Rule + +async def async_checker(bot: Bot, event: Event, state: dict) -> bool: + return True + +def sync_checker(bot: Bot, event: Event, state: dict) -> bool: + return True + +def check(arg1, args2): + + async def _checker(bot: Bot, event: Event, state: dict) -> bool: + return bool(arg1 + arg2) + + return Rule(_check) +``` + +`Rule` 和 `RuleChecker` 之间可以使用 `与 &` 互相组合： + +```python +from nonebot.rule import Rule + +Rule(async_checker1) & sync_checker & async_checker2 +``` + +**_请勿将事件处理的逻辑写入 `rule` 中，这会使得事件处理返回奇怪的响应。_** + +:::danger 警告 +`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function +::: diff --git a/archive/2.0.0a5/guide/creating-a-plugin.md b/archive/2.0.0a5/guide/creating-a-plugin.md new file mode 100644 index 00000000..fe52a25d --- /dev/null +++ b/archive/2.0.0a5/guide/creating-a-plugin.md @@ -0,0 +1,113 @@ +# 创建插件 + +如果之前使用 `nb-cli` 生成了项目结构，那我们已经有了一个空的插件目录 `Awesome-Bot/awesome_bot/plugins`，并且它已在 `bot.py` 中被加载，我们现在可以开始创建插件了！ + +插件通常有两种形式，下面分别介绍 + +## 单文件形式 + +在插件目录下创建名为 `foo.py` 的 Python 文件，暂时留空，此时目录结构如下： + + +:::vue +AweSome-Bot +├── awesome_bot +│ └── plugins +│ └── `foo.py` +├── .env +├── .env.dev +├── .env.prod +├── .gitignore +├── bot.py +├── docker-compose.yml +├── Dockerfile +├── pyproject.toml +└── README.md +::: + + +这个时候它已经可以被称为一个插件了，尽管它还什么都没做。 + +## 包形式(推荐) + +在插件目录下创建文件夹 `foo`，并在该文件夹下创建文件 `__init__.py`，此时目录结构如下： + + +:::vue +AweSome-Bot +├── awesome_bot +│ └── plugins +│ └── `foo` +│ └── `__init__.py` +├── .env +├── .env.dev +├── .env.prod +├── .gitignore +├── bot.py +├── docker-compose.yml +├── Dockerfile +├── pyproject.toml +└── README.md +::: + + +这个时候 `foo` 就是一个合法的 Python 包了，同时也是合法的 NoneBot 插件，插件内容可以在 `__init__.py` 中编写。 + +### 推荐结构(仅供参考) + + +:::vue +foo +├── `__init__.py` +├── `config.py` +├── `data_source.py` +└── `model.py` +::: + + +#### \_\_init\_\_.py + +在该文件中编写各类事件响应及处理逻辑。 + +#### config.py + +在该文件中使用 `pydantic` 定义插件所需要的配置项以及类型。 + +示例： + +```python +from pydantic import BaseSetting + + +class Config(BaseSetting): + + # plugin custom config + plugin_setting: str = "default" + + class Config: + extra = "ignore" +``` + +并在 `__init__.py` 文件中添加以下行 + +```python +import nonebot +from .config import Config + +global_config = nonebot.get_driver().config +plugin_config = Config(**global_config.dict()) +``` + +此时就可以通过 `plugin_config.plugin_setting` 获取到插件所需要的配置项了。 + +#### data_source.py + +在该文件中编写数据获取函数。 + +:::warning 警告 +数据获取应尽量使用**异步**处理！例如使用 [httpx](https://www.python-httpx.org/) 而非 [requests](https://requests.readthedocs.io/en/master/) +::: + +#### model.py + +在该文件中编写数据库模型。 diff --git a/archive/2.0.0a5/guide/creating-a-project.md b/archive/2.0.0a5/guide/creating-a-project.md new file mode 100644 index 00000000..74cdb24a --- /dev/null +++ b/archive/2.0.0a5/guide/creating-a-project.md @@ -0,0 +1,55 @@ +# 创建一个完整的项目 + +上一章中我们已经运行了一个最小的 NoneBot 实例，在这一章，我们将从零开始一个完整的项目。 + +## 目录结构 + +首先，我们可以使用 `nb-cli` 或者自行创建项目目录： + +```bash +pip install nonebot2[cli] +# pip install nb-cli +nb create +``` + +这将创建默认的目录结构 + + +:::vue +AweSome-Bot +├── `awesome_bot` _(**或是 src**)_ +│ └── `plugins` +├── `.env` _(**可选的**)_ +├── `.env.dev` _(**可选的**)_ +├── `.env.prod` _(**可选的**)_ +├── .gitignore +├── `bot.py` +├── docker-compose.yml +├── Dockerfile +├── `pyproject.toml` +└── README.md +::: + + +- `awesome_bot/plugins` 或 `src/plugins`: 用于存放编写的 bot 插件 +- `.env`, `.env.dev`, `.env.prod`: 各环境配置文件 +- `bot.py`: bot 入口文件 +- `pyproject.toml`: 项目依赖管理文件，默认使用 [poetry](https://python-poetry.org/) + +## 启动 Bot + +如果你使用 `nb-cli` + +```bash +nb run [--file=bot.py] [--app=app] +``` + +或者使用 + +```bash +python bot.py +``` + +:::tip 提示 +如果在 bot 入口文件内定义了 asgi server， `nb-cli` 将会为你启动**冷重载模式** +::: diff --git a/archive/2.0.0a5/guide/end-or-start.md b/archive/2.0.0a5/guide/end-or-start.md new file mode 100644 index 00000000..f1b0baa9 --- /dev/null +++ b/archive/2.0.0a5/guide/end-or-start.md @@ -0,0 +1,7 @@ +# 结语 + +至此，相信你已经能够写出一个基础的插件了，更多的用法将会在 进阶 部分进行介绍，这里给出几个小提示： + +- 请千万注意事件处理器的优先级设定 +- 在匹配规则中请勿使用耗时极长的函数 +- 同一个用户可以**跨群**(**私聊**)继续他的事件处理（除非做出权限限制，将在后续介绍） diff --git a/archive/2.0.0a5/guide/getting-started.md b/archive/2.0.0a5/guide/getting-started.md new file mode 100644 index 00000000..9c358ead --- /dev/null +++ b/archive/2.0.0a5/guide/getting-started.md @@ -0,0 +1,146 @@ +# 开始使用 + +一切都安装成功后，你就已经做好了进行简单配置以运行一个最小的 NoneBot 实例的准备。 + +## 最小实例 + +使用你最熟悉的编辑器或 IDE，创建一个名为 `bot.py` 的文件，内容如下： + +```python{3,4,7} +import nonebot + +nonebot.init() +nonebot.load_builtin_plugins() + +if __name__ == "__main__": + nonebot.run() +``` + +这几行高亮代码将依次： + +1. 使用默认配置初始化 NoneBot 包 +2. 加载 NoneBot 内置的插件 +3. 在地址 `127.0.0.1:8080` 运行 NoneBot + +在命令行使用如下命令即可运行这个 NoneBot 实例： + +```bash +python bot.py +``` + +运行后会产生如下日志： + +```default +09-14 21:02:00 [INFO] nonebot | Succeeded to import "nonebot.plugins.base" +09-14 21:02:00 [INFO] nonebot | Running NoneBot... +09-14 21:02:00 [INFO] uvicorn | Started server process [1234] +09-14 21:02:00 [INFO] uvicorn | Waiting for application startup. +09-14 21:02:00 [INFO] nonebot | Scheduler Started +09-14 21:02:00 [INFO] uvicorn | Application startup complete. +09-14 21:02:00 [INFO] uvicorn | Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit) +``` + +## 配置 QQ 协议端 + +单纯运行 NoneBot 实例并不会产生任何效果，因为此刻 QQ 这边还不知道 NoneBot 的存在，也就无法把消息发送给它，因此现在需要使用一个无头 QQ 来把消息等事件上报给 NoneBot。 + +目前支持的协议有: + +- [OneBot(CQHTTP)](https://github.com/howmanybots/onebot) + +QQ 协议端举例: + +- [Mirai](https://github.com/mamoe/mirai) + [cqhttp-mirai](https://github.com/yyuueexxiinngg/cqhttp-mirai) +- [cqhttp-mirai-embedded](https://github.com/yyuueexxiinngg/cqhttp-mirai/tree/embedded) +- [Mirai](https://github.com/mamoe/mirai) + [Mirai Native](https://github.com/iTXTech/mirai-native) + [CQHTTP](https://github.com/richardchien/coolq-http-api) +- [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) (基于 [MiraiGo](https://github.com/Mrs4s/MiraiGo)) +- [OICQ-http-api](https://github.com/takayama-lily/onebot) (基于 [OICQ](https://github.com/takayama-lily/oicq)) + +这里以 [go-cqhttp](https://github.com/Mrs4s/go-cqhttp) 为例 + +1. 下载 go-cqhttp 对应平台的 release 文件 +2. 双击 exe 文件或者使用 `./go-cqhttp` 启动 +3. 生成默认配置文件并修改默认配置 + +```json{2,3,30-31} +{ + "uin": 你的QQ号, + "password": "你的密码", + "encrypt_password": false, + "password_encrypted": "", + "enable_db": true, + "access_token": "", + "relogin": { + "enabled": true, + "relogin_delay": 3, + "max_relogin_times": 0 + }, + "ignore_invalid_cqcode": false, + "force_fragmented": true, + "heartbeat_interval": 0, + "http_config": { + "enabled": false, + "host": "0.0.0.0", + "port": 5700, + "timeout": 0, + "post_urls": {} + }, + "ws_config": { + "enabled": false, + "host": "0.0.0.0", + "port": 6700 + }, + "ws_reverse_servers": [ + { + "enabled": true, + "reverse_url": "ws://127.0.0.1:8080/cqhttp/ws", + "reverse_api_url": "", + "reverse_event_url": "", + "reverse_reconnect_interval": 3000 + } + ], + "post_message_format": "string", + "debug": false, + "log_level": "" +} +``` + +其中 `ws://127.0.0.1:8080/cqhttp/ws` 中的 `127.0.0.1` 和 `8080` 应分别对应 nonebot 配置的 HOST 和 PORT + +## 历史性的第一次对话 + +一旦新的配置文件正确生效之后，NoneBot 所在的控制台（如果正在运行的话）应该会输出类似下面的内容（两条访问日志）： + +```default +09-14 21:31:16 [INFO] uvicorn | ('127.0.0.1', 12345) - "WebSocket /cqhttp/ws" [accepted] +09-14 21:31:16 [INFO] nonebot | WebSocket Connection from CQHTTP Bot 你的QQ号 Accepted! +``` + +这表示 QQ 协议端已经成功地使用 CQHTTP 协议连接上了 NoneBot。 + +:::warning 注意 +如果到这一步你没有看到上面这样的成功日志，CQHTTP 的日志中在不断地重连或无反应，请注意检查配置中的 IP 和端口是否确实可以访问。比较常见的出错点包括： + +- NoneBot 监听 `0.0.0.0`，然后在 CQHTTP 配置中填了 `ws://0.0.0.0:8080/cqhttp/ws` +- 在 Docker 容器内运行 CQHTTP，并通过 `127.0.0.1` 访问宿主机上的 NoneBot +- 想从公网访问，但没有修改云服务商的安全组策略或系统防火墙 +- NoneBot 所监听的端口存在冲突，已被其它程序占用 +- 弄混了 NoneBot 的 `host`、`port` 参数与 CQHTTP 配置中的 `host`、`port` 参数 +- 使用了 `ws_reverse_api_url` 和 `ws_reverse_event_url` 而非 universal client +- `ws://` 错填为 `http://` +- CQHTTP 或 NoneBot 启动时遭到外星武器干扰 + +请尝试重启 CQHTTP、重启 NoneBot、更换端口、修改防火墙、重启系统、仔细阅读前面的文档及提示、更新 CQHTTP 和 NoneBot 到最新版本等方式来解决。 +::: + +现在，尝试向你的 QQ 机器人账号发送如下内容： + +```default +/echo 你好，世界 +``` + +到这里如果一切 OK，你应该会收到机器人给你回复了 `你好，世界`。这一历史性的对话标志着你已经成功地运行了一个 NoneBot 的最小实例，开始了编写更强大的 QQ 机器人的创意之旅！ + + + + diff --git a/archive/2.0.0a5/guide/installation.md b/archive/2.0.0a5/guide/installation.md new file mode 100644 index 00000000..907630c9 --- /dev/null +++ b/archive/2.0.0a5/guide/installation.md @@ -0,0 +1,85 @@ +# 安装 + +## NoneBot + +:::warning 注意 +请确保你的 Python 版本 >= 3.7。 +::: + +请在安装 nonebot2 之前卸载 nonebot 1.x + +```bash +pip uninstall nonebot +pip install nonebot2 +``` + +如果你需要使用最新的（可能尚未发布的）特性，可以直接从 GitHub 仓库安装： + +```bash +# master +poetry add git+https://github.com/nonebot/nonebot2.git#master +# dev +poetry add git+https://github.com/nonebot/nonebot2.git#dev +``` + +或者克隆 Git 仓库后手动安装： + +```bash +git clone https://github.com/nonebot/nonebot2.git +cd nonebot2 +poetry install --no-dev # 推荐 +pip install . # 不推荐 +``` + +## 额外依赖 + +### APScheduler + +A task scheduling library for Python. + +可用于计划任务，后台执行任务等 + +```bash +pip install nonebot2[scheduler] +poetry add nonebot2[scheduler] +``` + +[View On GitHub](https://github.com/agronholm/apscheduler) + +### NoneBot-Test + +A test frontend for nonebot2. + +通过前端展示 nonebot 已加载的插件以及运行状态，同时可以用于模拟发送事件测试机器人 + +```bash +pip install nonebot2[test] +poetry add nonebot2[test] +``` + +[View On GitHub](https://github.com/nonebot/nonebot-test) + +### CLI + +CLI for nonebot2. + +一个多功能脚手架 + +```bash +pip install nonebot2[cli] +poetry add nonebot2[cli] +``` + +[View On GitHub](https://github.com/yanyongyu/nb-cli) + +### 我全都要 + +```bash +pip install nonebot2[full] +poetry add nonebot2[full] +``` + +```bash +pip install nonebot2[cli,scheduler] +poetry add nonebot2[cli,scheduler] +``` diff --git a/archive/2.0.0a5/guide/loading-a-plugin.md b/archive/2.0.0a5/guide/loading-a-plugin.md new file mode 100644 index 00000000..bb7db02d --- /dev/null +++ b/archive/2.0.0a5/guide/loading-a-plugin.md @@ -0,0 +1,95 @@ +# 加载插件 + +在 [创建一个完整的项目](creating-a-project) 一章节中，我们已经创建了插件目录 `awesome_bot/plugins`，现在我们在机器人入口文件中加载它。当然，你也可以单独加载一个插件。 + +## 加载内置插件 + +在 `bot.py` 文件中添加以下行： + +```python{5} +import nonebot + +nonebot.init() +# 加载 nonebot 内置插件 +nonebot.load_bulitin_plugins() + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +这将会加载 nonebot 内置的插件，它包含： + +- 命令 `say`：可由**superuser**使用，可以将消息内容由特殊纯文本转为富文本 +- 命令 `echo`：可由任何人使用，将消息原样返回 + +以上命令均需要指定机器人，即私聊、群聊内@机器人、群聊内称呼机器人昵称。参考 [Rule: to_me](../api/rule.md#to-me) + +## 加载插件目录 + +在 `bot.py` 文件中添加以下行： + +```python{5} +import nonebot + +nonebot.init() +# 加载插件目录，该目录下为各插件，以下划线开头的插件将不会被加载 +nonebot.load_plugins("awesome_bot/plugins") + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +:::tip 提示 +加载插件目录时，目录下以 `_` 下划线开头的插件将不会被加载！ +::: + +:::warning 提示 +**插件不能存在相同名称！** +::: + +:::danger 警告 +插件间不应该存在过多的耦合，如果确实需要导入某个插件内的数据，可以使用如下两种方法： + +1. (推荐) `from plugin_name import xxx` 而非 `from awesome_bot.plugins.plugin_name import xxx` +2. 在需要导入其他插件的文件中添加 `__package__ = "plugins"; from .plugin_name import xxx` (将共同的上层目录设定为父包后使用相对导入) + +具体可以参考：[nonebot/nonebot2#32](https://github.com/nonebot/nonebot2/issues/32) +::: + +## 加载单个插件 + +在 `bot.py` 文件中添加以下行： + +```python{5,7} +import nonebot + +nonebot.init() +# 加载一个 pip 安装的插件 +nonebot.load_plugin("nonebot_plugin_status") +# 加载本地的单独插件 +nonebot.load_plugin("awesome_bot.plugins.xxx") + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +## 子插件(嵌套插件) + + + +~~待填坑~~ + +## 运行结果 + +尝试运行 `nb run` 或者 `python bot.py`，可以看到日志输出了类似如下内容： + +```plain +09-19 21:51:59 [INFO] nonebot | Succeeded to import "nonebot.plugins.base" +09-19 21:51:59 [INFO] nonebot | Succeeded to import "plugin_in_folder" +``` diff --git a/archive/2.0.0a5/sidebar.config.json b/archive/2.0.0a5/sidebar.config.json new file mode 100644 index 00000000..94ec57ab --- /dev/null +++ b/archive/2.0.0a5/sidebar.config.json @@ -0,0 +1,131 @@ +{ + "sidebar": {}, + "locales": { + "/": { + "label": "简体中文", + "selectText": "Languages", + "editLinkText": "在 GitHub 上编辑此页", + "lastUpdated": "上次更新", + "nav": [ + { + "text": "主页", + "link": "/" + }, + { + "text": "指南", + "link": "/guide/" + }, + { + "text": "API", + "link": "/api/" + }, + { + "text": "插件广场", + "link": "/plugin-store" + } + ], + "sidebarDepth": 2, + "sidebar": { + "/guide/": [ + { + "title": "开始", + "collapsable": false, + "sidebar": "auto", + "children": [ + "", + "installation", + "getting-started", + "creating-a-project", + "basic-configuration" + ] + }, + { + "title": "编写插件", + "collapsable": false, + "sidebar": "auto", + "children": [ + "loading-a-plugin", + "creating-a-plugin", + "creating-a-matcher", + "creating-a-handler", + "end-or-start" + ] + } + ], + "/api/": [ + { + "title": "NoneBot Api Reference", + "path": "", + "collapsable": false, + "children": [ + { + "title": "nonebot 模块", + "path": "nonebot" + }, + { + "title": "nonebot.config 模块", + "path": "config" + }, + { + "title": "nonebot.plugin 模块", + "path": "plugin" + }, + { + "title": "nonebot.message 模块", + "path": "message" + }, + { + "title": "nonebot.matcher 模块", + "path": "matcher" + }, + { + "title": "nonebot.rule 模块", + "path": "rule" + }, + { + "title": "nonebot.permission 模块", + "path": "permission" + }, + { + "title": "nonebot.sched 模块", + "path": "sched" + }, + { + "title": "nonebot.log 模块", + "path": "log" + }, + { + "title": "nonebot.utils 模块", + "path": "utils" + }, + { + "title": "nonebot.typing 模块", + "path": "typing" + }, + { + "title": "nonebot.exception 模块", + "path": "exception" + }, + { + "title": "nonebot.drivers 模块", + "path": "drivers/" + }, + { + "title": "nonebot.drivers.fastapi 模块", + "path": "drivers/fastapi" + }, + { + "title": "nonebot.adapters 模块", + "path": "adapters/" + }, + { + "title": "nonebot.adapters.cqhttp 模块", + "path": "adapters/cqhttp" + } + ] + } + ] + } + } + } +} \ No newline at end of file diff --git a/docs/.vuepress/versions.json b/docs/.vuepress/versions.json index 56a1527a..aa00d565 100644 --- a/docs/.vuepress/versions.json +++ b/docs/.vuepress/versions.json @@ -1,3 +1,4 @@ [ + "2.0.0a5", "2.0.0a4" ] \ No newline at end of file