From e4377faa670a1674f9bc75bf983ffd13900e6b74 Mon Sep 17 00:00:00 2001 From: yanyongyu Date: Sun, 13 Dec 2020 12:53:33 +0800 Subject: [PATCH] :lipstick: update docs --- docs/api/adapters/README.md | 94 +------------------- docs/api/adapters/cqhttp.md | 157 +++++++++++++++++++++++---------- docs/api/exception.md | 11 +++ docs/api/permission.md | 60 +------------ docs/api/rule.md | 2 +- docs/api/typing.md | 2 +- docs/api/utils.md | 24 +++++ docs_build/adapters/cqhttp.rst | 12 +-- docs_build/utils.rst | 2 +- nonebot/config.py | 14 +++ 10 files changed, 171 insertions(+), 207 deletions(-) diff --git a/docs/api/adapters/README.md b/docs/api/adapters/README.md index 61436c5c..288f77bf 100644 --- a/docs/api/adapters/README.md +++ b/docs/api/adapters/README.md @@ -176,99 +176,7 @@ await bot.send_msg(message="hello world") ## _class_ `Event` -基类：`abc.ABC`, `typing.Generic` - -Event 基类。提供上报信息的关键信息，其余信息可从原始上报消息获取。 - - -### `__init__(raw_event)` - - -* **参数** - - - * `raw_event: Union[dict, T]`: 原始上报消息 - - - -### _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` - -消息发送者信息 +基类：`abc.ABC`, `pydantic.main.BaseModel` ## _class_ `MessageSegment` diff --git a/docs/api/adapters/cqhttp.md b/docs/api/adapters/cqhttp.md index ba3c57aa..a2098304 100644 --- a/docs/api/adapters/cqhttp.md +++ b/docs/api/adapters/cqhttp.md @@ -290,142 +290,207 @@ CQHTTP 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。 基类：[`nonebot.adapters.Event`](README.md#nonebot.adapters.Event) -CQHTTP 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent) 。 +CQHTTP 协议事件。各事件字段未列出部分参考 [CQHTTP 文档](https://github.com/howmanybots/onebot/blob/master/README.md) -### _property_ `id` +## _class_ `MessageEvent` +基类：`nonebot.adapters.cqhttp.event.Event` -* 类型: `Optional[int]` +消息事件 -* 说明: 事件/消息 ID +### `to_me` -### _property_ `name` +* **说明** + 消息是否与机器人有关 -* 类型: `str` -* 说明: 事件名称，由类型与 `.` 组合而成 +* **类型** + `bool` -### _property_ `self_id` -* 类型: `str` +### `reply` -* 说明: 机器人自身 ID +* **说明** + 消息中提取的回复消息，内容为 `get_msg` API 返回结果 -### _property_ `time` -* 类型: `int` +* **类型** + `Optional[Reply]` -* 说明: 事件发生时间 -### _property_ `type` +## _class_ `PrivateMessageEvent` +基类：`nonebot.adapters.cqhttp.event.MessageEvent` -* 类型: `str` +私聊消息 -* 说明: 事件类型 +## _class_ `GroupMessageEvent` +基类：`nonebot.adapters.cqhttp.event.MessageEvent` -### _property_ `detail_type` +群消息 -* 类型: `str` +## _class_ `NoticeEvent` +基类：`nonebot.adapters.cqhttp.event.Event` -* 说明: 事件详细类型 +通知事件 -### _property_ `sub_type` +## _class_ `GroupUploadNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 类型: `Optional[str]` +群文件上传事件 -* 说明: 事件子类型 +## _class_ `GroupAdminNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -### _property_ `user_id` +群管理员变动 -* 类型: `Optional[int]` +## _class_ `GroupDecreaseNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 说明: 事件主体 ID +群成员减少事件 -### _property_ `group_id` +## _class_ `GroupIncreaseNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 类型: `Optional[int]` +群成员增加事件 -* 说明: 事件主体群 ID +## _class_ `GroupBanNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -### _property_ `to_me` +群禁言事件 -* 类型: `Optional[bool]` +## _class_ `FriendAddNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 说明: 消息是否与机器人相关 +好友添加事件 -### _property_ `message` +## _class_ `GroupRecallNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 类型: `Optional[Message]` +群消息撤回事件 -* 说明: 消息内容 +## _class_ `FriendRecallNoticeEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -### _property_ `reply` +好友消息撤回事件 -* 类型: `Optional[dict]` +## _class_ `NotifyEvent` +基类：`nonebot.adapters.cqhttp.event.NoticeEvent` -* 说明: 回复消息详情 +提醒事件 -### _property_ `raw_message` +## _class_ `PokeNotifyEvent` +基类：`nonebot.adapters.cqhttp.event.NotifyEvent` -* 类型: `Optional[str]` +戳一戳提醒事件 -* 说明: 原始消息 +## _class_ `LuckyKingNotifyEvent` +基类：`nonebot.adapters.cqhttp.event.NotifyEvent` -### _property_ `plain_text` +群红包运气王提醒事件 -* 类型: `Optional[str]` +## _class_ `HonorNotifyEvent` +基类：`nonebot.adapters.cqhttp.event.NotifyEvent` -* 说明: 纯文本消息内容 +群荣誉变更提醒事件 -### _property_ `sender` +## _class_ `RequestEvent` +基类：`nonebot.adapters.cqhttp.event.Event` -* 类型: `Optional[dict]` +请求事件 -* 说明: 消息发送者信息 +## _class_ `FriendRequestEvent` + +基类：`nonebot.adapters.cqhttp.event.RequestEvent` + +加好友请求事件 + + +## _class_ `GroupRequestEvent` + +基类：`nonebot.adapters.cqhttp.event.RequestEvent` + +加群请求/邀请事件 + + +## _class_ `MetaEvent` + +基类：`nonebot.adapters.cqhttp.event.Event` + +元事件 + + +## _class_ `LifecycleMetaEvent` + +基类：`nonebot.adapters.cqhttp.event.MetaEvent` + +生命周期元事件 + + +## _class_ `HeartbeatMetaEvent` + +基类：`nonebot.adapters.cqhttp.event.MetaEvent` + +心跳元事件 + + +## `get_event_model(event_name)` + + +* **说明** + + 根据事件名获取对应 `Event Model` 及 `FallBack Event Model` 列表 + + + +* **返回** + + + * `List[Type[Event]]` + ## _class_ `MessageSegment` diff --git a/docs/api/exception.md b/docs/api/exception.md index 0c584f75..ac2d28b2 100644 --- a/docs/api/exception.md +++ b/docs/api/exception.md @@ -150,6 +150,17 @@ sidebarDepth: 0 +## _exception_ `NoLogException` + +基类：`Exception` + + +* **说明** + + 指示 NoneBot 对当前 `Event` 进行处理但不显示 Log 信息，可在 `get_log_string` 时抛出 + + + ## _exception_ `ApiNotAvailable` 基类：`nonebot.exception.AdapterException` diff --git a/docs/api/permission.md b/docs/api/permission.md index 26d3cd34..1c42b2c8 100644 --- a/docs/api/permission.md +++ b/docs/api/permission.md @@ -50,72 +50,14 @@ sidebarDepth: 0 * **参数** - * `*user: int`: 白名单 + * `*user: str`: 白名单 * `perm: Permission`: 需要同时满足的权限 -## `PRIVATE` - - -* **说明**: 匹配任意私聊消息类型事件 - - -## `PRIVATE_FRIEND` - - -* **说明**: 匹配任意好友私聊消息类型事件 - - -## `PRIVATE_GROUP` - - -* **说明**: 匹配任意群临时私聊消息类型事件 - - -## `PRIVATE_OTHER` - - -* **说明**: 匹配任意其他私聊消息类型事件 - - -## `GROUP` - - -* **说明**: 匹配任意群聊消息类型事件 - - -## `GROUP_MEMBER` - - -* **说明**: 匹配任意群员群聊消息类型事件 - -:::warning 警告 -该权限通过 event.sender 进行判断且不包含管理员以及群主！ -::: - - -## `GROUP_ADMIN` - - -* **说明**: 匹配任意群管理员群聊消息类型事件 - - -## `GROUP_OWNER` - - -* **说明**: 匹配任意群主群聊消息类型事件 - - ## `SUPERUSER` * **说明**: 匹配任意超级用户消息类型事件 - - -## `EVERYBODY` - - -* **说明**: 匹配任意消息类型事件 diff --git a/docs/api/rule.md b/docs/api/rule.md index a9c173f6..e22d7fde 100644 --- a/docs/api/rule.md +++ b/docs/api/rule.md @@ -200,7 +200,7 @@ Rule(async_function, run_sync(sync_function)) * **说明** - 通过 `event.to_me` 判断消息是否是发送给机器人 + 通过 `event.to_me` 判断事件是否与机器人有关 diff --git a/docs/api/typing.md b/docs/api/typing.md index 4bf5fa67..95f45c42 100644 --- a/docs/api/typing.md +++ b/docs/api/typing.md @@ -147,7 +147,7 @@ sidebarDepth: 0 * **类型** - `Callable[[Bot, Event, State], Awaitable[None]]` + `Callable[[Bot, Event, State], Union[Awaitable[None], Awaitable[NoReturn]]]` diff --git a/docs/api/utils.md b/docs/api/utils.md index 52cf5766..ab3ea0c2 100644 --- a/docs/api/utils.md +++ b/docs/api/utils.md @@ -52,8 +52,32 @@ sidebarDepth: 0 +## `logger_wrapper` + + +* **说明** + + +用于打印 adapter 的日志。 + + +* **Log 参数** + + + +* `level: Literal['WARNING', 'DEBUG', 'INFO']`: 日志等级 + + +* `message: str`: 日志信息 + + +* `exception: Optional[Exception]`: 异常信息 + + ## _class_ `DataclassEncoder` +基类：`json.encoder.JSONEncoder` + * **说明** diff --git a/docs_build/adapters/cqhttp.rst b/docs_build/adapters/cqhttp.rst index 4714296d..e885728d 100644 --- a/docs_build/adapters/cqhttp.rst +++ b/docs_build/adapters/cqhttp.rst @@ -21,13 +21,13 @@ NoneBot.adapters.cqhttp 模块 :show-inheritance: -.. automodule:: nonebot.adapters.cqhttp.event - :members: - :private-members: - :show-inheritance: - - .. automodule:: nonebot.adapters.cqhttp.message :members: :private-members: :show-inheritance: + + +.. automodule:: nonebot.adapters.cqhttp.event + :members: + :private-members: + :show-inheritance: diff --git a/docs_build/utils.rst b/docs_build/utils.rst index 5e7acd8d..ff724b1a 100644 --- a/docs_build/utils.rst +++ b/docs_build/utils.rst @@ -9,6 +9,6 @@ NoneBot.utils 模块 .. autofunction:: nonebot.utils.escape_tag .. autodecorator:: nonebot.utils.run_sync -.. autoclass:: nonebot.utils.DataclassEncoder .. autodecorator:: nonebot.utils.logger_wrapper +.. autoclass:: nonebot.utils.DataclassEncoder :show-inheritance: diff --git a/nonebot/config.py b/nonebot/config.py index e1ac2b71..6add7e7c 100644 --- a/nonebot/config.py +++ b/nonebot/config.py @@ -103,6 +103,7 @@ class Env(BaseSettings): """ - **类型**: ``str`` - **默认值**: ``"prod"`` + :说明: 当前环境名。 NoneBot 将从 ``.env.{environment}`` 文件中加载配置。 """ @@ -123,6 +124,7 @@ class Config(BaseConfig): """ - **类型**: ``str`` - **默认值**: ``"nonebot.drivers.fastapi"`` + :说明: NoneBot 运行所使用的 ``Driver`` 。继承自 ``nonebot.driver.BaseDriver`` 。 @@ -131,6 +133,7 @@ class Config(BaseConfig): """ - **类型**: ``IPvAnyAddress`` - **默认值**: ``127.0.0.1`` + :说明: NoneBot 的 HTTP 和 WebSocket 服务端监听的 IP/主机名。 @@ -139,6 +142,7 @@ class Config(BaseConfig): """ - **类型**: ``int`` - **默认值**: ``8080`` + :说明: NoneBot 的 HTTP 和 WebSocket 服务端监听的端口。 @@ -147,6 +151,7 @@ class Config(BaseConfig): """ - **类型**: ``bool`` - **默认值**: ``False`` + :说明: 是否以调试模式运行 NoneBot。 @@ -157,6 +162,7 @@ class Config(BaseConfig): """ - **类型**: ``Dict[str, str]`` - **默认值**: ``{}`` + :说明: 以机器人 ID 为键，上报地址为值的字典，环境变量或文件中应使用 json 序列化。 @@ -171,6 +177,7 @@ class Config(BaseConfig): """ - **类型**: ``Optional[float]`` - **默认值**: ``30.`` + :说明: API 请求超时时间，单位: 秒。 @@ -179,6 +186,7 @@ class Config(BaseConfig): """ - **类型**: ``Optional[str]`` - **默认值**: ``None`` + :说明: API 请求以及上报所需密钥，在请求头中携带。 @@ -194,6 +202,7 @@ class Config(BaseConfig): """ - **类型**: ``Optional[str]`` - **默认值**: ``None`` + :说明: HTTP POST 形式上报所需签名，在请求头中携带。 @@ -211,6 +220,7 @@ class Config(BaseConfig): """ - **类型**: ``Set[int]`` - **默认值**: ``set()`` + :说明: 机器人超级用户。 @@ -225,6 +235,7 @@ class Config(BaseConfig): """ - **类型**: ``Set[str]`` - **默认值**: ``set()`` + :说明: 机器人昵称。 @@ -233,6 +244,7 @@ class Config(BaseConfig): """ - **类型**: ``Set[str]`` - **默认值**: ``{"/"}`` + :说明: 命令的起始标记，用于判断一条消息是不是命令。 @@ -241,6 +253,7 @@ class Config(BaseConfig): """ - **类型**: ``Set[str]`` - **默认值**: ``{"."}`` + :说明: 命令的分隔标记，用于将文本形式的命令切分为元组（实际的命令名）。 @@ -249,6 +262,7 @@ class Config(BaseConfig): """ - **类型**: ``timedelta`` - **默认值**: ``timedelta(minutes=2)`` + :说明: 等待用户回复的超时时间。