ErisPulse 1.1.14.dev1__py3-none-any.whl → 1.1.16__py3-none-any.whl

ErisPulse/logger.py

@@ -1,53 +1,123 @@
 """
 # 日志系统
 
-提供模块化、多级别的日志记录功能，支持内存存储和文件输出。
+提供模块化、多级别的日志记录功能，支持内存存储和文件输出。实现了模块级别的日志控制、彩色输出和灵活的存储选项。
 
 ## API 文档
-### 基本操作：
-    - debug(msg, *args, **kwargs):      调试信息
-    - info(msg, *args, **kwargs):       运行信息  
-    - warning(msg, *args, **kwargs):    警告信息
-    - error(msg, *args, **kwargs):      错误信息
-    - critical(msg, *args, **kwargs):   致命错误并终止程序
 
-### 日志控制：
-    - set_level(level):                     设置全局日志级别
-    - set_module_level(module_name, level): 设置模块日志级别
+### 基本日志操作
 
-### 日志存储：
-    - save_logs(path):          保存内存中的日志到文件
-    - set_output_file(path):    设置日志输出文件
+以debug为例：
+> 此外，还有其他级别的日志记录函数，如info, warning, error, critical等，用法相同。
 
-### 示例用法：
+debug(msg: str, *args, **kwargs) -> None
 
-```
-from ErisPulse import sdk
+记录调试级别的日志信息。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None
+- 示例:
 
-# 基本日志记录
-sdk.logger.debug("调试信息")
-sdk.logger.info("运行状态")
+```python
+sdk.logger.debug("这是一条日志")
+```
 
-# 模块级日志控制
-sdk.logger.set_module_level("MyModule", "DEBUG")
+### 日志级别控制
+#### set_level(level: str) -> None
+设置全局日志级别。
+- 参数:
+  - level: 日志级别，可选值为 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+- 返回:
+  - None
+- 示例:
+```python
+# 设置为调试级别
+sdk.logger.set_level("DEBUG")
+
+# 设置为生产环境级别
+sdk.logger.set_level("INFO")
+
+# 根据环境设置日志级别
+if is_production():
+    sdk.logger.set_level("WARNING")
+else:
+    sdk.logger.set_level("DEBUG")
+```
 
-# 异常捕获
-@sdk.logger.catch
-def risky_function():
-    raise Exception("出错了")
+#### set_module_level(module_name: str, level: str) -> bool
+设置特定模块的日志级别。
+- 参数:
+  - module_name: 模块名称
+  - level: 日志级别，可选值为 "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"
+- 返回:
+  - bool: 设置是否成功
+- 示例:
+```python
+# 为特定模块设置详细日志
+sdk.logger.set_module_level("NetworkModule", "DEBUG")
+
+# 为敏感模块设置更高级别
+sdk.logger.set_module_level("AuthModule", "WARNING")
+
+# 根据配置设置模块日志级别
+for module, level in config.get("logging", {}).items():
+    success = sdk.logger.set_module_level(module, level)
+    if not success:
+        print(f"无法为模块 {module} 设置日志级别 {level}")
 ```
 
-## 准备弃用
+### 日志存储和输出
+#### set_output_file(path: str | list) -> None
+设置日志输出文件。
+- 参数:
+  - path: 日志文件路径，可以是单个字符串或路径列表
+- 返回:
+  - None
+- 异常:
+  - 如果无法设置日志文件，会抛出异常
+- 示例:
+```python
+# 设置单个日志文件
+sdk.logger.set_output_file("app.log")
+
+# 设置多个日志文件
+sdk.logger.set_output_file(["app.log", "debug.log"])
+
+# 使用日期命名日志文件
+from datetime import datetime
+log_file = f"logs/app_{datetime.now().strftime('%Y%m%d')}.log"
+sdk.logger.set_output_file(log_file)
+```
 
-catch(func_or_level=None, level="error"): 异常捕获装饰器
-- 原因: 异常捕获功能已集成到 raiserr 模块中，建议使用 raiserr 进行异常处理。
+#### save_logs(path: str | list) -> None
+保存内存中的日志到文件。
+- 参数:
+  - path: 保存路径，可以是单个字符串或路径列表
+- 返回:
+  - None
+- 异常:
+  - 如果无法保存日志，会抛出异常
+- 示例:
+```python
+# 保存到单个文件
+sdk.logger.save_logs("saved_logs.txt")
+
+# 保存到多个文件
+sdk.logger.save_logs(["main_log.txt", "backup_log.txt"])
+
+# 在应用退出前保存日志
+import atexit
+atexit.register(lambda: sdk.logger.save_logs("final_logs.txt"))
+```
 
 """
 
 import logging
 import inspect
 import datetime
