💬 💡 rename some dataclass, add comments for events in mirai adapter

docs_build/adapters/mirai.rst

@@ -9,63 +9,70 @@ NoneBot.adapters.mirai 模块
 .. automodule:: nonebot.adapters.mirai
 
 NoneBot.adapters.mirai.bot 模块
-=====================================
+===============================
 
 .. automodule:: nonebot.adapters.mirai.bot
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.bot_ws 模块
-=====================================
+==================================
 
 .. automodule:: nonebot.adapters.mirai.bot_ws
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.config 模块
-=====================================
+==================================
 
 .. automodule:: nonebot.adapters.mirai.config
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.message 模块
-====================================
+===================================
 
 .. automodule:: nonebot.adapters.mirai.message
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.event 模块
-====================================
+=================================
 
 .. automodule:: nonebot.adapters.mirai.event
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.event.base 模块
-====================================
+======================================
 
 .. automodule:: nonebot.adapters.mirai.event.base
    :members:
    :show-inheritance:
 
+NoneBot.adapters.mirai.event.meta 模块
+======================================
+
+.. automodule:: nonebot.adapters.mirai.event.meta
+   :members:
+   :show-inheritance:
+
 NoneBot.adapters.mirai.event.message 模块
-====================================
+=========================================
 
 .. automodule:: nonebot.adapters.mirai.event.message
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.event.notice 模块
-====================================
+=========================================
 
 .. automodule:: nonebot.adapters.mirai.event.notice
    :members:
    :show-inheritance:
 
 NoneBot.adapters.mirai.event.request 模块
-====================================
+=========================================
 
 .. automodule:: nonebot.adapters.mirai.event.request
    :members:

nonebot/adapters/mirai/bot.py

@@ -118,6 +118,9 @@ class SessionManager:
 
 
 class MiraiBot(BaseBot):
