Merge branch 'dev' into plugins

models/events/base.py

@@ -1,7 +1,8 @@
 """
 基础事件模型模块
 
-定义了所有 OneBot 11 事件的基类和事件类型枚举。
+该模块定义了所有 OneBot v11 事件模型的基类 `OneBotEvent` 和
+事件类型常量 `EventType`。所有具体的事件模型都应继承自 `OneBotEvent`。
 """
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Optional
@@ -13,46 +14,60 @@ if TYPE_CHECKING:
 
 class EventType:
     """
-    事件类型枚举
+    OneBot v11 事件类型常量。
+
+    用于标识不同种类的事件上报。
     """
-    META = 'meta_event'      # 元事件
-    REQUEST = 'request'      # 请求事件
-    NOTICE = 'notice'        # 通知事件
-    MESSAGE = 'message'      # 消息事件
-    MESSAGE_SENT = 'message_sent'  # 消息发送事件
+    META = 'meta_event'
+    """元事件 (meta_event): 如心跳、生命周期等。"""
+    REQUEST = 'request'
+    """请求事件 (request): 如加好友请求、加群请求等。"""
+    NOTICE = 'notice'
+    """通知事件 (notice): 如群成员增加、文件上传等。"""
+    MESSAGE = 'message'
+    """消息事件 (message): 如私聊消息、群消息等。"""
+    MESSAGE_SENT = 'message_sent'
+    """消息发送事件 (message_sent): 机器人自己发送消息的上报。"""
 
 
-@dataclass
+@dataclass(slots=True)
 class OneBotEvent(ABC):
     """
-    OneBot 事件基类
-    所有具体的事件类型都应该继承自此类
+    OneBot v11 事件的抽象基类。
+
+    所有具体的事件模型都必须继承此类，并实现 `post_type` 属性。
+
+    Attributes:
+        time (int): 事件发生的时间戳 (秒)。
+        self_id (int): 收到事件的机器人 QQ 号。
+        _bot (Optional[Bot]): 内部持有的 Bot 实例引用，用于快捷 API 调用。
     """
 
     time: int
-    """事件发生的时间戳"""
-
     self_id: int
-    """收到事件的机器人 QQ 号"""
-
     _bot: Optional["Bot"] = field(default=None, init=False)
-    """Bot 实例引用，用于快捷调用 API"""
 
     @property
     @abstractmethod
     def post_type(self) -> str:
         """
-        上报类型
+        抽象属性，代表事件的上报类型。
+
+        子类必须重写此属性，并返回对应的 `EventType` 常量值。
+        例如: `return EventType.MESSAGE`
         """
         pass
 
     @property
     def bot(self) -> "Bot":
         """
-        获取 Bot 实例
+        获取与此事件关联的 `Bot` 实例，以便快捷调用 API。
 
-        :return: Bot 实例
-        :raises ValueError: 如果 Bot 实例未设置
+        Returns:
+            Bot: 当前事件所对应的 `Bot` 实例。
+
+        Raises:
+            ValueError: 如果 `Bot` 实例尚未被设置到事件对象中。
         """
         if self._bot is None:
             raise ValueError("Bot instance not set for this event")
@@ -61,8 +76,10 @@ class OneBotEvent(ABC):
     @bot.setter
     def bot(self, value: "Bot"):
         """
-        设置 Bot 实例
+        为事件对象设置关联的 `Bot` 实例。
 
-        :param value: Bot 实例
+        Args:
+            value (Bot): 要设置的 `Bot` 实例。
         """
         self._bot = value
+

models/events/message.py

@@ -11,7 +11,7 @@ from models.sender import Sender
 from .base import OneBotEvent, EventType
 
 
-@dataclass
+@dataclass(slots=True)
 class Anonymous:
     """
     匿名信息

models/events/meta.py

@@ -8,7 +8,7 @@ from typing import Optional
 from .base import OneBotEvent, EventType
 
 
-@dataclass
+@dataclass(slots=True)
 class HeartbeatStatus:
     """
     心跳状态接口

models/events/notice.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass, field
 from .base import OneBotEvent, EventType
 
 
-@dataclass
+@dataclass(slots=True)
 class NoticeEvent(OneBotEvent):
     """
     通知事件基类

models/events/request.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass
 from .base import OneBotEvent, EventType
 
 
-@dataclass
+@dataclass(slots=True)
 class RequestEvent(OneBotEvent):
     """
     请求事件基类

models/message.py

@@ -1,49 +1,57 @@
 """
 消息段模型模块
 
-定义了 MessageSegment 类，用于封装 OneBot 11 的消息段。
+该模块定义了 `MessageSegment` 类，用于构建和表示 OneBot v11 协议中的消息段。
+通过此类，可以方便地创建文本、图片、At 等不同类型的消息内容，并支持链式操作。
 """
 
 from dataclasses import dataclass
 from typing import Any, Dict
 
 
