ErisPulse 2.4.2.dev0__tar.gz → 2.4.2.dev1__tar.gz

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.4.2.dev0
+Version: 2.4.2.dev1
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: ErisDev <erisdev@88.com>
 Maintainer-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ErisPulse"
-version = "2.4.2-dev.0"
+version = "2.4.2-dev.1"
 description = "ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。"
 readme = "README.md"
 requires-python = ">=3.10"

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/src/ErisPulse/Core/adapter.py

@@ -51,6 +51,9 @@ class AdapterManager(ManagerBase):
         # Bot状态存储 - {platform: {bot_id: {"status": str, "last_active": float, "info": dict}}}
         self._bots: dict[str, dict[str, dict]] = {}
 
+        # 标记是否正在关闭，避免重复提交离线事件
+        self._is_being_shutdown = False
+
     def set_sdk_ref(self, sdk) -> bool:
         """
         设置 SDK 引用
@@ -287,127 +290,134 @@ class AdapterManager(ManagerBase):
         >>> # 关闭多个适配器
         >>> await adapter.shutdown(["Platform1", "Platform2"])
         """
-        if platforms is None:
-            platforms = list(self._adapters.keys())
-        if not isinstance(platforms, list):
-            platforms = [platforms]
-        for platform in platforms:
-            if platform not in self._adapters:
-                raise ValueError(f"平台 {platform} 未注册")
-
-        logger.info(f"关闭适配器 {platforms}")
-
-        # 提交适配器关闭开始事件
-        await lifecycle.submit_event(
-            "adapter.stop", msg="开始关闭适配器", data={"platforms": platforms}
-        )
-
-        from .router import router
-
-        # 需要收集受影响的 adapter 实例（因为多个平台可能共享同一个实例）
-        affected_adapters = set()
-        bots_to_offline = []  # [(platform, bot_id), ...]
+        # 设置关闭标志，避免重复提交离线事件
+        self._is_being_shutdown = True
 
-        # 取消目标平台的后台启动任务
-        for platform in platforms:
-            task = self._adapter_tasks.pop(platform, None)
-            if task and not task.done():
-                task.cancel()
-                logger.debug(f"已取消平台 {platform} 的后台启动任务")
-
-        for platform in platforms:
-            adapter_instance = self._adapters[platform]
-            affected_adapters.add(adapter_instance)
-
-            # 收集该平台下需要标记为离线的 Bot
-            if platform in self._bots:
-                for bot_id, bot_info in self._bots[platform].items():
-                    if bot_info.get("status") != "offline":
-                        bots_to_offline.append((platform, bot_id))
+        try:
+            if platforms is None:
+                platforms = list(self._adapters.keys())
+            if not isinstance(platforms, list):
+                platforms = [platforms]
+            for platform in platforms:
+                if platform not in self._adapters:
+                    raise ValueError(f"平台 {platform} 未注册")
 
-        # 对每个受影响的 adapter 实例执行 shutdown（如果尚未关闭）
-        for adapter_instance in affected_adapters:
-            if adapter_instance in self._started_instances:
-                # 找到该实例对应的平台名（用于事件提交）
-                instance_platforms = [
-                    p for p, a in self._adapters.items() if a is adapter_instance
-                ]
-                platform_label = (
-                    instance_platforms[0]
-                    if instance_platforms
-                    else str(id(adapter_instance))
-                )
+            logger.info(f"关闭适配器 {platforms}")
 
-                # 提交适配器状态变化事件（stopping）
-                for p in instance_platforms:
-                    if p in platforms:
-                        await lifecycle.submit_event(
-                            "adapter.status.change",
-                            msg=f"适配器 {p} 状态变化: stopping",
-                            data={"platform": p, "status": "stopping"},
-                        )
+            # 提交适配器关闭开始事件
+            await lifecycle.submit_event(
+                "adapter.stop", msg="开始关闭适配器", data={"platforms": platforms}
+            )
 
