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

ErisPulse/adapter.py

@@ -1,46 +1,225 @@
 """
 # 适配器系统
 
-提供平台适配器基类、消息发送DSL和适配器管理功能。
-
-## 主要功能
-- BaseAdapter: 适配器基类
-- SendDSL: 链式消息发送接口
-- AdapterManager: 适配器管理
-- 适配器注册和生命周期管理
+提供平台适配器基类、消息发送DSL和适配器管理功能。支持多平台消息处理、事件驱动和生命周期管理。
 
 ## API 文档
-### 适配器基类 (BaseAdapter):
-    - call_api(): 必须实现的API调用方法
-    - start(): 启动适配器
-    - shutdown(): 关闭适配器
-    - on(): 事件监听装饰器
-    - emit(): 触发事件
-
-### 消息发送DSL (SendDSL):
-    - To(): 设置消息目标
-    - Text(): 发送文本消息
-    - 可扩展其他消息类型
-
-### 适配器管理 (AdapterManager):
-    - register(): 注册适配器
-    - startup(): 启动适配器
-    - shutdown(): 关闭所有适配器
-    - get(): 获取适配器实例
-
-### 示例用法：
 
+### 适配器基类 (BaseAdapter)
+适配器基类提供了与外部平台交互的标准接口。
+
+#### call_api(endpoint: str, **params) -> Any
+调用平台API的抽象方法。
+- 参数:
+  - endpoint: API端点
+  - **params: API参数
+- 返回:
+  - Any: API调用结果
+- 说明:
+  - 必须由子类实现
+  - 处理与平台的实际通信
+- 示例:
+```python
+class MyPlatformAdapter(BaseAdapter):
+    async def call_api(self, endpoint: str, **params):
+        if endpoint == "/send":
+            return await self._send_message(params)
+        elif endpoint == "/upload":
+            return await self._upload_file(params)
+        raise NotImplementedError(f"未实现的端点: {endpoint}")
 ```
-from ErisPulse import sdk
 
-# 注册适配器
-sdk.adapter.register("MyPlatform", MyAdapter)
+#### start() -> None
+启动适配器的抽象方法。
+- 参数: 无
+- 返回:
+  - None
+- 说明:
+  - 必须由子类实现
+  - 处理适配器的初始化和启动逻辑
+- 示例:
+```python
+class MyPlatformAdapter(BaseAdapter):
+    async def start(self):
+        self.client = await self._create_client()
+        self.ws = await self.client.create_websocket()
+        self._start_heartbeat()
+```
+
+#### shutdown() -> None
+关闭适配器的抽象方法。
+- 参数: 无
+- 返回:
+  - None
+- 说明:
+  - 必须由子类实现
+  - 处理资源清理和关闭逻辑
+- 示例:
+```python
+class MyPlatformAdapter(BaseAdapter):
+    async def shutdown(self):
+        if self.ws:
+            await self.ws.close()
+        if self.client:
+            await self.client.close()
+```
+
+#### on(event_type: str = "*") -> Callable
+事件监听装饰器。
+- 参数:
+  - event_type: 事件类型，默认"*"表示所有事件
+- 返回:
+  - Callable: 装饰器函数
+- 示例:
+```python
+adapter = MyPlatformAdapter()
+
+@adapter.on("message")
+async def handle_message(data):
+    print(f"收到消息: {data}")
+
+@adapter.on("error")
+async def handle_error(error):
+    print(f"发生错误: {error}")
+
+# 处理所有事件
+@adapter.on()
+async def handle_all(event):
+    print(f"事件: {event}")
+```
+
+#### emit(event_type: str, data: Any) -> None
+触发事件。
+- 参数:
+  - event_type: 事件类型
+  - data: 事件数据
+- 返回:
+  - None
+- 示例:
+```python
+class MyPlatformAdapter(BaseAdapter):
+    async def _handle_websocket_message(self, message):
+        # 处理消息并触发相应事件
+        if message.type == "chat":
+            await self.emit("message", {
+                "type": "chat",
+                "content": message.content,
+                "sender": message.sender
+            })
+```
 
-# 发送消息
-sdk.adapter.MyPlatform.Send.To("user", "123").Text("Hello")
+#### middleware(func: Callable) -> Callable
+添加中间件处理器。
+- 参数:
+  - func: 中间件函数
+- 返回:
+  - Callable: 中间件函数
+- 示例:
+```python
+adapter = MyPlatformAdapter()
+
+@adapter.middleware
+async def log_middleware(data):
+    print(f"处理数据: {data}")
+    return data
+
+@adapter.middleware
+async def filter_middleware(data):
+    if "spam" in data.get("content", ""):
+        return None
+    return data
+```
+
+### 消息发送DSL (SendDSL)
+提供链式调用风格的消息发送接口。
+
+#### To(target_type: str = None, target_id: str = None) -> 'SendDSL'
+设置消息目标。
+- 参数:
+  - target_type: 目标类型（可选）
+  - target_id: 目标ID
+- 返回:
+  - SendDSL: 发送器实例
+- 示例:
+```python
+# 发送到用户
+sdk.adapter.Platform.Send.To("user", "123").Text("Hello")
+
+# 发送到群组
+sdk.adapter.Platform.Send.To("group", "456").Text("Hello Group")
+
+# 简化形式（只有ID）
+sdk.adapter.Platform.Send.To("123").Text("Hello")
+```
+
+#### Text(text: str) -> Task
+发送文本消息。
+- 参数:
+  - text: 文本内容
+- 返回:
+  - Task: 异步任务
+- 示例:
+```python
+# 发送简单文本
+await sdk.adapter.Platform.Send.To("user", "123").Text("Hello")
+
+# 发送格式化文本
+name = "Alice"
+await sdk.adapter.Platform.Send.To("123").Text(f"Hello {name}")
+```
 
-# 启动适配器
+### 适配器管理 (AdapterManager)
+管理多个平台适配器的注册、启动和关闭。
+
+#### register(platform: str, adapter_class: Type[BaseAdapter]) -> bool
+注册新的适配器类。
+- 参数:
+  - platform: 平台名称
+  - adapter_class: 适配器类
+- 返回:
+  - bool: 注册是否成功
+- 示例:
+```python
+# 注册适配器
+sdk.adapter.register("MyPlatform", MyPlatformAdapter)
+
+# 注册多个适配器
+adapters = {
+    "Platform1": Platform1Adapter,
+    "Platform2": Platform2Adapter
+}
+for name, adapter in adapters.items():
+    sdk.adapter.register(name, adapter)
+```
+
+#### startup(platforms: List[str] = None) -> None
+启动指定的适配器。
+- 参数:
+  - platforms: 要启动的平台列表，None表示所有平台
+- 返回:
+  - None
+- 示例:
+```python
+# 启动所有适配器
 await sdk.adapter.startup()
+
+# 启动指定适配器
+await sdk.adapter.startup(["Platform1", "Platform2"])
+```
+
+#### shutdown() -> None
+关闭所有适配器。
+- 参数: 无
+- 返回:
+  - None
+- 示例:
+```python
+# 关闭所有适配器
+await sdk.adapter.shutdown()
+
+# 在程序退出时关闭
+import atexit
+atexit.register(lambda: asyncio.run(sdk.adapter.shutdown()))
 ```
 
 """

