echotools 1.0.0__py3-none-any.whl

echotools/__init__.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+"""echotools：通用基础设施 SDK。
+
+完全项目无关，支持调用链，覆盖 Python 3.8-3.14。
+"""
+
+from echotools.cache import ListCache, MemoryCache
+from echotools.config import ConfigBase, ConfigCenter
+from echotools.dispatch import (
+    AdaptiveSelector,
+    TaskCandidate,
+    TaskDispatcher,
+    make_id,
+)
+from echotools.errors import (
+    ConfigError,
+    EchoError,
+    NetworkError,
+    NoCandidateError,
+    NotSupportedError,
+    PluginError,
+    ProtocolError,
+    TimeoutError,
+    ValidationError,
+    classify_http_error,
+)
+from echotools.events import Event, EventBus
+from echotools.files import FileUtil
+from echotools.ids import short_id, span_id, trace_id, uuid7
+from echotools.io import (
+    atomic_write_text,
+    ensure_directory,
+    read_text_if_exists,
+)
+from echotools.lifecycle import AutoUpdater, LifecycleManager
+from echotools.logger import LoggerManager, configure, get_logger, set_color
+from echotools.plugin import Plugin, PluginRegistry, discover_plugins
+from echotools.process import PortReleaseResult, ensure_port_available
+from echotools.protocol.base import (
+    ToolProtocol,
+    get_protocol_by_id,
+    list_protocols,
+    register_protocol,
+)
+from echotools.proxy import ProxyManager
+from echotools.retry import (
+    retry_on_empty,
+    retry_on_exception,
+    retry_with_backoff,
+)
+from echotools.runtime import RuntimeCollector
+from echotools.scheduler import TaskScheduler
+from echotools.sdk import EchoTools
+from echotools.tracing import (
+    Span,
+    Trace,
+    Tracer,
+    get_current_span_id,
+    get_current_trace_id,
+    get_request_id,
+    set_current_span_id,
+    set_current_trace_id,
+    set_request_id,
+)
+from echotools.web import WebApplication, json_body, safe_flush
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    # SDK 门面
+    "EchoTools",
+    # 配置
+    "ConfigBase",
+    "ConfigCenter",
+    # 日志
+    "LoggerManager",
+    "get_logger",
+    "set_color",
+    "configure",
+    # 事件
+    "Event",
+    "EventBus",
+    # 调用链
+    "Tracer",
+    "Trace",
+    "Span",
+    "get_current_trace_id",
+    "set_current_trace_id",
+    "get_current_span_id",
+    "set_current_span_id",
+    "get_request_id",
+    "set_request_id",
+    # 缓存
+    "ListCache",
+    "MemoryCache",
+    # 调度
+    "TaskCandidate",
+    "make_id",
+    "AdaptiveSelector",
+    "TaskDispatcher",
+    "TaskScheduler",
+    # 插件
+    "Plugin",
+    "PluginRegistry",
+    "discover_plugins",
+    # 协议
+    "ToolProtocol",
+    "register_protocol",
+    "get_protocol_by_id",
+    "list_protocols",
+    # 生命周期
+    "LifecycleManager",
+    "AutoUpdater",
+    # 网络/代理/进程
+    "ProxyManager",
+    "PortReleaseResult",
+    "ensure_port_available",
+    # 运行时
+    "RuntimeCollector",
+    # Web
+    "WebApplication",
+    "json_body",
+    "safe_flush",
+    # 工具
+    "FileUtil",
+    "uuid7",
+    "short_id",
+    "trace_id",
+    "span_id",
+    "atomic_write_text",
+    "ensure_directory",
+    "read_text_if_exists",
+    "retry_with_backoff",
+    "retry_on_empty",
+    "retry_on_exception",
+    # 错误
+    "EchoError",
+    "ConfigError",
+    "ValidationError",
+    "NetworkError",
+    "TimeoutError",
+    "NotSupportedError",
+    "NoCandidateError",
+    "PluginError",
+    "ProtocolError",
+    "classify_http_error",
+]