-                try:
-                    await adapter_instance.shutdown()
-                    self._started_instances.remove(adapter_instance)
+            from .router import router
+
+            # 需要收集受影响的 adapter 实例（因为多个平台可能共享同一个实例）
+            affected_adapters = set()
+            bots_to_offline = []  # [(platform, bot_id), ...]
+
+            # 取消目标平台的后台启动任务
+            for platform in platforms:
+                task = self._adapter_tasks.pop(platform, None)
+                if task and not task.done():
+                    task.cancel()
+                    logger.debug(f"已取消平台 {platform} 的后台启动任务")
+
+            for platform in platforms:
+                adapter_instance = self._adapters[platform]
+                affected_adapters.add(adapter_instance)
+
+                # 收集该平台下需要标记为离线的 Bot
+                if platform in self._bots:
+                    for bot_id, bot_info in self._bots[platform].items():
+                        if bot_info.get("status") != "offline":
+                            bots_to_offline.append((platform, bot_id))
+
+            # 对每个受影响的 adapter 实例执行 shutdown（如果尚未关闭）
+            for adapter_instance in affected_adapters:
+                if adapter_instance in self._started_instances:
+                    # 找到该实例对应的平台名（用于事件提交）
+                    instance_platforms = [
+                        p for p, a in self._adapters.items() if a is adapter_instance
+                    ]
+                    platform_label = (
+                        instance_platforms[0]
+                        if instance_platforms
+                        else str(id(adapter_instance))
+                    )
 
-                    # 提交适配器状态变化事件（stopped）
+                    # 提交适配器状态变化事件（stopping）
                     for p in instance_platforms:
                         if p in platforms:
                             await lifecycle.submit_event(
                                 "adapter.status.change",
-                                msg=f"适配器 {p} 状态变化: stopped",
-                                data={"platform": p, "status": "stopped"},
+                                msg=f"适配器 {p} 状态变化: stopping",
+                                data={"platform": p, "status": "stopping"},
                             )
-                except Exception as e:
-                    logger.error(f"关闭适配器实例 {id(adapter_instance)} 失败: {e}")
 
-                    # 提交适配器状态变化事件（stop_failed）
-                    for p in instance_platforms:
-                        if p in platforms:
-                            await lifecycle.submit_event(
-                                "adapter.status.change",
-                                msg=f"适配器 {p} 状态变化: stop_failed",
-                                data={
-                                    "platform": p,
-                                    "status": "stop_failed",
-                                    "error": str(e),
-                                },
-                            )
+                    try:
+                        await adapter_instance.shutdown()
+                        self._started_instances.remove(adapter_instance)
+
+                        # 提交适配器状态变化事件（stopped）
+                        for p in instance_platforms:
+                            if p in platforms:
+                                await lifecycle.submit_event(
+                                    "adapter.status.change",
+                                    msg=f"适配器 {p} 状态变化: stopped",
+                                    data={"platform": p, "status": "stopped"},
+                                )
+                    except Exception as e:
+                        logger.error(f"关闭适配器实例 {id(adapter_instance)} 失败: {e}")
+
+                        # 提交适配器状态变化事件（stop_failed）
+                        for p in instance_platforms:
+                            if p in platforms:
+                                await lifecycle.submit_event(
+                                    "adapter.status.change",
+                                    msg=f"适配器 {p} 状态变化: stop_failed",
+                                    data={
+                                        "platform": p,
+                                        "status": "stop_failed",
+                                        "error": str(e),
+                                    },
+                                )
+
+            # 清理被关闭平台的路由
+            for platform in platforms:
+                result = router.unregister_all_by_namespace(platform)
+                if result["http_count"] > 0 or result["websocket_count"] > 0:
+                    logger.debug(
+                        f"已清理平台 {platform} 的路由: HTTP={result['http_count']}, WebSocket={result['websocket_count']}"
+                    )
 