-import functools
 
 class Logger:
     def __init__(self):
@@ -117,34 +187,6 @@ class Logger:
                 self._logger.error(f"无法保存日志到 {p}: {e}。")
                 raise e
 
-    def catch(self, func_or_level=None, level="error"):
-        if isinstance(func_or_level, str):
-            return lambda func: self.catch(func, level=func_or_level)
-        if func_or_level is None:
-            return lambda func: self.catch(func, level=level)
-        func = func_or_level
-
-        @functools.wraps(func)
-        def wrapper(*args, **kwargs):
-            try:
-                return func(*args, **kwargs)
-            except Exception as e:
-                import traceback
-                error_info = traceback.format_exc()
-
-                module_name = func.__module__
-                if module_name == "__main__":
-                    module_name = "Main"
-                func_name = func.__name__
-
-                error_msg = f"Exception in {func_name}: {str(e)}\n{error_info}"
-
-                log_method = getattr(self, level, self.error)
-                log_method(error_msg)
-
-                return None
-        return wrapper
-
     def _save_in_memory(self, ModuleName, msg):
         if ModuleName not in self._logs:
             self._logs[ModuleName] = []
@@ -163,6 +205,8 @@ class Logger:
             module_name = "Main"
         if module_name.endswith(".Core"):
             module_name = module_name[:-5]
+        if module_name.startswith("ErisPulse"):
+            module_name = "ErisPulse"
         return module_name
 
     def debug(self, msg, *args, **kwargs):

ErisPulse/mods.py