echotools/cache/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+"""cache 模块导出。"""
+
+from echotools.cache.list_cache import ListCache
+from echotools.cache.memory_cache import MemoryCache
+
+__all__ = ["ListCache", "MemoryCache"]

echotools/cache/list_cache.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+"""通用列表缓存：持久化 + 定时刷新 + 合并策略。
+
+从 ModelsCache 抽象为完全通用的版本，不预设"模型"语义。
+"""
+
+import asyncio
+import json
+import time
+from pathlib import Path
+from typing import Awaitable, Callable, List, Optional
+
+from echotools.logger.manager import get_logger
+
+__all__ = ["ListCache"]
+
+logger = get_logger(__name__)
+
+
+class ListCache:
+    """通用字符串列表缓存管理器。
+
+    职责：
+    1. 从持久化文件读取缓存
+    2. 定时调用 fetch_fn 刷新远程列表
+    3. 根据 overwrite 决定覆盖或追加
+    4. 更新后触发 on_update 回调
+    """
+
+    def __init__(
+        self,
+        name: str,
+        fallback: List[str],
+        cache_path: str,
+        overwrite: bool = True,
+    ) -> None:
+        """初始化列表缓存。
+
+        Args:
+            name: 缓存标识名（仅用于日志）。
+            fallback: 兜底列表。
+            cache_path: 持久化文件路径。
+            overwrite: True=覆盖，False=只增不减。
+        """
+        self._name = name
+        self._fallback = list(fallback)
+        self._overwrite = overwrite
+        self._items: List[str] = list(fallback)
+        self._cache_path = Path(cache_path)
+        self._refreshing = False
+
+    async def load(self) -> List[str]:
+        """从缓存文件加载列表。
+
+        Returns:
+            缓存列表，无缓存则返回兜底列表。
+        """
+        try:
+            if self._cache_path.is_file():
+                text = self._cache_path.read_text(encoding="utf-8")
+                data = json.loads(text)
+                items = data.get("items", [])
+                if items:
+                    self._items = list(items)
+                    logger.info(
+                        "[%s] 从缓存加载 %d 项",
+                        self._name,
+                        len(self._items),
+                    )
+        except Exception as e:
+            logger.warning("[%s] 缓存加载失败: %s", self._name, e)
+        return list(self._items)
+
+    async def save(self, items: List[str]) -> None:
+        """保存列表到缓存文件。
+
+        Args:
+            items: 要保存的列表。
+        """
+        try:
+            self._cache_path.parent.mkdir(parents=True, exist_ok=True)
+            data = {"items": items, "updated_at": int(time.time())}
+            self._cache_path.write_text(
+                json.dumps(data, ensure_ascii=False, indent=2),
+                encoding="utf-8",
+            )
+        except Exception as e:
+            logger.warning("[%s] 缓存保存失败: %s", self._name, e)
+
+    def _merge(self, remote: List[str]) -> List[str]:
+        """根据策略合并列表。"""
+        if self._overwrite:
+            return list(remote) if remote else list(self._items)
+        existing = set(self._items)
+        merged = list(self._items)
+        for m in remote:
+            if m not in existing:
+                merged.append(m)
+                existing.add(m)
+        return merged
+
+    async def start_refresh_loop(
+        self,
+        fetch_fn: Callable[[], Awaitable[List[str]]],
+        interval: int = 86400,
+        on_update: Optional[
+            Callable[[List[str]], Awaitable[None]]
+        ] = None,
+    ) -> None:
+        """启动定时刷新循环（永久运行）。
+
+        Args:
+            fetch_fn: 返回远程列表的异步函数。
+            interval: 刷新间隔（秒）。
+            on_update: 更新回调。
+        """
+        while True:
+            await self._do_refresh(fetch_fn, on_update)
+            await asyncio.sleep(interval)
+
+    async def _do_refresh(
+        self,
+        fetch_fn: Callable[[], Awaitable[List[str]]],
+        on_update: Optional[
+            Callable[[List[str]], Awaitable[None]]
+        ] = None,
+    ) -> None:
+        """执行一次刷新。"""
+        if self._refreshing:
+            return
+        self._refreshing = True
+        try:
+            remote = await fetch_fn()
+            if remote:
+                merged = self._merge(remote)
+                self._items = merged
+                await self.save(merged)
+                if on_update is not None:
+                    await on_update(merged)
+                logger.info(
+                    "[%s] 列表已刷新: %d 项", self._name, len(merged)
+                )
+        except Exception as e:
+            logger.warning("[%s] 列表刷新失败: %s", self._name, e)
+        finally:
+            self._refreshing = False
+
+    @property
+    def items(self) -> List[str]:
+        """当前列表副本。"""
+        return list(self._items)

