ErisPulse 1.1.13__py3-none-any.whl → 1.1.14__py3-none-any.whl

ErisPulse/logger.py

@@ -1,3 +1,327 @@
+"""
+# 日志系统
+
+提供模块化、多级别的日志记录功能，支持内存存储和文件输出。实现了模块级别的日志控制、彩色输出和灵活的存储选项。
+
+## 核心功能
+1. 多级别日志记录
+2. 模块级别日志控制
+3. 内存日志存储
+4. 文件输出支持
+5. 自动调用者识别
+6. 异常捕获装饰器
+
+## API 文档
+
+### 基本日志操作
+#### debug(msg: str, *args, **kwargs) -> None
+记录调试级别的日志信息。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None
+- 示例:
+```python
+# 基本调试信息
+sdk.logger.debug("初始化配置")
+
+# 带有变量的调试信息
+config_value = get_config("timeout")
+sdk.logger.debug(f"读取配置: timeout = {config_value}")
+
+# 在条件下记录调试信息
+if is_development_mode():
+    sdk.logger.debug("开发模式下的详细信息: %s", detailed_info)
+```
+
+#### info(msg: str, *args, **kwargs) -> None
+记录信息级别的日志信息。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None
+- 示例:
+```python
+# 基本信息记录
+sdk.logger.info("应用已启动")
+
+# 带有上下文的信息
+user_count = get_active_users()
+sdk.logger.info(f"当前活跃用户: {user_count}")
+
+# 记录操作结果
+sdk.logger.info("数据导入完成，共处理 %d 条记录", record_count)
+```
+
+#### warning(msg: str, *args, **kwargs) -> None
+记录警告级别的日志信息。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None
+- 示例:
+```python
+# 基本警告信息
+sdk.logger.warning("配置文件未找到，使用默认配置")
+
+# 性能警告
+if response_time > threshold:
+    sdk.logger.warning(f"响应时间过长: {response_time}ms > {threshold}ms")
+
+# 资源使用警告
+memory_usage = get_memory_usage()
+if memory_usage > 80:
+    sdk.logger.warning("内存使用率高: %d%%", memory_usage)
+```
+
+#### error(msg: str, *args, **kwargs) -> None
+记录错误级别的日志信息。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None
+- 示例:
+```python
+# 基本错误信息
+sdk.logger.error("数据库连接失败")
+
+# 带有异常信息的错误
+try:
+    process_data()
+except Exception as e:
+    sdk.logger.error(f"数据处理错误: {str(e)}")
+
+# 带有错误代码的错误
+sdk.logger.error("API请求失败，状态码: %d, 错误: %s", status_code, error_message)
+```
+
+#### critical(msg: str, *args, **kwargs) -> None
+记录致命错误级别的日志信息，并终止程序。
+- 参数:
+  - msg: 日志消息
+  - *args: 传递给底层logger的位置参数
+  - **kwargs: 传递给底层logger的关键字参数
+- 返回:
+  - None (程序会终止)
+- 示例:
+```python
+# 致命错误记录
+if not database_connection:
+    sdk.logger.critical("无法连接到主数据库，应用无法继续运行")
+
+# 安全相关的致命错误
+if security_breach_detected():
+    sdk.logger.critical("检测到安全漏洞，强制关闭系统")
+
+# 资源耗尽的致命错误
+if disk_space < min_required:
+    sdk.logger.critical("磁盘空间不足 (%dMB)，无法继续运行", disk_space)
+```
+
+### 日志级别控制
+#### 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")
+```
+
+#### 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)
+```
+
+#### 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"))
+```
+
+### 异常捕获 (准备弃用)
+#### catch(func_or_level=None, level="error")
+异常捕获装饰器。
+- 参数:
+  - func_or_level: 要装饰的函数或日志级别
+  - level: 捕获异常时使用的日志级别
+- 返回:
+  - function: 装饰后的函数
+- 注意:
+  - 此功能已集成到 raiserr 模块中，建议使用 raiserr 进行异常处理
+- 示例:
+```python
+# 基本用法 (不推荐，请使用raiserr)
+@sdk.logger.catch
+def risky_function():
+    # 可能抛出异常的代码
+    process_data()
+
+# 指定日志级别 (不推荐，请使用raiserr)
+@sdk.logger.catch(level="critical")
+def very_important_function():
+    # 关键操作
+    update_database()
+```
+
+## 最佳实践
+1. 日志级别使用
+```python
+# 开发环境使用详细日志
+if is_development():
+    sdk.logger.set_level("DEBUG")
+    sdk.logger.debug("详细的调试信息")
+else:
+    sdk.logger.set_level("INFO")
+    
+# 性能敏感模块使用更高级别
+sdk.logger.set_module_level("PerformanceModule", "WARNING")
+```
+
+2. 结构化日志信息
+```python
+# 使用一致的格式
+def log_api_request(endpoint, method, status, duration):
+    sdk.logger.info(
+        f"API请求: {method} {endpoint} - 状态: {status}, 耗时: {duration}ms"
+    )
+
+# 包含关键上下文
+def log_user_action(user_id, action, result):
+    sdk.logger.info(
+        f"用户操作: [用户:{user_id}] {action} - 结果: {result}"
+    )
+```
+
+3. 日志文件管理
+```python
+# 按日期分割日志文件
+from datetime import datetime
+import os
+
+def setup_logging():
+    log_dir = "logs"
+    os.makedirs(log_dir, exist_ok=True)
+    
+    today = datetime.now().strftime("%Y-%m-%d")
+    log_file = os.path.join(log_dir, f"app_{today}.log")
+    
+    sdk.logger.set_output_file(log_file)
+    sdk.logger.info(f"日志文件已设置: {log_file}")
+```
+
+4. 异常处理与日志
+```python
+# 推荐方式：使用raiserr结合logger
+def process_with_logging():
+    try:
+        result = perform_operation()
+        sdk.logger.info(f"操作成功: {result}")
+        return result
+    except Exception as e:
+        sdk.logger.error(f"操作失败: {str(e)}")
+        sdk.raiserr.OperationError(f"处理失败: {str(e)}")
+```
+
+## 注意事项
+1. 日志级别选择
+   - DEBUG: 详细的调试信息，仅在开发环境使用
+   - INFO: 常规操作信息，适用于生产环境
+   - WARNING: 潜在问题或异常情况
+   - ERROR: 错误但不影响整体功能
+   - CRITICAL: 致命错误，导致程序终止
+
+2. 性能考虑
+   - 避免在高频循环中记录过多日志
+   - 使用适当的日志级别减少不必要的输出
+   - 考虑日志文件大小和轮转策略
+
+3. 敏感信息保护
+   - 不要记录密码、令牌等敏感信息
+   - 在记录用户数据前进行脱敏处理
+   - 遵循数据保护法规要求
+
+4. 迁移建议
+   - 从catch装饰器迁移到raiserr模块
+   - 使用结构化的错误处理方式
+   - 结合日志和错误管理实现完整的异常处理流程
+"""
+
 import logging
 import inspect
 import datetime