@@ -1,37 +1,253 @@
 """
 # 模块管理系统
 
-提供模块的注册、状态管理和依赖解析功能。
+提供模块的注册、状态管理和依赖解析功能。支持模块信息存储、状态切换和批量操作。
 
 ## API 文档
-### 模块状态：
-    - set_module_status(module_name, status):   设置模块启用状态
-    - get_module_status(module_name):           获取模块状态
 
-### 模块信息：
-    - set_module(module_name, module_info): 设置模块信息
-    - get_module(module_name):              获取模块信息
-    - get_all_modules():                    获取所有模块信息
-    - remove_module(module_name):           删除模块
+### 模块状态管理
+#### set_module_status(module_name: str, status: bool) -> None
+设置模块的启用状态。
+- 参数:
+  - module_name: 模块名称
+  - status: 模块状态，True为启用，False为禁用
+- 返回:
+  - None
+- 示例:
+```python
+# 启用模块
+sdk.mods.set_module_status("MyModule", True)
 
-### 前缀管理：
-    - update_prefixes(module_prefix, status_prefix): 更新存储前缀
-    - module_prefix: 模块存储前缀属性
-    - status_prefix: 状态存储前缀属性
+# 禁用模块
+sdk.mods.set_module_status("MyModule", False)
 
-### 示例用法：
+# 条件性启用模块
+if check_dependencies():
+    sdk.mods.set_module_status("MyModule", True)
+else:
+    sdk.logger.warning("依赖检查失败，模块未启用")
+```
 
+#### get_module_status(module_name: str) -> bool
+获取模块的启用状态。
+- 参数:
+  - module_name: 模块名称
+- 返回:
+  - bool: 模块状态，True为启用，False为禁用
+- 示例:
+```python
+# 检查模块是否启用
+if sdk.mods.get_module_status("MyModule"):
+    print("模块已启用")
+else:
+    print("模块已禁用")
+    
+# 在条件中使用
+if sdk.mods.get_module_status("DatabaseModule") and sdk.mods.get_module_status("NetworkModule"):
+    start_application()
 ```
-from ErisPulse import sdk
 
-# 设置模块状态
-sdk.mods.set_module_status("MyModule", True)
+### 模块信息管理
+#### set_module(module_name: str, module_info: dict) -> None
+设置模块信息。
+- 参数:
+  - module_name: 模块名称
+  - module_info: 模块信息字典，包含模块的元数据和配置
+- 返回:
+  - None
+- 示例:
+```python
+# 设置基本模块信息
+sdk.mods.set_module("MyModule", {
+    "status": True,
+    "info": {
+        "meta": {
+            "name": "MyModule",
+            "version": "1.0.0",
+            "description": "示例模块",
+            "author": "开发者"
+        },
+        "dependencies": {
+            "requires": ["CoreModule"],
+            "optional": ["OptionalModule"],
+            "pip": ["requests", "numpy"]
+        }
+    }
+})
+
+# 更新现有模块信息
+module_info = sdk.mods.get_module("MyModule")
+module_info["info"]["meta"]["version"] = "1.1.0"
+sdk.mods.set_module("MyModule", module_info)
+```
 
+#### get_module(module_name: str) -> dict | None
+获取模块信息。
+- 参数:
+  - module_name: 模块名称
+- 返回:
+  - dict: 模块信息字典
+  - None: 如果模块不存在
+- 示例:
+```python
 # 获取模块信息
 module_info = sdk.mods.get_module("MyModule")
+if module_info:
+    print(f"模块版本: {module_info['info']['meta']['version']}")
+    print(f"模块描述: {module_info['info']['meta']['description']}")
+    print(f"模块状态: {'启用' if module_info['status'] else '禁用'}")
+else:
+    print("模块不存在")
+```
+
+#### get_all_modules() -> dict
+获取所有模块信息。
+- 参数: 无
+- 返回:
+  - dict: 包含所有模块信息的字典，键为模块名，值为模块信息
+- 示例:
+```python
+# 获取所有模块
+all_modules = sdk.mods.get_all_modules()
+
+# 统计启用和禁用的模块
+enabled_count = 0
+disabled_count = 0
+for name, info in all_modules.items():
+    if info.get("status", False):
+        enabled_count += 1
+    else:
+        disabled_count += 1
+        
+print(f"已启用模块: {enabled_count}")
+print(f"已禁用模块: {disabled_count}")
+
+# 查找特定类型的模块
+adapters = [name for name, info in all_modules.items() 
+           if "adapter" in info.get("info", {}).get("meta", {}).get("tags", [])]
+print(f"适配器模块: {adapters}")
+```
+
+#### update_module(module_name: str, module_info: dict) -> None
+更新模块信息。
+- 参数:
+  - module_name: 模块名称
+  - module_info: 更新后的模块信息字典
+- 返回:
+  - None
+- 示例:
+```python
+# 更新模块版本
+module_info = sdk.mods.get_module("MyModule")
+module_info["info"]["meta"]["version"] = "1.2.0"
+sdk.mods.update_module("MyModule", module_info)
+
+# 添加新的配置项
+module_info = sdk.mods.get_module("MyModule")
+if "config" not in module_info:
+    module_info["config"] = {}
+module_info["config"]["debug_mode"] = True
+sdk.mods.update_module("MyModule", module_info)
+```
+
+#### remove_module(module_name: str) -> bool
+删除模块。
+- 参数:
+  - module_name: 模块名称
+- 返回:
+  - bool: 是否成功删除
+- 示例:
+```python
+# 删除模块
+if sdk.mods.remove_module("OldModule"):
+    print("模块已成功删除")
+else:
+    print("模块不存在或删除失败")
+    
+# 条件删除
+if sdk.mods.get_module_status("TestModule") and is_test_environment():
+    sdk.mods.remove_module("TestModule")
+    print("测试模块已在生产环境中移除")
+```
+
+#### set_all_modules(modules_info: Dict[str, dict]) -> None
+批量设置多个模块信息。
+- 参数:
+  - modules_info: 模块信息字典的字典，键为模块名，值为模块信息
+- 返回:
+  - None
+- 示例:
+```python
+# 批量设置模块
+sdk.mods.set_all_modules({
+    "Module1": {
+        "status": True,
+        "info": {"meta": {"name": "Module1", "version": "1.0.0"}}
+    },
+    "Module2": {
+        "status": True,
+        "info": {"meta": {"name": "Module2", "version": "1.0.0"}}
+    }
+})
+
+# 从配置文件加载模块信息
+import json
+with open("modules_config.json", "r") as f:
+    modules_config = json.load(f)
+sdk.mods.set_all_modules(modules_config)
+```
+
+### 前缀管理
+#### update_prefixes(module_prefix: str = None, status_prefix: str = None) -> None
+更新存储前缀。
+- 参数:
+  - module_prefix: 模块存储前缀
+  - status_prefix: 状态存储前缀
+- 返回:
+  - None
+- 示例:
+```python
+# 更新模块前缀
+sdk.mods.update_prefixes(module_prefix="custom.module.")
+
+# 更新状态前缀
+sdk.mods.update_prefixes(status_prefix="custom.status.")
+
+# 同时更新两个前缀
+sdk.mods.update_prefixes(
+    module_prefix="app.modules.",
+    status_prefix="app.status."
+)
+```
+
+#### module_prefix 属性
+获取当前模块存储前缀。
+- 返回:
+  - str: 当前模块存储前缀
+- 示例:
+```python
+# 获取当前模块前缀
+prefix = sdk.mods.module_prefix
+print(f"当前模块前缀: {prefix}")
+
+# 在自定义存储操作中使用
+custom_key = f"{sdk.mods.module_prefix}custom.{module_name}"
+sdk.env.set(custom_key, custom_data)
+```
+
+#### status_prefix 属性
+获取当前状态存储前缀。
+- 返回:
+  - str: 当前状态存储前缀
+- 示例:
+```python
+# 获取当前状态前缀
+prefix = sdk.mods.status_prefix
+print(f"当前状态前缀: {prefix}")
 
-# 批量操作
-sdk.mods.set_all_modules({"Module1": {...}, "Module2": {...}})
+# 在自定义状态操作中使用
+custom_status_key = f"{sdk.mods.status_prefix}custom.{module_name}"
+sdk.env.set(custom_status_key, is_active)
 ```
 
 """

