echotools 1.0.0__tar.gz

echotools-1.0.0/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: echotools
+Version: 1.0.0
+Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
+Author: nichengfuben
+License: MIT
+Project-URL: Homepage, https://github.com/nichengfuben/echotools
+Project-URL: Repository, https://github.com/nichengfuben/echotools
+Project-URL: Issues, https://github.com/nichengfuben/echotools/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: typing-extensions>=4.7.0
+Provides-Extra: toml
+Requires-Dist: tomlkit>=0.11.0; extra == "toml"
+Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "toml"
+Provides-Extra: watch
+Requires-Dist: watchdog>=3.0.0; extra == "watch"
+Provides-Extra: http
+Requires-Dist: aiohttp>=3.8.0; extra == "http"
+Provides-Extra: socks
+Requires-Dist: aiohttp-socks>=0.8.0; extra == "socks"
+Provides-Extra: all
+Requires-Dist: tomlkit>=0.11.0; extra == "all"
+Requires-Dist: tomli>=2.0.0; python_version < "3.11" and extra == "all"
+Requires-Dist: watchdog>=3.0.0; extra == "all"
+Requires-Dist: aiohttp>=3.8.0; extra == "all"
+Requires-Dist: aiohttp-socks>=0.8.0; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+
+# echotools
+
+通用基础设施 SDK：配置中心、日志、事件总线、调用链、任务调度、
+插件框架、协议系统、自适应选择器，完全项目无关，兼容 Python 3.8-3.14。
+
+## 安装
+
+    pip install echotools[all]
+
+## 快速开始
+
+    from echotools import EchoTools
+
+    et = EchoTools(service_name="myapp")
+    et.logger.configure(level="INFO", color=True)
+    cfg = et.config
+    cfg.load("config.toml")
+
+    with et.tracer.trace("request") as trace:
+        with et.tracer.span(trace, "db") as span:
+            span.set_tag("query", "select 1")
+
+## 能力总览
+
+- ConfigCenter      点路径配置 + 热重载 + 类型绑定
+- LoggerManager     调用链注入 + 颜色 + 轮转
+- EventBus          同步/异步事件
+- Tracer            轻量调用链
+- TaskDispatcher    单发/竞速 + 自适应选择
+- PluginRegistry    自动发现 + 热重载
+- get_protocol      XML/antml/original/bracket/nous/custom 协议
+- ProxyManager      HTTP/HTTPS/SOCKS
+- AutoUpdater       git 自动更新
+- FileWatcher       轮询文件监视

echotools-1.0.0/README.md

@@ -0,0 +1,34 @@
+# echotools
+
+通用基础设施 SDK：配置中心、日志、事件总线、调用链、任务调度、
+插件框架、协议系统、自适应选择器，完全项目无关，兼容 Python 3.8-3.14。
+
+## 安装
+
+    pip install echotools[all]
+
+## 快速开始
+
+    from echotools import EchoTools
+
+    et = EchoTools(service_name="myapp")
+    et.logger.configure(level="INFO", color=True)
+    cfg = et.config
+    cfg.load("config.toml")
+
+    with et.tracer.trace("request") as trace:
+        with et.tracer.span(trace, "db") as span:
+            span.set_tag("query", "select 1")
+
+## 能力总览
+
+- ConfigCenter      点路径配置 + 热重载 + 类型绑定
+- LoggerManager     调用链注入 + 颜色 + 轮转
+- EventBus          同步/异步事件
+- Tracer            轻量调用链
+- TaskDispatcher    单发/竞速 + 自适应选择
+- PluginRegistry    自动发现 + 热重载
+- get_protocol      XML/antml/original/bracket/nous/custom 协议
+- ProxyManager      HTTP/HTTPS/SOCKS
+- AutoUpdater       git 自动更新
+- FileWatcher       轮询文件监视

echotools-1.0.0/pyproject.toml

@@ -0,0 +1,82 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "echotools"
+version = "1.0.0"
+description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "nichengfuben" }]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "typing-extensions>=4.7.0",
+]
+
+[project.optional-dependencies]
+toml = ["tomlkit>=0.11.0", "tomli>=2.0.0; python_version < '3.11'"]
+watch = ["watchdog>=3.0.0"]
+http = ["aiohttp>=3.8.0"]
+socks = ["aiohttp-socks>=0.8.0"]
+all = [
+    "tomlkit>=0.11.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+    "watchdog>=3.0.0",
+    "aiohttp>=3.8.0",
+    "aiohttp-socks>=0.8.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-cov>=4.1.0",
+    "mypy>=1.5.0",
+    "black>=23.0.0",
+    "isort>=5.12.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/nichengfuben/echotools"
+Repository = "https://github.com/nichengfuben/echotools"
+Issues = "https://github.com/nichengfuben/echotools/issues"
+
+[tool.black]
+line-length = 88
+target-version = ["py38", "py39", "py310", "py311", "py312", "py313"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["echotools"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = ["--strict-markers", "--tb=short"]
+
+[tool.coverage.run]
+source = ["src/echotools"]
+branch = true
+omit = ["*/tests/*", "*/__init__.py"]
+
+[tool.coverage.report]
+fail_under = 90
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

echotools-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

echotools-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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",
+]