🔀 Merge pull request #94

Add dingding adapter
2025-07-27 16:21:28 +00:00 · 2020-12-03 19:33:58 +08:00
parent b47bef3ef6 0838cdfbe7
commit b24649b6af
31 changed files with 1361 additions and 384 deletions
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@ -198,6 +198,10 @@ module.exports = context => ({
                {
                  title: "nonebot.adapters.cqhttp 模块",
                  path: "adapters/cqhttp"
+                },
+                {
+                  title: "nonebot.adapters.ding 模块",
+                  path: "adapters/ding"
                }
              ]
            }
--- a/docs/api/README.md
+++ b/docs/api/README.md
@ -47,3 +47,6 @@


    * [nonebot.adapters.cqhttp](adapters/cqhttp.html)
+
+
+    * [nonebot.adapters.ding](adapters/ding.html)
--- a/docs/api/adapters/README.md
+++ b/docs/api/adapters/README.md
@ -176,7 +176,7 @@ await bot.send_msg(message="hello world")

 ## _class_ `BaseEvent`

-基类：`abc.ABC`
+基类：`abc.ABC`, `typing.Generic`

 Event 基类。提供上报信息的关键信息，其余信息可从原始上报消息获取。

@ -187,7 +187,7 @@ Event 基类。提供上报信息的关键信息，其余信息可从原始上
 * **参数**

    
-    * `raw_event: dict`: 原始上报消息
+    * `raw_event: Union[dict, T]`: 原始上报消息



@ -309,7 +309,7 @@ Event 基类。提供上报信息的关键信息，其余信息可从原始上
 * **参数**

    
-    * `message: Union[str, dict, list, MessageSegment, Message]`: 消息内容
+    * `message: Union[str, dict, list, BaseModel, MessageSegment, Message]`: 消息内容



@ -350,7 +350,7 @@ Event 基类。提供上报信息的关键信息，其余信息可从原始上

 * **说明**

-    缩减消息数组，即拼接相邻纯文本消息段
+    缩减消息数组，即按 MessageSegment 的实现拼接相邻消息段



--- a/docs/api/adapters/cqhttp.md
+++ b/docs/api/adapters/cqhttp.md
@ -5,29 +5,6 @@ sidebarDepth: 0

 # NoneBot.adapters.cqhttp 模块