-        # 清理被关闭平台的路由
-        for platform in platforms:
-            result = router.unregister_all_by_namespace(platform)
-            if result["http_count"] > 0 or result["websocket_count"] > 0:
-                logger.debug(
-                    f"已清理平台 {platform} 的路由: HTTP={result['http_count']}, WebSocket={result['websocket_count']}"
-                )
+            # 停止路由器（仅当所有适配器都关闭时）
+            if not self._started_instances:
+                await router.stop()
 
-        # 停止路由器（仅当所有适配器都关闭时）
-        if not self._started_instances:
-            await router.stop()
-
-        # 将相关 Bot 标记为离线
-        for platform, bot_id in bots_to_offline:
-            if platform in self._bots and bot_id in self._bots[platform]:
-                self._bots[platform][bot_id]["status"] = "offline"
-                # 提交 Bot 离线事件
-                await lifecycle.submit_event(
-                    "adapter.bot.offline",
-                    msg=f"Bot {platform}/{bot_id} 离线",
-                    data={"platform": platform, "bot_id": bot_id, "status": "offline"},
-                )
+            # 将相关 Bot 标记为离线
+            for platform, bot_id in bots_to_offline:
+                if platform in self._bots and bot_id in self._bots[platform]:
+                    self._bots[platform][bot_id]["status"] = "offline"
+                    # 提交 Bot 离线事件
+                    await lifecycle.submit_event(
+                        "adapter.bot.offline",
+                        msg=f"Bot {platform}/{bot_id} 离线",
+                        data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+                    )
 
-        # 如果所有适配器都关闭了，清理事件处理器
-        if not self._started_instances:
-            self._onebot_handlers.clear()
-            self._raw_handlers.clear()
-            self._onebot_middlewares.clear()
+            # 如果所有适配器都关闭了，清理事件处理器
+            if not self._started_instances:
+                self._onebot_handlers.clear()
+                self._raw_handlers.clear()
+                self._onebot_middlewares.clear()
 
-        # 提交适配器关闭完成事件
-        await lifecycle.submit_event(
-            "adapter.stopped", msg="适配器关闭完成", data={"platforms": platforms}
-        )
+            # 提交适配器关闭完成事件
+            await lifecycle.submit_event(
+                "adapter.stopped", msg="适配器关闭完成", data={"platforms": platforms}
+            )
+        finally:
+            # 清除关闭标志
+            self._is_being_shutdown = False
 
     def clear(self) -> None:
         """
@@ -473,12 +483,11 @@ class AdapterManager(ManagerBase):
 
     def exists(self, platform: str) -> bool:
         """
-        检查平台是否存在
+        检查平台是否已注册
 
         :param platform: 平台名称
-        :return: [bool] 平台是否存在
+        :return: 平台是否已注册（即 adapter.register() 已被调用）
         """
-        # 检查平台是否已注册（在 _adapters 中）
         return platform in self._adapters
 
     def is_enabled(self, platform: str) -> bool:
@@ -486,20 +495,25 @@ class AdapterManager(ManagerBase):
         检查平台适配器是否启用
 
         :param platform: 平台名称
-        :return: [bool] 平台适配器是否启用
+        :return: 平台适配器是否启用
+
+        {!--< tips >!--}
+        适配器启用条件：
+        1. 适配器在配置文件中（ErisPulse.adapters.status.{platform} 存在）
+        2. 配置值为启用状态
+
+        如果适配器未在配置中，返回 False
+        {!--< /tips >!--}
         """
-        # 不使用默认值，如果配置不存在则返回 None
+        from .config import parse_bool_config
+
         status = config.getConfig(f"ErisPulse.adapters.status.{platform}")
 
-        # 如果状态不存在，说明是新适配器
+        # 适配器未在配置中，返回 False
         if status is None:
-            return False  # 新适配器默认不启用，需要在初始化时处理
-
-        # 处理字符串形式的布尔值
-        if isinstance(status, str):
-            return status.lower() not in ("false", "0", "no", "off")
+            return False
 