ErisPulse/raiserr.py

@@ -1,34 +1,69 @@
 """
 # 错误管理系统
 
-提供错误类型注册、抛出和管理功能，集成全局异常处理。
+提供错误类型注册、抛出和管理功能，集成全局异常处理。支持自定义错误类型、错误链追踪和全局异常捕获。
 
 ## API 文档
-### 错误注册：
-    - register(name, doc="", base=Exception): 注册新的错误类型
-    - info(name: str = None): 获取错误类型信息
-
-### 错误抛出：
-    - __getattr__(name): 动态获取错误抛出函数
-    - ErrorType(msg, exit=False): 抛出注册的错误类型
-
-### 全局处理：
-    - global_exception_handler: 全局同步异常处理器
-    - async_exception_handler: 全局异步异常处理器
-
-### 示例用法：
 
+### 错误注册
+#### register(name: str, doc: str = "", base: type = Exception) -> type
+注册新的错误类型。
+- 参数:
+  - name: 错误类型名称
+  - doc: 错误描述文档
+  - base: 基础异常类，默认为Exception
+- 返回:
+  - type: 注册的错误类型类
+- 示例:
+```python
+# 注册一个简单错误
+sdk.raiserr.register("SimpleError", "简单的错误类型")
+
+# 注册带有自定义基类的错误
+class CustomBase(Exception):
+    pass
+sdk.raiserr.register("AdvancedError", "高级错误", CustomBase)
 ```
-from ErisPulse import sdk
 
-# 注册自定义错误
-sdk.raiserr.register("MyError", doc="自定义错误描述")
-
-# 抛出错误
-sdk.raiserr.MyError("发生了错误", exit=False)
+#### info(name: str = None) -> dict | None
+获取错误类型信息。
+- 参数:
+  - name: 错误类型名称，如果为None则返回所有错误类型信息
+- 返回:
+  - dict: 包含错误类型信息的字典，包括类型名、文档和类引用
+  - None: 如果指定的错误类型不存在
+- 示例:
+```python
+# 获取特定错误信息
+error_info = sdk.raiserr.info("SimpleError")
+print(f"错误类型: {error_info['type']}")
+print(f"错误描述: {error_info['doc']}")
+
+# 获取所有注册的错误信息
+all_errors = sdk.raiserr.info()
+for name, info in all_errors.items():
+    print(f"{name}: {info['doc']}")
+```
 
-# 获取错误信息
-error_info = sdk.raiserr.info("MyError")
+### 错误抛出
+#### ErrorType(msg: str, exit: bool = False)
+动态生成的错误抛出函数。
+- 参数:
+  - msg: 错误消息
+  - exit: 是否在抛出错误后退出程序
+- 示例:
+```python
+# 抛出不退出的错误
+sdk.raiserr.SimpleError("操作失败")
+
+# 抛出导致程序退出的错误
+sdk.raiserr.CriticalError("致命错误", exit=True)
+
+# 带有异常捕获的使用方式
+try:
+    sdk.raiserr.ValidationError("数据验证失败")
+except Exception as e:
+    print(f"捕获到错误: {e}")
 ```
 
 """