echotools/cache/memory_cache.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+"""带 TTL 的内存缓存。"""
+
+import time
+from typing import Any, Dict, Optional, Tuple
+
+__all__ = ["MemoryCache"]
+
+
+class MemoryCache:
+    """简单的 TTL 内存缓存。"""
+
+    def __init__(self, default_ttl: float = 0.0) -> None:
+        """初始化缓存。
+
+        Args:
+            default_ttl: 默认存活秒数，0 表示永不过期。
+        """
+        self._store: Dict[str, Tuple[Any, float]] = {}
+        self._default_ttl = default_ttl
+
+    def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
+        """写入缓存。
+
+        Args:
+            key: 键。
+            value: 值。
+            ttl: 存活秒数，None 用默认。
+        """
+        effective = self._default_ttl if ttl is None else ttl
+        expire = 0.0 if effective <= 0 else time.time() + effective
+        self._store[key] = (value, expire)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """读取缓存。
+
+        Args:
+            key: 键。
+            default: 缺省值。
+
+        Returns:
+            值或默认值（过期自动剔除）。
+        """
+        item = self._store.get(key)
+        if item is None:
+            return default
+        value, expire = item
+        if expire and time.time() > expire:
+            self._store.pop(key, None)
+            return default
+        return value
+
+    def delete(self, key: str) -> None:
+        """删除键。"""
+        self._store.pop(key, None)
+
+    def clear(self) -> None:
+        """清空缓存。"""
+        self._store.clear()
+
+    def cleanup(self) -> int:
+        """清理过期项，返回清理数量。"""
+        now = time.time()
+        expired = [
+            k
+            for k, (_, exp) in self._store.items()
+            if exp and now > exp
+        ]
+        for k in expired:
+            self._store.pop(k, None)
+        return len(expired)

echotools/config/__init__.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+"""config 模块导出。"""
+
+from echotools.config.base import ConfigBase
+from echotools.config.center import ConfigCenter
+from echotools.config.loader import (
+    find_config,
+    find_template,
+    load_file,
+    write_toml,
+)
+from echotools.config.merge import merge_dicts
+
+__all__ = [
+    "ConfigBase",
+    "ConfigCenter",
+    "load_file",
+    "find_config",
+    "find_template",
+    "write_toml",
+    "merge_dicts",
+]