-## CQHTTP (OneBot) v11 协议适配
-
-协议详情请看: [CQHTTP](https://github.com/howmanybots/onebot/blob/master/README.md) | [OneBot](https://github.com/howmanybots/onebot/blob/master/README.md)
-
-
-## `log(level, message)`
-
-
-* **说明**
-
-    用于打印 CQHTTP 日志。
-
-
-
-* **参数**
-
-    
-    * `level: str`: 日志等级
-
-
-    * `message: str`: 日志信息
-
-

 ## `escape(s, *, escape_comma=True)`

@ -64,9 +41,50 @@ sidebarDepth: 0



-## `_b2s(b)`
+## _exception_ `CQHTTPAdapterException`

-转换布尔值为字符串。
+基类：[`nonebot.exception.AdapterException`](../exception.md#nonebot.exception.AdapterException)
+
+
+## _exception_ `ActionFailed`
+
+基类：[`nonebot.exception.ActionFailed`](../exception.md#nonebot.exception.ActionFailed), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`
+
+
+* **说明**
+
+    API 请求返回错误信息。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `NetworkError`
+
+基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`
+
+
+* **说明**
+
+    网络错误。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `ApiNotAvailable`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.cqhttp.exception.CQHTTPAdapterException`


 ## _async_ `_check_reply(bot, event)`
--- a/docs/api/adapters/ding.md
+++ b/docs/api/adapters/ding.md
@ -0,0 +1,380 @@
+---
+contentSidebar: true
+sidebarDepth: 0
+---
+
+# NoneBot.adapters.ding 模块
+
+
+## _exception_ `DingAdapterException`
+
+基类：[`nonebot.exception.AdapterException`](../exception.md#nonebot.exception.AdapterException)
+
+
+* **说明**
+
+    钉钉 Adapter 错误基类
+
+
+
+## _exception_ `ActionFailed`
+
+基类：[`nonebot.exception.ActionFailed`](../exception.md#nonebot.exception.ActionFailed), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    API 请求返回错误信息。
+
+
+
+* **参数**
+
+    
+    * `errcode: Optional[int]`: 错误码
+
+
+    * `errmsg: Optional[str]`: 错误信息
+
+
+
+## _exception_ `ApiNotAvailable`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+## _exception_ `NetworkError`
+
+基类：[`nonebot.exception.NetworkError`](../exception.md#nonebot.exception.NetworkError), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    网络错误。
+
+
+
+* **参数**
+
+    
+    * `retcode: Optional[int]`: 错误码
+
+
+
+## _exception_ `SessionExpired`
+
+基类：[`nonebot.exception.ApiNotAvailable`](../exception.md#nonebot.exception.ApiNotAvailable), `nonebot.adapters.ding.exception.DingAdapterException`
+
+
+* **说明**
+
+    发消息的 session 已经过期。
+
+
+
+## _class_ `Bot`
+
+基类：[`nonebot.adapters.BaseBot`](README.md#nonebot.adapters.BaseBot)
+
+钉钉 协议 Bot 适配。继承属性参考 [BaseBot](./#class-basebot) 。
+
+
+### _property_ `type`
+
+
+* 返回: `"ding"`
+
+
+### _async classmethod_ `check_permission(driver, connection_type, headers, body)`
+
+
+* **说明**
+
+    钉钉协议鉴权。参考 [鉴权](https://ding-doc.dingtalk.com/doc#/serverapi2/elzz1p)
+
+
+
+### _async_ `handle_message(body)`
+
+
+* **说明**
+
+    处理上报消息的函数，转换为 `Event` 事件后调用 `nonebot.message.handle_event` 进一步处理事件。
+
+
+
+* **参数**
+
+    
+    * `message: dict`: 收到的上报消息
+
+
+
+### _async_ `call_api(api, event=None, **data)`
+
+
+* **说明**
+
+    调用 钉钉 协议 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)
+
+钉钉 协议 Event 适配。继承属性参考 [BaseEvent](./#class-baseevent) 。
+
+
+### _property_ `raw_event`
+
+原始上报消息
+
+
+### _property_ `id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 消息 ID
+
+
+### _property_ `name`
+
+
+* 类型: `str`
+
+
+* 说明: 事件名称，由 type.\`detail_type\` 组合而成
+
+
+### _property_ `self_id`
+
+
+* 类型: `str`
+
+
+* 说明: 机器人自身 ID
+
+
+### _property_ `time`
+
+
+* 类型: `int`
+
+
+* 说明: 消息的时间戳，单位 s
+
+
+### _property_ `type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件类型
+
+
+### _property_ `detail_type`
+
+
+* 类型: `str`
+
+
+* 说明: 事件详细类型
+
+
+### _property_ `sub_type`
+
+
+* 类型: `None`
+
+
+* 说明: 钉钉适配器无事件子类型
+
+
+### _property_ `user_id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 发送者 ID
+
+
+### _property_ `group_id`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 事件主体群 ID
+
+
+### _property_ `to_me`
+
+
+* 类型: `Optional[bool]`
+
+
+* 说明: 消息是否与机器人相关
+
+
+### _property_ `message`
+
+
+* 类型: `Optional[Message]`
+
+
+* 说明: 消息内容
+
+
+### _property_ `reply`
+
+
+* 类型: `None`
+
+
+* 说明: 回复消息详情
+
+
+### _property_ `raw_message`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 原始消息
+
+
+### _property_ `plain_text`
+
+
+* 类型: `Optional[str]`
+
+
+* 说明: 纯文本消息内容
+
+
+### _property_ `sender`
+
+
+* 类型: `Optional[dict]`
+
+
+* 说明: 消息发送者信息
+
+
+## _class_ `MessageSegment`
+
+基类：[`nonebot.adapters.BaseMessageSegment`](README.md#nonebot.adapters.BaseMessageSegment)
+
+钉钉 协议 MessageSegment 适配。具体方法参考协议消息段类型或源码。
+
+
+### _static_ `actionCardSingleMultiBtns(title, text, btns=[], hideAvatar=False, btnOrientation='1')`
+
+
+* **参数**
+
+    
+    * `btnOrientation`: 0：按钮竖直排列 1：按钮横向排列
+
+
+    * `btns`: [{ "title": title, "actionURL": actionURL }, ...]
+
+
+
+### _static_ `feedCard(links=[])`
+
+
+* **参数**
+
+    
+    * `links`: [{ "title": xxx, "messageURL": xxx, "picURL": xxx }, ...]
+
+
+
+### _static_ `empty()`
+
+不想回复消息到群里
+
+
+## _class_ `Message`
+
+基类：[`nonebot.adapters.BaseMessage`](README.md#nonebot.adapters.BaseMessage)
+
+钉钉 协议 Message 适配。
--- a/docs/api/exception.md
+++ b/docs/api/exception.md
@ -11,11 +11,22 @@ sidebarDepth: 0
 这些异常并非所有需要用户处理，在 NoneBot 内部运行时被捕获，并进行对应操作。


-## _exception_ `IgnoredException`
+## _exception_ `NoneBotException`

 基类：`Exception`


+* **说明**
+
+    所有 NoneBot 发生的异常基类。
+
+
+
+## _exception_ `IgnoredException`
+
+基类：`nonebot.exception.NoneBotException`
+
+
 * **说明**

    指示 NoneBot 应该忽略该事件。可由 PreProcessor 抛出。
@ -31,7 +42,7 @@ sidebarDepth: 0

 ## _exception_ `PausedException`

-基类：`Exception`
+基类：`nonebot.exception.NoneBotException`


 * **说明**
@ -49,7 +60,7 @@ sidebarDepth: 0

 ## _exception_ `RejectedException`

-基类：`Exception`
+基类：`nonebot.exception.NoneBotException`


 * **说明**
@ -67,7 +78,7 @@ sidebarDepth: 0

 ## _exception_ `FinishedException`

-基类：`Exception`
+基类：`nonebot.exception.NoneBotException`


 * **说明**
@ -85,7 +96,7 @@ sidebarDepth: 0

 ## _exception_ `StopPropagation`

-基类：`Exception`
+基类：`nonebot.exception.NoneBotException`


 * **说明**
@ -102,7 +113,7 @@ sidebarDepth: 0

 ## _exception_ `RequestDenied`

-基类：`Exception`
+基类：`nonebot.exception.NoneBotException`


 * **说明**
@ -121,9 +132,27 @@ sidebarDepth: 0



+## _exception_ `AdapterException`
+
+基类：`nonebot.exception.NoneBotException`
+
+
+* **说明**
+
+    代表 `Adapter` 抛出的异常，所有的 `Adapter` 都要在内部继承自这个 `Exception`
+
+
+
+* **参数**
+
+    
+    * `adapter_name: str`: 标识 adapter
+
+
+
 ## _exception_ `ApiNotAvailable`

-基类：`Exception`
+基类：`nonebot.exception.AdapterException`


 * **说明**
@ -134,7 +163,7 @@ sidebarDepth: 0

 ## _exception_ `NetworkError`

-基类：`Exception`
+基类：`nonebot.exception.AdapterException`


 * **说明**
@ -145,16 +174,9 @@ sidebarDepth: 0

 ## _exception_ `ActionFailed`

-基类：`Exception`
+基类：`nonebot.exception.AdapterException`


 * **说明**

    API 请求成功返回数据，但 API 操作失败。
-
-
-
-* **参数**
-
-    
-    * `retcode: Optional[int]`: 错误代码
--- a/docs/api/utils.md
+++ b/docs/api/utils.md
@ -54,8 +54,6 @@ sidebarDepth: 0

 ## _class_ `DataclassEncoder`

-基类：`json.encoder.JSONEncoder`
-

 * **说明**