@@ -86,24 +121,16 @@ raiserr = Error()
 
 # 全局异常处理器
 def global_exception_handler(exc_type, exc_value, exc_traceback):
-    from .logger import logger
     error_message = ''.join(traceback.format_exception(exc_type, exc_value, exc_traceback))
-    logger.error(f"未处理的异常被捕获:\n{error_message}")
-    raiserr.CaughtExternalError(
-        f"检测到外部异常，请优先使用 sdk.raiserr 抛出错误。\n原始异常: {exc_type.__name__}: {exc_value}\nTraceback:\n{error_message}"
+    raiserr.ExternalError(
+        f"{exc_type.__name__}: {exc_value}\nTraceback:\n{error_message}"
     )
-sys.excepthook = global_exception_handler
-
 def async_exception_handler(loop, context):
-    from .logger import logger
     exception = context.get('exception')
-    message = context.get('message', 'Async error')
-    if exception:
-        tb = ''.join(traceback.format_exception(type(exception), exception, exception.__traceback__))
-        logger.error(f"异步任务异常: {message}\n{tb}")
-        raiserr.CaughtExternalError(
-            f"检测到异步任务异常，请优先使用 sdk.raiserr 抛出错误。\n原始异常: {type(exception).__name__}: {exception}\nTraceback:\n{tb}"
-        )
-    else:
-        logger.warning(f"异步任务警告: {message}")
+    tb = ''.join(traceback.format_exception(type(exception), exception, exception.__traceback__))
+    raiserr.ExternalError(
+        f"{type(exception).__name__}: {exception}\nTraceback:\n{tb}"
+    )
+
+sys.excepthook = global_exception_handler
 asyncio.get_event_loop().set_exception_handler(async_exception_handler)