ErisPulse/db.py

@@ -1,55 +1,427 @@
 """
 # 环境配置
 
-提供键值存储、事务支持、快照和恢复功能，用于管理框架配置数据。
+提供键值存储、事务支持、快照和恢复功能，用于管理框架配置数据。基于SQLite实现持久化存储，支持复杂数据类型和原子操作。
 
 ## API 文档
-### 基本操作：
-    - get(key, default=None) -> any: 获取配置项
-    - set(key, value) -> bool: 设置配置项
-    - delete(key) -> bool: 删除配置项
-    - get_all_keys() -> list[str]: 获取所有键名
 
-### 批量操作：
-    - get_multi(keys) -> dict: 批量获取键值
-    - set_multi(items) -> bool: 批量设置键值
-    - delete_multi(keys) -> bool: 批量删除键值
+### 基本操作
+#### get(key: str, default: Any = None) -> Any
+获取配置项的值。
+- 参数:
+  - key: 配置项键名
+  - default: 如果键不存在时返回的默认值
+- 返回:
+  - Any: 配置项的值，如果是JSON格式则自动解析为Python对象
+- 示例:
+```python
+# 获取基本配置
+timeout = sdk.env.get("network.timeout", 30)
+
+# 获取结构化数据
+user_settings = sdk.env.get("user.settings", {})
+if "theme" in user_settings:
+    apply_theme(user_settings["theme"])
+
+# 条件获取
+debug_mode = sdk.env.get("app.debug", False)
+if debug_mode:
+    enable_debug_features()
+```
 
-### 事务管理：
-    - transaction() -> contextmanager: 创建事务上下文
+#### set(key: str, value: Any) -> bool
+设置配置项的值。
+- 参数:
+  - key: 配置项键名
+  - value: 配置项的值，复杂类型会自动序列化为JSON
+- 返回:
+  - bool: 操作是否成功
+- 示例:
+```python
+# 设置基本配置
+sdk.env.set("app.name", "MyApplication")
+
+# 设置结构化数据
+sdk.env.set("server.config", {
+    "host": "localhost",
+    "port": 8080,
+    "workers": 4
+})
+
+# 更新现有配置
+current_settings = sdk.env.get("user.settings", {})
+current_settings["last_login"] = datetime.now().isoformat()
+sdk.env.set("user.settings", current_settings)
+```
 
-### 快照管理：
-    - snapshot(name=None) -> str: 创建数据库快照
-    - restore(snapshot_name) -> bool: 从快照恢复
-    - list_snapshots() -> list: 列出所有快照
-    - delete_snapshot(name) -> bool: 删除指定快照
-    - set_snapshot_interval(seconds): 设置自动快照间隔
+#### delete(key: str) -> bool
+删除配置项。
+- 参数:
+  - key: 要删除的配置项键名
+- 返回:
+  - bool: 操作是否成功
+- 示例:
+```python
+# 删除临时配置
+sdk.env.delete("temp.session")
+
+# 条件删除
+if not is_feature_enabled():
+    sdk.env.delete("feature.config")
+
+# 清理旧配置
+for key in sdk.env.get_all_keys():
+    if key.startswith("deprecated."):
+        sdk.env.delete(key)
+```
 
-### 其他功能：
-    - clear(): 清空所有配置
-    - load_env_file(): 从env.py加载配置(SDK自动)
+#### get_all_keys() -> list[str]
+获取所有配置项的键名。
+- 参数: 无
+- 返回:
+  - list[str]: 所有配置项的键名列表
+- 示例:
+```python
+# 列出所有配置
+all_keys = sdk.env.get_all_keys()
+print(f"当前有 {len(all_keys)} 个配置项")
+
+# 按前缀过滤
+user_keys = [k for k in sdk.env.get_all_keys() if k.startswith("user.")]
+print(f"用户相关配置: {user_keys}")
+
+# 导出配置摘要
+config_summary = {}
+for key in sdk.env.get_all_keys():
+    parts = key.split(".")
+    if len(parts) > 1:
+        category = parts[0]
+        if category not in config_summary:
+            config_summary[category] = 0
+        config_summary[category] += 1
+print("配置分类统计:", config_summary)
+```
 
-### 示例用法：
+### 批量操作
+#### get_multi(keys: list) -> dict
+批量获取多个配置项的值。
+- 参数:
+  - keys: 要获取的配置项键名列表
+- 返回:
+  - dict: 键值对字典，只包含存在的键
+- 示例:
+```python
+# 批量获取配置
+settings = sdk.env.get_multi([
+    "app.name", 
+    "app.version", 
+    "app.debug"
+])
+print(f"应用: {settings.get('app.name')} v{settings.get('app.version')}")
+
+# 获取相关配置组
+db_keys = ["database.host", "database.port", "database.user", "database.password"]
+db_config = sdk.env.get_multi(db_keys)
+connection = create_db_connection(**db_config)
+
+# 配置存在性检查
+required_keys = ["api.key", "api.endpoint", "api.version"]
+config = sdk.env.get_multi(required_keys)
+missing = [k for k in required_keys if k not in config]
+if missing:
+    raise ValueError(f"缺少必要配置: {missing}")
+```
 
+#### set_multi(items: dict) -> bool
+批量设置多个配置项的值。
+- 参数:
+  - items: 要设置的键值对字典
+- 返回:
+  - bool: 操作是否成功
+- 示例:
+```python
+# 批量设置基本配置
+sdk.env.set_multi({
+    "app.name": "MyApp",
+    "app.version": "1.0.0",
+    "app.debug": True
+})
+
+# 更新系统设置
+sdk.env.set_multi({
+    "system.max_connections": 100,
+    "system.timeout": 30,
+    "system.retry_count": 3
+})
+
+# 从外部配置导入
+import json
+with open("config.json", "r") as f:
+    external_config = json.load(f)
+    
+# 转换为扁平结构
+flat_config = {}
+for section, values in external_config.items():
+    for key, value in values.items():
+        flat_config[f"{section}.{key}"] = value
+        
+sdk.env.set_multi(flat_config)
+```
+
+#### delete_multi(keys: list) -> bool
+批量删除多个配置项。
+- 参数:
+  - keys: 要删除的配置项键名列表
+- 返回:
+  - bool: 操作是否成功
+- 示例:
+```python
+# 批量删除临时配置
+temp_keys = [k for k in sdk.env.get_all_keys() if k.startswith("temp.")]
+sdk.env.delete_multi(temp_keys)
+
+# 删除特定模块的所有配置
+module_keys = [k for k in sdk.env.get_all_keys() if k.startswith("module_name.")]
+sdk.env.delete_multi(module_keys)
+
+# 清理测试数据
+test_keys = ["test.user", "test.data", "test.results"]
+sdk.env.delete_multi(test_keys)
 ```
-from ErisPulse import sdk
 
-env = sdk.env
+### 事务管理
+#### transaction() -> contextmanager
+创建事务上下文，确保多个操作的原子性。
+- 参数: 无
+- 返回:
+  - contextmanager: 事务上下文管理器
+- 示例:
+```python
+# 基本事务
+with sdk.env.transaction():
+    sdk.env.set("user.id", user_id)
+    sdk.env.set("user.name", user_name)
+    sdk.env.set("user.email", user_email)
+
+# 带有条件检查的事务
+def update_user_safely(user_id, new_data):
+    with sdk.env.transaction():
+        current = sdk.env.get(f"user.{user_id}", None)
+        if not current:
+            return False
+            
+        for key, value in new_data.items():
+            sdk.env.set(f"user.{user_id}.{key}", value)
+        
+        sdk.env.set(f"user.{user_id}.updated_at", time.time())
+    return True
+
+# 复杂业务逻辑事务
+def transfer_credits(from_user, to_user, amount):
+    with sdk.env.transaction():
+        # 检查余额
+        from_balance = sdk.env.get(f"user.{from_user}.credits", 0)
+        if from_balance < amount:
+            raise ValueError("余额不足")
+            
+        # 更新余额
+        sdk.env.set(f"user.{from_user}.credits", from_balance - amount)
+        
+        to_balance = sdk.env.get(f"user.{to_user}.credits", 0)
+        sdk.env.set(f"user.{to_user}.credits", to_balance + amount)
+        
+        # 记录交易
+        transaction_id = str(uuid.uuid4())
+        sdk.env.set(f"transaction.{transaction_id}", {
+            "from": from_user,
+            "to": to_user,
+            "amount": amount,
+            "timestamp": time.time()
+        })
+```
 
-# 基本操作
-env.set('config_key', 'value')
-value = env.get('config_key')
-value_another = env.config_key  # 通过属性访问
-env.config_key = 'value'        # 通过属性赋值
+### 快照管理
+#### snapshot(name: str = None) -> str
+创建数据库快照。
+- 参数:
+  - name: 快照名称，默认使用当前时间戳
+- 返回:
+  - str: 快照文件路径
+- 示例:
+```python
+# 创建命名快照
+sdk.env.snapshot("before_migration")
+
+# 创建定期备份
+def create_daily_backup():
+    date_str = datetime.now().strftime("%Y%m%d")
+    return sdk.env.snapshot(f"daily_{date_str}")
+
+# 在重要操作前创建快照
+def safe_operation():
+    snapshot_path = sdk.env.snapshot("pre_operation")
+    try:
+        perform_risky_operation()
+    except Exception as e:
+        sdk.logger.error(f"操作失败: {e}")
+        sdk.env.restore(snapshot_path)
+        return False
+    return True
+```
 
-# 事务使用
-with env.transaction():
-    env.set('key1', 'value1')
-    env.set('key2', 'value2')
+#### restore(snapshot_name: str) -> bool
+从快照恢复数据库。
+- 参数:
+  - snapshot_name: 快照名称或路径
+- 返回:
+  - bool: 恢复是否成功
+- 示例:
+```python
+# 恢复到指定快照
+success = sdk.env.restore("before_migration")
+if success:
+    print("成功恢复到之前的状态")
+else:
+    print("恢复失败")
+
+# 回滚到最近的每日备份
+def rollback_to_last_daily():
+    snapshots = sdk.env.list_snapshots()
+    daily_snapshots = [s for s in snapshots if s[0].startswith("daily_")]
+    if daily_snapshots:
+        latest = daily_snapshots[0]  # 列表已按时间排序
+        return sdk.env.restore(latest[0])
+    return False
+
+# 灾难恢复
+def disaster_recovery():
+    snapshots = sdk.env.list_snapshots()
+    if not snapshots:
+        print("没有可用的快照")
+        return False
+        
+    print("可用快照:")
+    for i, (name, date, size) in enumerate(snapshots):
+        print(f"{i+1}. {name} - {date} ({size/1024:.1f} KB)")
+        
+    choice = input("选择要恢复的快照编号: ")
+    try:
+        index = int(choice) - 1
+        if 0 <= index < len(snapshots):
+            return sdk.env.restore(snapshots[index][0])
+    except ValueError:
+        pass
+    return False
+```
+
+#### list_snapshots() -> list
+列出所有可用的快照。
+- 参数: 无
+- 返回:
+  - list: 快照信息列表，每项包含(名称, 创建时间, 大小)
+- 示例:
+```python
+# 列出所有快照
+snapshots = sdk.env.list_snapshots()
+print(f"共有 {len(snapshots)} 个快照")
+
+# 显示快照详情
+for name, date, size in snapshots:
+    print(f"名称: {name}")
+    print(f"创建时间: {date}")
+    print(f"大小: {size/1024:.2f} KB")
+    print("-" * 30)
+
+# 查找特定快照
+def find_snapshot(prefix):
+    snapshots = sdk.env.list_snapshots()
+    return [s for s in snapshots if s[0].startswith(prefix)]
+```
+
+#### delete_snapshot(name: str) -> bool
+删除指定的快照。
+- 参数:
+  - name: 要删除的快照名称
+- 返回:
+  - bool: 删除是否成功
+- 示例:
+```python
+# 删除指定快照
+sdk.env.delete_snapshot("old_backup")
+
+# 清理过期快照
+def cleanup_old_snapshots(days=30):
+    snapshots = sdk.env.list_snapshots()
+    cutoff = datetime.now() - timedelta(days=days)
+    for name, date, _ in snapshots:
+        if date < cutoff:
+            sdk.env.delete_snapshot(name)
+            print(f"已删除过期快照: {name}")
+
+# 保留最新的N个快照
+def retain_latest_snapshots(count=5):
+    snapshots = sdk.env.list_snapshots()
+    if len(snapshots) > count:
+        for name, _, _ in snapshots[count:]:
+            sdk.env.delete_snapshot(name)
+```
+
+## 最佳实践
+
+1. 配置组织
+```python
+# 使用层次结构组织配置
+sdk.env.set("app.server.host", "localhost")
+sdk.env.set("app.server.port", 8080)
+sdk.env.set("app.database.url", "postgresql://localhost/mydb")
+
+# 使用命名空间避免冲突
+sdk.env.set("module1.config.timeout", 30)
+sdk.env.set("module2.config.timeout", 60)
+```
+
+2. 事务使用
+```python
+# 确保数据一致性
+def update_configuration(config_data):
+    with sdk.env.transaction():
+        # 验证
+        for key, value in config_data.items():
+            if not validate_config(key, value):
+                raise ValueError(f"无效的配置: {key}")
+                
+        # 更新
+        for key, value in config_data.items():
+            sdk.env.set(key, value)
+            
+        # 记录更新
+        sdk.env.set("config.last_updated", time.time())
+```
+
+3. 快照管理
+```python
+# 定期创建快照
+def schedule_backups():
+    # 每日快照
+    if not sdk.env.snapshot(f"daily_{datetime.now().strftime('%Y%m%d')}"):
+        sdk.logger.error("每日快照创建失败")
+        
+    # 清理旧快照
+    cleanup_old_snapshots(days=30)
+    
+# 自动备份重要操作
+def safe_bulk_update(updates):
+    snapshot_name = f"pre_update_{time.time()}"
+    sdk.env.snapshot(snapshot_name)
     
-# 快照管理
-snapshot_path = env.snapshot()
-env.restore('snapshot_name')
+    try:
+        with sdk.env.transaction():
+            for key, value in updates.items():
+                sdk.env.set(key, value)
+    except Exception as e:
+        sdk.logger.error(f"批量更新失败: {e}")
+        sdk.env.restore(snapshot_name)
+        raise
 ```
 
 """