From 7c9cbe7b58b4017c4b60ff327ee3904fd799744a Mon Sep 17 00:00:00 2001 From: Mix Date: Mon, 1 Feb 2021 00:01:31 +0800 Subject: [PATCH] :speech_balloon: :bulb: rename some dataclass, add comments for events in mirai adapter --- docs_build/adapters/mirai.rst | 25 +++++--- nonebot/adapters/mirai/bot.py | 7 +-- nonebot/adapters/mirai/bot_ws.py | 3 + nonebot/adapters/mirai/event/__init__.py | 2 +- nonebot/adapters/mirai/event/base.py | 35 +++++++++--- nonebot/adapters/mirai/event/message.py | 12 ++-- nonebot/adapters/mirai/event/meta.py | 31 ++++++++++ nonebot/adapters/mirai/event/notice.py | 72 ++++++++++++++++-------- nonebot/adapters/mirai/event/request.py | 6 +- 9 files changed, 143 insertions(+), 50 deletions(-) create mode 100644 nonebot/adapters/mirai/event/meta.py diff --git a/docs_build/adapters/mirai.rst b/docs_build/adapters/mirai.rst index 1f6e3eaf..6f15695b 100644 --- a/docs_build/adapters/mirai.rst +++ b/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: diff --git a/nonebot/adapters/mirai/bot.py b/nonebot/adapters/mirai/bot.py index 81c7f7b7..ee718997 100644 --- a/nonebot/adapters/mirai/bot.py +++ b/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={ diff --git a/nonebot/adapters/mirai/bot_ws.py b/nonebot/adapters/mirai/bot_ws.py index d20d81dd..560534b6 100644 --- a/nonebot/adapters/mirai/bot_ws.py +++ b/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, *, diff --git a/nonebot/adapters/mirai/event/__init__.py b/nonebot/adapters/mirai/event/__init__.py index 903f4eb8..8b96ecca 100644 --- a/nonebot/adapters/mirai/event/__init__.py +++ b/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 * \ No newline at end of file diff --git a/nonebot/adapters/mirai/event/base.py b/nonebot/adapters/mirai/event/base.py index 3b6916f5..5b1cf7fc 100644 --- a/nonebot/adapters/mirai/event/base.py +++ b/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)) diff --git a/nonebot/adapters/mirai/event/message.py b/nonebot/adapters/mirai/event/message.py index 10574d5e..6021ea64 100644 --- a/nonebot/adapters/mirai/event/message.py +++ b/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: diff --git a/nonebot/adapters/mirai/event/meta.py b/nonebot/adapters/mirai/event/meta.py new file mode 100644 index 00000000..e42baf72 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/nonebot/adapters/mirai/event/notice.py b/nonebot/adapters/mirai/event/notice.py index b758d9c5..276b12d1 100644 --- a/nonebot/adapters/mirai/event/notice.py +++ b/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 diff --git a/nonebot/adapters/mirai/event/request.py b/nonebot/adapters/mirai/event/request.py index 39c64298..cea13aae 100644 --- a/nonebot/adapters/mirai/event/request.py +++ b/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')