echotools/config/base.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+"""配置数据类基类，提供自动 from_dict 反序列化。"""
+
+from dataclasses import MISSING, fields, is_dataclass
+from typing import (
+    Any,
+    Literal,
+    Type,
+    TypeVar,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+__all__ = ["ConfigBase"]
+
+T = TypeVar("T", bound="ConfigBase")
+
+_type_hints_cache: "dict[type, dict[str, Any]]" = {}
+
+
+class ConfigBase:
+    """配置类基类，提供 from_dict 自动反序列化。"""
+
+    @classmethod
+    def from_dict(cls: Type[T], data: "dict[str, Any]") -> T:
+        """从字典构造实例。"""
+        if not isinstance(data, dict):
+            raise TypeError(
+                "Expected a dict, got {}".format(type(data).__name__)
+            )
+        init_args: "dict[str, Any]" = {}
+        type_hints = _get_type_hints(cls)
+        for f in fields(cls):  # type: ignore[arg-type]
+            field_name = f.name
+            field_type = type_hints.get(field_name, f.type)
+            if field_name.startswith("_"):
+                continue
+            if not f.init:
+                continue
+            if field_name not in data:
+                if f.default is not MISSING:
+                    init_args[field_name] = f.default
+                    continue
+                if f.default_factory is not MISSING:  # type: ignore[misc]
+                    init_args[field_name] = f.default_factory()  # type: ignore[misc]
+                    continue
+                raise ValueError(
+                    "Missing required field: '{}'".format(field_name)
+                )
+            value = data[field_name]
+            init_args[field_name] = cls._convert_field(value, field_type)
+        return cls(**init_args)
+
+    @classmethod
+    def _convert_field(cls, value: Any, field_type: Any) -> Any:
+        """转换单个字段。"""
+        if isinstance(field_type, type) and is_dataclass(field_type):
+            return field_type.from_dict(value)  # type: ignore[attr-defined]
+        origin = get_origin(field_type)
+        args = get_args(field_type)
+        if origin in {list, set, tuple}:
+            if not isinstance(value, list):
+                raise TypeError(
+                    "Expected list for {}, got {}".format(
+                        field_type, type(value).__name__
+                    )
+                )
+            if origin is list:
+                item_type = args[0] if args else Any
+                return [cls._convert_field(i, item_type) for i in value]
+            if origin is set:
+                item_type = args[0] if args else Any
+                return {cls._convert_field(i, item_type) for i in value}
+            if origin is tuple:
+                return tuple(
+                    cls._convert_field(i, a) for i, a in zip(value, args)
+                )
+        if origin is dict:
+            if not isinstance(value, dict):
+                raise TypeError(
+                    "Expected dict for {}, got {}".format(
+                        field_type, type(value).__name__
+                    )
+                )
+            key_type, val_type = args if len(args) == 2 else (Any, Any)
+            result = {}
+            for k, v in value.items():
+                ck = cls._convert_field(k, key_type)
+                try:
+                    cv = cls._convert_field(v, val_type)
+                except (TypeError, ValueError):
+                    cv = v
+                result[ck] = cv
+            return result
+        if origin is Union:
+            if value is None:
+                return None
+            real_type = next(
+                (a for a in args if a is not type(None)), Any
+            )
+            return cls._convert_field(value, real_type)
+        if origin is Literal:
+            allowed = get_args(field_type)
+            if value not in allowed:
+                raise TypeError(
+                    "Value '{}' not in allowed values {}".format(
+                        value, allowed
+                    )
+                )
+            return value
+        if isinstance(field_type, type):
+            if isinstance(value, field_type):
+                return value
+            try:
+                return field_type(value)
+            except (ValueError, TypeError) as e:
+                raise TypeError(
+                    "Cannot convert {} to {}".format(
+                        type(value).__name__, field_type.__name__
+                    )
+                ) from e
+        return value
+
+    def __str__(self) -> str:
+        field_strs = [
+            "{}={!r}".format(f.name, getattr(self, f.name))
+            for f in fields(self)  # type: ignore[arg-type]
+        ]
+        return "{}({})".format(
+            self.__class__.__name__, ", ".join(field_strs)
+        )
+
+
+def _get_type_hints(cls: type) -> "dict[str, Any]":
+    """带缓存的 get_type_hints。"""
+    if cls not in _type_hints_cache:
+        try:
+            _type_hints_cache[cls] = get_type_hints(cls)
+        except Exception:
+            _type_hints_cache[cls] = {}
+    return _type_hints_cache[cls]