+    """
+    mirai-api-http 协议 Bot 适配。
+    """
 
     @overrides(BaseBot)
     def __init__(self,
@@ -663,10 +666,6 @@ class MiraiBot(BaseBot):
           * ``target: int``: 指定群的群号
           * ``member_id: int``: 群员QQ号
           * ``info: Dict[str, Any]``: 群员资料, 格式见 ``member_info`` 的返回值
-
-        :返回:
-
-          - ``[type]``: [description]
         """
         return await self.api.post('memberInfo',
                                    params={

nonebot/adapters/mirai/bot_ws.py

@@ -89,6 +89,9 @@ class WebSocket(BaseWebSocket):
 
 
 class MiraiWebsocketBot(MiraiBot):
+    """
+    mirai-api-http 正向 Websocket 协议 Bot 适配。
+    """
 
     @overrides(MiraiBot)
     def __init__(self, connection_type: str, self_id: str, *,

nonebot/adapters/mirai/event/__init__.py

@@ -1,4 +1,4 @@
-from .base import Event, SenderInfo, PrivateSenderInfo, SenderGroup
+from .base import Event, GroupChatInfo, GroupInfo, UserPermission, PrivateChatInfo
 from .message import *
 from .notice import *
 from .request import *

nonebot/adapters/mirai/event/base.py

@@ -11,37 +11,53 @@ from nonebot.log import logger
 from nonebot.typing import overrides
 
 
-class SenderPermission(str, Enum):
+class UserPermission(str, Enum):
+    """
+    用户权限枚举类
+    
+      - ``OWNER``: 群主
+      - ``ADMINISTRATOR``: 群管理
+      - ``MEMBER``: 普通群成员
+    """
     OWNER = 'OWNER'
     ADMINISTRATOR = 'ADMINISTRATOR'
     MEMBER = 'MEMBER'
 
 
-class SenderGroup(BaseModel):
+class GroupInfo(BaseModel):
     id: int
     name: str
-    permission: SenderPermission
+    permission: UserPermission
 
 
-class SenderInfo(BaseModel):
+class GroupChatInfo(BaseModel):
     id: int
     name: str = Field(alias='memberName')
-    permission: SenderPermission
-    group: SenderGroup
+    permission: UserPermission
+    group: GroupInfo
 
 
-class PrivateSenderInfo(BaseModel):
+class PrivateChatInfo(BaseModel):
     id: int
     nickname: str
     remark: str
 
 
 class Event(BaseEvent):
+    """
+    mirai-api-http 协议事件，字段与 mirai-api-http 一致。各事件字段参考 `mirai-api-http 文档`_
+
+    .. _mirai-api-http 文档:
+        https://github.com/project-mirai/mirai-api-http/blob/master/docs/EventType.md
+    """
     self_id: int
     type: str
 
     @classmethod
     def new(cls, data: Dict[str, Any]) -> "Event":
+        """
+        此事件类的工厂函数, 能够通过事件数据选择合适的子类进行序列化
+        """
         type = data['type']
 
         def all_subclasses(cls: Type[Event]):
@@ -70,7 +86,7 @@ class Event(BaseEvent):
 
     @overrides(BaseEvent)
     def get_type(self) -> Literal["message", "notice", "request", "meta_event"]:
-        from . import message, notice, request
+        from . import message, notice, request, meta
         if isinstance(self, message.MessageEvent):
             return 'message'
         elif isinstance(self, notice.NoticeEvent):
@@ -109,4 +125,7 @@ class Event(BaseEvent):
         return False
 
     def normalize_dict(self, **kwargs) -> Dict[str, Any]:
+        """
+        返回可以被json正常反序列化的结构体
+        """
         return json.loads(self.json(**kwargs))

nonebot/adapters/mirai/event/message.py

@@ -5,10 +5,11 @@ from pydantic import Field
 from nonebot.typing import overrides
 
 from ..message import MessageChain
-from .base import Event, PrivateSenderInfo, SenderInfo
+from .base import Event, GroupChatInfo, PrivateChatInfo
 
 
 class MessageEvent(Event):
+    """消息事件基类"""
     message_chain: MessageChain = Field(alias='messageChain')
     sender: Any
 
@@ -30,7 +31,8 @@ class MessageEvent(Event):
 
 
 class GroupMessage(MessageEvent):
-    sender: SenderInfo
+    """群消息事件"""
+    sender: GroupChatInfo
 
     @overrides(MessageEvent)
     def get_session_id(self) -> str:
@@ -38,7 +40,8 @@ class GroupMessage(MessageEvent):
 
 
 class FriendMessage(MessageEvent):
-    sender: PrivateSenderInfo
+    """好友消息事件"""
+    sender: PrivateChatInfo
 
     @overrides(MessageEvent)
     def get_user_id(self) -> str:
@@ -50,7 +53,8 @@ class FriendMessage(MessageEvent):
 
 
 class TempMessage(MessageEvent):
-    sender: SenderInfo
+    """临时会话消息事件"""
+    sender: GroupChatInfo
 
     @overrides
     def get_session_id(self) -> str:

nonebot/adapters/mirai/event/meta.py

@@ -0,0 +1,31 @@
+from .base import Event
+
+
+class MetaEvent(Event):
+    """元事件基类"""
+    qq: int
+
+
+class BotOnlineEvent(MetaEvent):
+    """Bot登录成功"""
+    pass
+
+
+class BotOfflineEventActive(MetaEvent):
+    """Bot主动离线"""
+    pass
+
+
+class BotOfflineEventForce(MetaEvent):
+    """Bot被挤下线"""
+    pass
+
+
+class BotOfflineEventDropped(MetaEvent):
+    """Bot被服务器断开或因网络问题而掉线"""
+    pass
+
+
+class BotReloginEvent(MetaEvent):
+    """Bot主动重新登录"""
+    pass

nonebot/adapters/mirai/event/notice.py

@@ -2,61 +2,74 @@ from typing import Any, Optional
 
 from pydantic import Field
 
-from .base import Event, SenderGroup, SenderInfo, SenderPermission
+from .base import Event, GroupChatInfo, GroupInfo, UserPermission
 
 
 class NoticeEvent(Event):
+    """通知事件基类"""
     pass
 
 
 class MuteEvent(NoticeEvent):
-    operator: SenderInfo
+    """禁言类事件基类"""
+    operator: GroupChatInfo
 
 
 class BotMuteEvent(MuteEvent):
+    """Bot被禁言"""
     pass
 
 
 class BotUnmuteEvent(MuteEvent):
+    """Bot被取消禁言"""
     pass
 
 
 class MemberMuteEvent(MuteEvent):
+    """群成员被禁言事件（该成员不是Bot）"""
     duration_seconds: int = Field(alias='durationSeconds')
-    member: SenderInfo
-    operator: Optional[SenderInfo] = None
+    member: GroupChatInfo
+    operator: Optional[GroupChatInfo] = None
 
 
 class MemberUnmuteEvent(MuteEvent):
-    member: SenderInfo
-    operator: Optional[SenderInfo] = None
+    """群成员被取消禁言事件（该成员不是Bot）"""
+    member: GroupChatInfo
+    operator: Optional[GroupChatInfo] = None
 
 
 class BotJoinGroupEvent(NoticeEvent):
-    group: SenderGroup
+    """Bot加入了一个新群"""
+    group: GroupInfo
 
 
 class BotLeaveEventActive(BotJoinGroupEvent):
+    """Bot主动退出一个群"""
     pass
 
 
 class BotLeaveEventKick(BotJoinGroupEvent):
+    """Bot被踢出一个群"""
     pass
 
 
 class MemberJoinEvent(NoticeEvent):
-    member: SenderInfo
-
-
-class MemberLeaveEventQuit(MemberJoinEvent):
-    pass
+    """新人入群的事件"""
+    member: GroupChatInfo
 
 
 class MemberLeaveEventKick(MemberJoinEvent):
-    operator: Optional[SenderInfo] = None
+    """成员被踢出群（该成员不是Bot）"""
+    operator: Optional[GroupChatInfo] = None
+
+
+class MemberLeaveEventQuit(MemberJoinEvent):
+    """成员主动离群（该成员不是Bot）"""
+    pass
 
 
 class FriendRecallEvent(NoticeEvent):
+    """好友消息撤回"""
     author_id: int = Field(alias='authorId')
     message_id: int = Field(alias='messageId')
     time: int
@@ -64,67 +77,80 @@ class FriendRecallEvent(NoticeEvent):
 
 
 class GroupRecallEvent(FriendRecallEvent):
-    group: SenderGroup
-    operator: Optional[SenderInfo] = None
+    """群消息撤回"""
+    group: GroupInfo
+    operator: Optional[GroupChatInfo] = None
 
 
 class GroupStateChangeEvent(NoticeEvent):
+    """群变化事件基类"""
     origin: Any
     current: Any
-    group: SenderGroup
-    operator: Optional[SenderInfo] = None
+    group: GroupInfo
+    operator: Optional[GroupChatInfo] = None
 
 
 class GroupNameChangeEvent(GroupStateChangeEvent):
+    """某个群名改变"""
     origin: str
     current: str
 
 
 class GroupEntranceAnnouncementChangeEvent(GroupStateChangeEvent):
+    """某群入群公告改变"""
     origin: str
     current: str
 
 
 class GroupMuteAllEvent(GroupStateChangeEvent):
+    """全员禁言"""
     origin: bool
     current: bool
 
 
 class GroupAllowAnonymousChatEvent(GroupStateChangeEvent):
+    """匿名聊天"""
     origin: bool
     current: bool
 
 
 class GroupAllowConfessTalkEvent(GroupStateChangeEvent):
+    """坦白说"""
     origin: bool
     current: bool
 
 
 class GroupAllowMemberInviteEvent(GroupStateChangeEvent):
+    """允许群员邀请好友加群"""
     origin: bool
     current: bool
 
 
 class MemberStateChangeEvent(NoticeEvent):
-    member: SenderInfo
-    operator: Optional[SenderInfo] = None
+    """群成员变化事件基类"""
+    member: GroupChatInfo
+    operator: Optional[GroupChatInfo] = None
 
 
 class MemberCardChangeEvent(MemberStateChangeEvent):
+    """群名片改动"""
     origin: str
     current: str
 
 
 class MemberSpecialTitleChangeEvent(MemberStateChangeEvent):
+    """群头衔改动（只有群主有操作限权）"""
     origin: str
     current: str
 
 
 class BotGroupPermissionChangeEvent(MemberStateChangeEvent):
-    origin: SenderPermission
-    current: SenderPermission
+    """Bot在群里的权限被改变"""
+    origin: UserPermission
+    current: UserPermission
 
 
 class MemberPermissionChangeEvent(MemberStateChangeEvent):
-    origin: SenderPermission
-    current: SenderPermission
+    """成员权限改变的事件（该成员不是Bot）"""
+    origin: UserPermission
+    current: UserPermission

nonebot/adapters/mirai/event/request.py

@@ -1,7 +1,7 @@
 from typing import TYPE_CHECKING
-from typing_extensions import Literal
 
 from pydantic import Field
+from typing_extensions import Literal
 
 from .base import Event
 
@@ -10,12 +10,14 @@ if TYPE_CHECKING:
 
 
 class RequestEvent(Event):
+    """请求事件基类"""
     event_id: int = Field(alias='eventId')
     message: str
     nick: str
 
 
 class NewFriendRequestEvent(RequestEvent):
+    """添加好友申请"""
     from_id: int = Field(alias='fromId')
     group_id: int = Field(0, alias='groupId')
 
@@ -70,6 +72,7 @@ class NewFriendRequestEvent(RequestEvent):
 
 
 class MemberJoinRequestEvent(RequestEvent):
+    """用户入群申请（Bot需要有管理员权限）"""
     from_id: int = Field(alias='fromId')
     group_id: int = Field(alias='groupId')
     group_name: str = Field(alias='groupName')
@@ -123,6 +126,7 @@ class MemberJoinRequestEvent(RequestEvent):
 
 
 class BotInvitedJoinGroupRequestEvent(RequestEvent):
+    """Bot被邀请入群申请"""
     from_id: int = Field(alias='fromId')
     group_id: int = Field(alias='groupId')
     group_name: str = Field(alias='groupName')