-@dataclass
+@dataclass(slots=True)
 class MessageSegment:
     """
-    消息段，对应 OneBot 11 标准中的消息段对象
+    表示一个 OneBot v11 消息段。
+
+    Attributes:
+        type (str): 消息段的类型，例如 'text', 'image', 'at'。
+        data (Dict[str, Any]): 消息段的具体数据，是一个键值对字典。
     """
 
     type: str
-    """消息段类型，如 text, image, at 等"""
-
     data: Dict[str, Any]
-    """消息段数据"""
 
     @property
     def text(self) -> str:
         """
-        获取文本内容（仅当 type 为 text 时有效）
+        当消息段类型为 'text' 时，快速获取其文本内容。
 
-        :return: 文本内容
+        Returns:
+            str: 消息段的文本内容。如果类型不是 'text'，则返回空字符串。
         """
         return self.data.get("text", "") if self.type == "text" else ""
 
     @property
     def image_url(self) -> str:
         """
-        获取图片 URL（仅当 type 为 image 时有效）
+        当消息段类型为 'image' 时，快速获取其图片 URL。
 
-        :return: 图片 URL
+        Returns:
+            str: 图片的 URL。如果类型不是 'image' 或数据中不含 'url'，则返回空字符串。
         """
         return self.data.get("url", "") if self.type == "image" else ""
 
     def is_at(self, user_id: int = None) -> bool:
         """
-        判断是否为 @某人
+        检查当前消息段是否是一个 'at' (提及) 消息段。
 
-        :param user_id: 指定的 QQ 号，如果为 None 则只判断是否为 at 类型
-        :return: 是否匹配
+        Args:
+            user_id (int, optional): 如果提供，则进一步检查被提及的 QQ 号是否匹配。
+                                     Defaults to None.
+
+        Returns:
+            bool: 如果消息段是 'at' 类型且 user_id 匹配 (如果提供)，则返回 True。
         """
         if self.type != "at":
             return False
@@ -52,6 +60,9 @@ class MessageSegment:
         return str(self.data.get("qq")) == str(user_id)
 
     def __repr__(self):
+        """
+        返回消息段对象的字符串表示形式，便于调试。
+        """
         return f"[MS:{self.type}:{self.data}]"
 
     # --- 快捷构造方法 ---
@@ -59,39 +70,52 @@ class MessageSegment:
     @staticmethod
     def text(text: str) -> "MessageSegment":  # noqa: F811
         """
-        构造文本消息段
+        创建一个文本消息段。
 
-        :param text: 文本内容
-        :return: MessageSegment 对象
+        Args:
+            text (str): 文本内容。
+
+        Returns:
+            MessageSegment: 一个类型为 'text' 的消息段对象。
         """
         return MessageSegment(type="text", data={"text": text})
 
     @staticmethod
     def at(user_id: int | str) -> "MessageSegment":
         """
-        构造 @某人 消息段
+        创建一个 @某人 的消息段。
 
-        :param user_id: 目标 QQ 号，"all" 表示 @全体成员
-        :return: MessageSegment 对象
+        Args:
+            user_id (int | str): 要提及的 QQ 号。若为 "all"，则表示 @全体成员。
+
+        Returns:
+            MessageSegment: 一个类型为 'at' 的消息段对象。
         """
         return MessageSegment(type="at", data={"qq": str(user_id)})
 
     @staticmethod
     def image(file: str) -> "MessageSegment":
         """
-        构造图片消息段
+        创建一个图片消息段。
 
-        :param file: 图片文件名、URL 或 Base64
-        :return: MessageSegment 对象
+        Args:
+            file (str): 图片的路径、URL 或 Base64 编码的字符串。
+
+        Returns:
+            MessageSegment: 一个类型为 'image' 的消息段对象。
         """
         return MessageSegment(type="image", data={"file": file})
 
     @staticmethod
     def face(id: int) -> "MessageSegment":
         """
-        构造表情消息段
+        创建一个 QQ 表情消息段。
 
-        :param id: 表情 ID
-        :return: MessageSegment 对象
+        Args:
+            id (int): QQ 表情的 ID。
+
+        Returns:
+            MessageSegment: 一个类型为 'face' 的消息段对象。
         """
         return MessageSegment(type="face", data={"id": str(id)})
+

models/objects.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass, field
 from typing import List, Optional
 
 
-@dataclass
+@dataclass(slots=True)
 class GroupInfo:
     """
     群信息

models/sender.py

@@ -7,7 +7,7 @@ from dataclasses import dataclass
 from typing import Optional
 
 
-@dataclass
+@dataclass(slots=True)
 class Sender:
     """
     发送者信息类，对应 OneBot 11 标准中的 sender 字段