📝 update doc

nonebot/adapters/cqhttp/__init__.py

@@ -11,6 +11,7 @@ CQHTTP (OneBot) v11 协议适配
 """
 
 from .event import *
+from .permission import *
 from .message import Message, MessageSegment
 from .utils import log, escape, unescape, _b2s
 from .bot import Bot, _check_at_me, _check_nickname, _check_reply, _handle_api_result

nonebot/adapters/cqhttp/event.py

@@ -14,7 +14,7 @@ from .message import Message
 
 class Event(BaseEvent):
     """
-    CQHTTP 协议事件。各事件字段未列出部分参考 `CQHTTP 文档`_
+    CQHTTP 协议事件，字段与 CQHTTP 一致。各事件字段参考 `CQHTTP 文档`_
 
     .. _CQHTTP 文档:
         https://github.com/howmanybots/onebot/blob/master/README.md

nonebot/adapters/cqhttp/permission.py

@@ -0,0 +1,86 @@
+from typing import TYPE_CHECKING
+
+from nonebot.permission import Permission
+
+from .event import PrivateMessageEvent, GroupMessageEvent
+
+if TYPE_CHECKING:
+    from nonebot.adapters import Bot, Event
+
+
+async def _private(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, PrivateMessageEvent)
+
+
+async def _private_friend(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, PrivateMessageEvent) and event.sub_type == "friend"
+
+
+async def _private_group(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, PrivateMessageEvent) and event.sub_type == "group"
+
+
+async def _private_other(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, PrivateMessageEvent) and event.sub_type == "other"
+
+
+PRIVATE = Permission(_private)
+"""
+- **说明**: 匹配任意私聊消息类型事件
+"""
+PRIVATE_FRIEND = Permission(_private_friend)
+"""
+- **说明**: 匹配任意好友私聊消息类型事件
+"""
+PRIVATE_GROUP = Permission(_private_group)
+"""
+- **说明**: 匹配任意群临时私聊消息类型事件
+"""
+PRIVATE_OTHER = Permission(_private_other)
+"""
+- **说明**: 匹配任意其他私聊消息类型事件
+"""
+
+
+async def _group(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, GroupMessageEvent)
+
+
+async def _group_member(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event,
+                      GroupMessageEvent) and event.sender.role == "member"
+
+
+async def _group_admin(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, GroupMessageEvent) and event.sender.role == "admin"
+
+
+async def _group_owner(bot: "Bot", event: "Event") -> bool:
+    return isinstance(event, GroupMessageEvent) and event.sender.role == "owner"
+
+
+GROUP = Permission(_group)
+"""
+- **说明**: 匹配任意群聊消息类型事件
+"""
+GROUP_MEMBER = Permission(_group_member)
+"""
+- **说明**: 匹配任意群员群聊消息类型事件
+
+\:\:\:warning 警告
+该权限通过 event.sender 进行判断且不包含管理员以及群主！
+\:\:\:
+"""
+GROUP_ADMIN = Permission(_group_admin)
+"""
+- **说明**: 匹配任意群管理员群聊消息类型事件
+"""
+GROUP_OWNER = Permission(_group_owner)
+"""
+- **说明**: 匹配任意群主群聊消息类型事件
+"""
+
+__all__ = [
+    "PRIVATE", "PRIVATE_FRIEND", "PRIVATE_GROUP", "PRIVATE_OTHER", "GROUP",
+    "GROUP_MEMBER", "GROUP_ADMIN", "GROUP_OWNER"
+]

nonebot/adapters/ding/__init__.py

@@ -5,8 +5,7 @@
 协议详情请看: `钉钉文档`_
 
 .. _钉钉文档:
-    https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p/
-
+    https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p
 """
 
 from .utils import log

nonebot/adapters/ding/event.py

@@ -12,7 +12,7 @@ from .message import Message
 
 class Event(BaseEvent):
     """
-    钉钉 协议 Event 适配。各事件字段参考 `钉钉文档`_
+    钉钉协议事件。各事件字段参考 `钉钉文档`_
 
     .. _钉钉文档:
         https://ding-doc.dingtalk.com/document#/org-dev-guide/elzz1p
@@ -68,6 +68,7 @@ class ConversationType(str, Enum):
 
 
 class MessageEvent(Event):
+    """消息事件"""
     msgtype: str
     text: TextMessage
     msgId: str
@@ -126,12 +127,14 @@ class MessageEvent(Event):
 
 
 class PrivateMessageEvent(MessageEvent):
+    """私聊消息事件"""
     chatbotCorpId: str
     senderStaffId: Optional[str]
     conversationType: ConversationType = ConversationType.private
 
 
 class GroupMessageEvent(MessageEvent):
+    """群消息事件"""
     atUsers: List[AtUsersItem]
     conversationType: ConversationType = ConversationType.group
     conversationTitle: str

nonebot/adapters/ding/message.py

@@ -36,28 +36,32 @@ class MessageSegment(BaseMessageSegment):
 
     @staticmethod
     def atAll() -> "MessageSegment":
+        """@全体"""
         return MessageSegment("at", {"isAtAll": True})
 
     @staticmethod
     def atMobiles(*mobileNumber: str) -> "MessageSegment":
+        """@指定手机号人员"""
         return MessageSegment("at", {"atMobiles": list(mobileNumber)})
 
     @staticmethod
     def text(text: str) -> "MessageSegment":
+        """发送 ``text`` 类型消息"""
         return MessageSegment("text", {"content": text})
 
     @staticmethod
     def image(picURL: str) -> "MessageSegment":
+        """发送 ``image`` 类型消息"""
         return MessageSegment("image", {"picURL": picURL})
 
     @staticmethod
     def extension(dict_: dict) -> "MessageSegment":
-        """"标记 text 文本的 extension 属性，需要与 text 消息段相加。
-        """
+        """"标记 text 文本的 extension 属性，需要与 text 消息段相加。"""
         return MessageSegment("extension", dict_)
 
     @staticmethod
     def markdown(title: str, text: str) -> "MessageSegment":
+        """发送 ``markdown`` 类型消息"""
         return MessageSegment(
             "markdown",
             {
@@ -69,6 +73,7 @@ class MessageSegment(BaseMessageSegment):
     @staticmethod
     def actionCardSingleBtn(title: str, text: str, singleTitle: str,
                             singleURL) -> "MessageSegment":
+        """发送 ``actionCardSingleBtn`` 类型消息"""
         return MessageSegment(
             "actionCard", {
                 "title": title,
@@ -86,10 +91,11 @@ class MessageSegment(BaseMessageSegment):
         btnOrientation: str = '1',
     ) -> "MessageSegment":
         """
+        发送 ``actionCardMultiBtn`` 类型消息
+
         :参数:
 
             * ``btnOrientation``: 0：按钮竖直排列 1：按钮横向排列
-
             * ``btns``: [{ "title": title, "actionURL": actionURL }, ...]
         """
         return MessageSegment(
@@ -104,6 +110,8 @@ class MessageSegment(BaseMessageSegment):
     @staticmethod
     def feedCard(links: list) -> "MessageSegment":
         """
+        发送 ``feedCard`` 类型消息
+
         :参数:
 
             * ``links``: [{ "title": xxx, "messageURL": xxx, "picURL": xxx }, ...]