@@ -152,4 +476,4 @@ class Logger:
             raiserr.register("CriticalError", doc="发生致命错误")
             raiserr.CriticalError(f"程序发生致命错误：{msg}", exit=True)
 
-logger = Logger()
+logger = Logger()

ErisPulse/mods.py

@@ -1,3 +1,334 @@
+"""
+# 模块管理系统
+
+提供模块的注册、状态管理和依赖解析功能。支持模块信息存储、状态切换和批量操作。
+
+## 核心功能
+1. 模块信息管理
+2. 模块状态控制
+3. 批量模块操作
+4. 存储前缀自定义
+5. 模块依赖管理
+
+## API 文档
+
+### 模块状态管理
+#### set_module_status(module_name: str, status: bool) -> None
+设置模块的启用状态。
+- 参数:
+  - module_name: 模块名称
+  - status: 模块状态，True为启用，False为禁用
+- 返回:
+  - None
+- 示例:
+```python
+# 启用模块
+sdk.mods.set_module_status("MyModule", True)
+
+# 禁用模块
+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()
+```
+
+### 模块信息管理
+#### 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}")
+
+# 在自定义状态操作中使用
+custom_status_key = f"{sdk.mods.status_prefix}custom.{module_name}"
+sdk.env.set(custom_status_key, is_active)
+```
+
+## 最佳实践
+1. 模块信息结构
+```python
+# 推荐的模块信息结构
+module_info = {
+    "status": True,  # 模块启用状态
+    "info": {
+        "meta": {
+            "name": "ModuleName",  # 模块名称
+            "version": "1.0.0",    # 模块版本
+            "description": "模块描述",
+            "author": "作者",
+            "license": "MIT",
+            "tags": ["tag1", "tag2"]  # 分类标签
+        },
+        "dependencies": {
+            "requires": ["RequiredModule1"],  # 必需依赖
+            "optional": ["OptionalModule1"],  # 可选依赖
+            "pip": ["package1", "package2"]   # pip包依赖
+        }
+    },
+    "config": {  # 模块配置（可选）
+        "setting1": "value1",
+        "setting2": "value2"
+    }
+}
+```
+
+2. 模块状态管理
+```python
+# 根据条件启用/禁用模块
+def toggle_modules_by_environment():
+    env_type = get_environment_type()
+    
+    # 开发环境启用调试模块
+    if env_type == "development":
+        sdk.mods.set_module_status("DebugModule", True)
+        sdk.mods.set_module_status("PerformanceModule", False)
+    
+    # 生产环境禁用调试模块，启用性能模块
+    elif env_type == "production":
+        sdk.mods.set_module_status("DebugModule", False)
+        sdk.mods.set_module_status("PerformanceModule", True)
+```
+
+3. 模块依赖检查
+```python
+# 检查模块依赖
+def check_module_dependencies(module_name):
+    module_info = sdk.mods.get_module(module_name)
+    if not module_info:
+        return False
+        
+    dependencies = module_info.get("info", {}).get("dependencies", {}).get("requires", [])
+    
+    for dep in dependencies:
+        dep_info = sdk.mods.get_module(dep)
+        if not dep_info or not dep_info.get("status", False):
+            sdk.logger.warning(f"模块 {module_name} 的依赖 {dep} 未启用或不存在")
+            return False
+            
+    return True
+```
+
+## 注意事项
+1. 模块名称应唯一，避免冲突
+2. 模块信息结构应保持一致，便于管理
+3. 更新模块信息前应先获取现有信息，避免覆盖
+4. 批量操作时注意性能影响
+5. 自定义前缀时确保不与系统其他键冲突
+"""
+
 import json
 from typing import Dict, Optional