-        return bool(status)
+        return parse_bool_config(status)
 
     def enable(self, platform: str) -> bool:
         """
@@ -541,7 +555,7 @@ class AdapterManager(ManagerBase):
         :return: 是否取消成功
 
         {!--< internal-use >!--}
-        注意：此方法仅取消注册，不关闭已启动的适配器
+        注意: 此方法仅取消注册, 不关闭已启动的适配器
         {!--< /internal-use >!--}
         """
         if platform not in self._adapters:
@@ -837,13 +851,15 @@ class AdapterManager(ManagerBase):
                 )
 
         if status == "offline":
-            asyncio.ensure_future(
-                lifecycle.submit_event(
-                    "adapter.bot.offline",
-                    msg=f"Bot {platform}/{bot_id} 离线",
-                    data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+            # 只有在非主动关闭的情况下才提交事件（避免与 shutdown() 重复）
+            if not self._is_being_shutdown:
+                asyncio.ensure_future(
+                    lifecycle.submit_event(
+                        "adapter.bot.offline",
+                        msg=f"Bot {platform}/{bot_id} 离线",
+                        data={"platform": platform, "bot_id": bot_id, "status": "offline"},
+                    )
                 )
-            )
 
     def _update_bot_heartbeat(self, platform: str, self_info: dict) -> None:
         """

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/src/ErisPulse/Core/adapter.pyi

@@ -104,10 +104,10 @@ class AdapterManager(ManagerBase):
         ...
     def exists(self: object, platform: str) -> bool:
         """
-        检查平台是否存在
+        检查平台是否已注册
         
         :param platform: 平台名称
-        :return: [bool] 平台是否存在
+        :return: 平台是否已注册（即 adapter.register() 已被调用）
         """
         ...
     def is_enabled(self: object, platform: str) -> bool:
@@ -115,7 +115,15 @@ class AdapterManager(ManagerBase):
         检查平台适配器是否启用
         
         :param platform: 平台名称
-        :return: [bool] 平台适配器是否启用
+        :return: 平台适配器是否启用
+        
+        {!--< tips >!--}
+        适配器启用条件：
+        1. 适配器在配置文件中（ErisPulse.adapters.status.{platform} 存在）
+        2. 配置值为启用状态
+        
+        如果适配器未在配置中，返回 False
+        {!--< /tips >!--}
         """
         ...
     def enable(self: object, platform: str) -> bool:

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/src/ErisPulse/Core/config.py

@@ -24,8 +24,9 @@ class ConfigManager:
         self._cache_timestamp = 0  # 缓存时间戳
         self._cache_timeout = 60  # 缓存超时时间（秒）
         self._write_delay = 5  # 写入延迟（秒）
-        self._write_timer = None  # 写入定时器
+        self._write_timer: threading.Timer | None = None  # 写入定时器
         self._lock = threading.RLock()  # 线程安全锁
+        self._file_lock = threading.RLock()  # 文件操作锁，确保原子性
         self._migrate_config()  # 迁移旧配置文件
         self._load_config()  # 初始化时加载配置
 
@@ -138,56 +139,79 @@ class ConfigManager:
     def _flush_config(self) -> None:
         """
         将待写入的配置刷新到文件
+        
+        使用文件锁确保多线程环境下的原子性操作
         """
         with self._lock:
             if not self._dirty_keys:
                 return  # 没有需要写入的内容
 
-            try:
-                # 从文件读取完整配置
-                if os.path.exists(self.CONFIG_FILE):
-                    with open(self.CONFIG_FILE, "r", encoding="utf-8") as f:
-                        config = toml.load(f)
-                else:
-                    config = {}
-
-                # 应用待写入的更改
-                for key, value in self._dirty_keys.items():
-                    keys = key.split(".")
-                    current = config
-                    for k in keys[:-1]:
-                        if k not in current:
-                            current[k] = {}
-                        current = current[k]
-                    current[keys[-1]] = value
-
-                # 对配置字典进行排序，确保同一模块的配置项排列在一起
-                sorted_config = self._sort_config_dict(config)
-
-                # 写入文件
-                with open(self.CONFIG_FILE, "w", encoding="utf-8") as f:
-                    toml.dump(sorted_config, f)
-
-                # 更新缓存并清除待写入队列
-                self._cache = sorted_config
-                self._cache_timestamp = time.time()
-                self._dirty_keys.clear()
+            with self._file_lock:  # 确保文件操作原子性
+                try:
+                    # 从文件读取完整配置
+                    if os.path.exists(self.CONFIG_FILE):
+                        with open(self.CONFIG_FILE, "r", encoding="utf-8") as f:
+                            config = toml.load(f)
+                    else:
+                        config = {}
+
+                    # 应用待写入的更改
+                    for key, value in self._dirty_keys.items():
+                        keys = key.split(".")
+                        current = config
+                        for k in keys[:-1]:
+                            if k not in current:
+                                current[k] = {}
+                            current = current[k]
+                        current[keys[-1]] = value
+
+                    # 对配置字典进行排序，确保同一模块的配置项排列在一起
+                    sorted_config = self._sort_config_dict(config)
+
+                    # 写入临时文件，确保原子性
+                    temp_file = self.CONFIG_FILE + ".tmp"
+                    with open(temp_file, "w", encoding="utf-8") as f:
+                        toml.dump(sorted_config, f)
+
+                    # 原子性重命名（跨平台兼容）
+                    if os.name == 'nt':  # Windows
+                        if os.path.exists(self.CONFIG_FILE):
+                            os.replace(temp_file, self.CONFIG_FILE)
+                        else:
+                            os.rename(temp_file, self.CONFIG_FILE)
+                    else:  # Unix/Linux/macOS
+                        os.rename(temp_file, self.CONFIG_FILE)
+
+                    # 更新缓存并清除待写入队列
+                    self._cache = sorted_config
+                    self._cache_timestamp = time.time()
+                    self._dirty_keys.clear()
 
-            except Exception as e:
-                from .logger import logger
+                except Exception as e:
+                    from .logger import logger
 
-                logger.error(f"写入配置文件 {self.CONFIG_FILE} 失败: {e}")
+                    logger.error(f"写入配置文件 {self.CONFIG_FILE} 失败: {e}")
+                    # 清理临时文件
+                    temp_file = self.CONFIG_FILE + ".tmp"
+                    if os.path.exists(temp_file):
+                        try:
+                            os.remove(temp_file)
+                        except Exception:
+                            pass
 
     def _schedule_write(self) -> None:
         """
         安排延迟写入
+        
+        线程安全：使用锁保护 Timer 的取消和创建
         """
-        if self._write_timer:
-            self._write_timer.cancel()
+        with self._lock:
+            if self._write_timer:
+                self._write_timer.cancel()
 
-        self._write_timer = threading.Timer(self._write_delay, self._flush_config)
-        self._write_timer.daemon = True
-        self._write_timer.start()
+            self._write_timer = threading.Timer(self._write_delay, self._flush_config)
+            self._write_timer.daemon = True
+            self._write_timer.start()
 
     def _check_cache_validity(self) -> None:
         """
@@ -268,4 +292,30 @@ class ConfigManager:
 
 config: ConfigManager = ConfigManager()
 
-__all__ = ["config"]
+
+def parse_bool_config(value: Any) -> bool:
+    """
+    解析配置中的布尔值
+
+    :param value: 配置值（可以是 bool, int, str 等）
+    :return: 解析后的布尔值
+
+    支持的值：
+    - True: True, 1, "true", "True", "1", "yes", "Yes", "on", "On"
+    - False: False, 0, "false", "False", "0", "no", "No", "off", "Off"
+    """
+    if isinstance(value, bool):
+        return value
+
+    if isinstance(value, int):
+        return value != 0
+
+    if isinstance(value, str):
+        normalized = value.lower().strip()
+        return normalized in ("true", "1", "yes", "on")
+
+    # 其他类型尝试转换为布尔值
+    return bool(value)
+
+
+__all__ = ["config", "parse_bool_config"]

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/src/ErisPulse/Core/config.pyi

@@ -46,11 +46,15 @@ class ConfigManager:
     def _flush_config(self: object) -> None:
         """
         将待写入的配置刷新到文件
+        
+        使用文件锁确保多线程环境下的原子性操作
         """
         ...
     def _schedule_write(self: object) -> None:
         """
         安排延迟写入
+        
+        线程安全：使用锁保护 Timer 的取消和创建
         """
         ...
     def _check_cache_validity(self: object) -> None:
@@ -87,3 +91,16 @@ class ConfigManager:
         ...
 
 config: ConfigManager
+
+def parse_bool_config(value: Any) -> bool:
+    """
+    解析配置中的布尔值
+    
+    :param value: 配置值（可以是 bool, int, str 等）
+    :return: 解析后的布尔值
+    
+    支持的值：
+    - True: True, 1, "true", "True", "1", "yes", "Yes", "on", "On"
+    - False: False, 0, "false", "False", "0", "no", "No", "off", "Off"
+    """
+    ...

{erispulse-2.4.2.dev0 → erispulse-2.4.2.dev1}/src/ErisPulse/Core/module.py

@@ -272,15 +272,17 @@ class ModuleManager(ManagerBase):
 
     def exists(self, module_name: str) -> bool:
         """
-        检查模块是否存在（已注册或在配置中）
+        检查模块是否已注册
 
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否存在
+        :param module_name: 模块名称
+        :return: 模块是否已注册（即 module.register() 已被调用）
+
+        {!--< tips >!--}
+        exists() 只检查模块类是否已注册到管理器，用于验证模块是否可以加载。
+        如需检查模块是否启用，请使用 is_enabled()。
+        {!--< /tips >!--}
         """
-        if module_name in self._module_classes:
-            return True
-        module_statuses = config.getConfig("ErisPulse.modules.status", {})
-        return module_name in module_statuses
+        return module_name in self._module_classes
 
     def is_loaded(self, module_name: str) -> bool:
         """
@@ -350,9 +352,9 @@ class ModuleManager(ManagerBase):
         {!--< internal-use >!--}
         此方法仅供内部使用
 
-        :param module_name: [str] 模块名称
-        :param enabled: [bool] 是否启用模块 (默认: False)
-        :return: [bool] 操作是否成功
+        :param module_name: 模块名称
+        :param enabled: 是否启用模块 (默认: False)
+        :return: 操作是否成功
         """
         if self.exists(module_name):
             return True
@@ -367,18 +369,27 @@ class ModuleManager(ManagerBase):
         """
         检查模块是否启用
 
-        :param module_name: [str] 模块名称
-        :return: [bool] 模块是否启用
+        :param module_name: 模块名称
+        :return: 模块是否启用
+
+        {!--< tips >!--}
+        模块启用条件：
+        1. 模块在配置文件中（ErisPulse.modules.status.{module_name} 存在）
+        2. 配置值为启用状态
+
+        如果模块未在配置中，返回 False
+        {!--< /tips >!--}
         """
-        if (
-            status := config.getConfig(f"ErisPulse.modules.status.{module_name}")
-        ) is None:
-            return False
+        from .config import parse_bool_config
+
+        status = config.getConfig(f"ErisPulse.modules.status.{module_name}")
 
-        if isinstance(status, str):
-            return status.lower() not in ("false", "0", "no", "off")
+        # 模块未在配置中，返回 False
+        if status is None:
+            return False
 
-        return bool(status)
+        # 解析配置值
+        return parse_bool_config(status)
 
     def enable(self, module_name: str) -> bool:
         """