echotools 2.4.7__tar.gz → 2.4.9__tar.gz

{echotools-2.4.7 → echotools-2.4.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 2.4.7
+Version: 2.4.9
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Home-page: https://github.com/nichengfuben/echotools
 Author: nichengfuben
@@ -58,7 +58,7 @@ Requires-Dist: ruff>=0.4.0; extra == "dev"
 
 通用基础设施 SDK：配置、日志、事件、调度、插件、调用链，以及 **entml** LLM 工具调用协议与终端 Console UI。
 
-完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.7**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
+完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.9**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
 
 ## 安装
 

{echotools-2.4.7 → echotools-2.4.9}/README.md

@@ -2,7 +2,7 @@
 
 通用基础设施 SDK：配置、日志、事件、调度、插件、调用链，以及 **entml** LLM 工具调用协议与终端 Console UI。
 
-完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.7**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
+完全项目无关，兼容 Python 3.8–3.14。当前版本：**2.4.9**（详见 [CHANGELOG](docs/CHANGELOG.md)）。
 
 ## 安装
 

{echotools-2.4.7 → echotools-2.4.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "2.4.7"
+version = "2.4.9"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -142,6 +142,23 @@ omit = [
     "*/web/application.py",
     "*/web/middleware.py",
     "*/web/utils.py",
+    "*/plat/capture/shared/win_com.py",
+    "*/plat/capture/audio_monitor/api.py",
+    "*/plat/capture/audio_record/api.py",
+    "*/plat/capture/screenshot/api.py",
+    "*/plat/capture/audio_monitor/win.py",
+    "*/plat/capture/audio_monitor/mac.py",
+    "*/plat/capture/audio_monitor/linux.py",
+    "*/plat/capture/audio_record/win.py",
+    "*/plat/capture/audio_record/win_wasapi.py",
+    "*/plat/capture/audio_record/win_winmm.py",
+    "*/plat/capture/audio_record/mac.py",
+    "*/plat/capture/audio_record/linux.py",
+    "*/plat/capture/screenshot/win.py",
+    "*/plat/capture/screenshot/win_dxgi.py",
+    "*/plat/capture/screenshot/win_gdi.py",
+    "*/plat/capture/screenshot/mac.py",
+    "*/plat/capture/screenshot/linux.py",
 ]
 
 [tool.coverage.report]

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/cache/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""cache 模块导出。"""
-
 from echotools.base.cache.list_cache import ListCache
 from echotools.base.cache.memory_cache import MemoryCache
 

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/cache/list_cache.py

@@ -19,14 +19,7 @@ logger = get_logger(__name__)
 
 
 class ListCache:
-    """通用字符串列表缓存管理器。
-
-    职责：
-    1. 从持久化文件读取缓存
-    2. 定时调用 fetch_fn 刷新远程列表
-    3. 根据 overwrite 决定覆盖或追加
-    4. 更新后触发 on_update 回调
-    """
+    """持久化字符串列表；定时 fetch 刷新，overwrite 控制覆盖或只增不减。"""
 
     def __init__(
         self,
@@ -36,15 +29,6 @@ class ListCache:
         overwrite: bool = True,
         data_key: str = "items",
     ) -> None:
-        """初始化列表缓存。
-
-        Args:
-            name: 缓存标识名（仅用于日志）。
-            fallback: 兜底列表。
-            cache_path: 持久化文件路径。
-            overwrite: True=覆盖，False=只增不减。
-            data_key: JSON 中存储列表的键名，默认 "items"。
-        """
         self._name = name
         self._fallback = list(fallback)
         self._overwrite = overwrite
@@ -54,11 +38,6 @@ class ListCache:
         self._data_key = data_key
 
     async def load(self) -> List[str]:
-        """从缓存文件加载列表。
-
-        Returns:
-            缓存列表，无缓存则返回兜底列表。
-        """
         try:
             if self._cache_path.is_file():
                 text = self._cache_path.read_text(encoding="utf-8")
@@ -76,11 +55,6 @@ class ListCache:
         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 = {self._data_key: items, "updated_at": int(time.time())}
@@ -92,7 +66,6 @@ class ListCache:
             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)
@@ -111,13 +84,6 @@ class ListCache:
             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)

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/cache/memory_cache.py

@@ -14,19 +14,12 @@ class MemoryCache:
     """Thread-safe TTL memory cache with optional LRU eviction."""
 
     def __init__(self, default_ttl: float = 0.0, max_size: int = 0) -> None:
-        """初始化缓存。
-
-        Args:
-            default_ttl: 默认存活秒数，0 表示永不过期。
-            max_size: 最大条目数，0 表示不限制。
-        """
         self._store: "OrderedDict[str, Tuple[Any, float]]" = OrderedDict()
         self._default_ttl = default_ttl
         self._max_size = max_size
         self._lock = threading.RLock()
 
     def set(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
-        """写入缓存。"""
         effective = self._default_ttl if ttl is None else ttl
         expire = 0.0 if effective <= 0 else time.time() + effective
         with self._lock:
@@ -36,7 +29,6 @@ class MemoryCache:
             self._evict_if_needed()
 
     def get(self, key: str, default: Any = None) -> Any:
-        """读取缓存。"""
         with self._lock:
             item = self._store.get(key)
             if item is None:
@@ -49,17 +41,15 @@ class MemoryCache:
             return value
 
     def delete(self, key: str) -> None:
-        """删除键。"""
         with self._lock:
             self._store.pop(key, None)
 
     def clear(self) -> None:
-        """清空缓存。"""
         with self._lock:
             self._store.clear()
 
     def cleanup(self) -> int:
-        """清理过期项，返回清理数量。"""
+        """返回被剔除的过期条目数。"""
         now = time.time()
         with self._lock:
             expired = [k for k, (_, exp) in self._store.items() if exp and now > exp]

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/config/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""config 模块导出。"""
-
 from echotools.base.config.base import ConfigBase
 from echotools.base.config.center import ConfigCenter
 from echotools.base.config.loader import (

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/config/center.py

@@ -52,7 +52,6 @@ class ConfigCenter:
     """
 
     def __init__(self) -> None:
-        """初始化配置中心。"""
         self._raw: Dict[str, Any] = {}
         self._path: Optional[Path] = None
         self._callbacks: Dict[str, List[Callable[[Any, Any], Any]]] = {}
@@ -77,19 +76,7 @@ class ConfigCenter:
         filename: str = "config.toml",
         data: Optional[Dict[str, Any]] = None,
     ) -> Dict[str, Any]:
-        """加载配置。
-
-        Args:
-            path: 配置文件路径。
-            filename: 自动查找时的文件名。
-            data: 直接提供字典（最高优先，跳过文件）。
-
-        Returns:
-            原始配置字典。
-
-        Raises:
-            ConfigError: 无法定位或解析配置。
-        """
+        """加载配置；data 非空时跳过文件读取。"""
         if data is not None:
             self._raw = copy.deepcopy(data)
             return dict(self._raw)
@@ -104,15 +91,7 @@ class ConfigCenter:
         return dict(self._raw)
 
     def get(self, path: str, default: Any = None) -> Any:
-        """按点路径获取配置值。
-
-        Args:
-            path: 形如 "server.port" 的点路径。
-            default: 缺省值。
-
-        Returns:
-            配置值或默认值。
-        """
+        """按点路径获取配置值。"""
         node: Any = self._raw
         for part in path.split("."):
             if isinstance(node, dict) and part in node:
@@ -122,12 +101,7 @@ class ConfigCenter:
         return node
 
     def set(self, path: str, value: Any) -> None:
-        """按点路径设置配置值（内存中）。
-
-        Args:
-            path: 点路径。
-            value: 新值。
-        """
+        """按点路径设置配置值（仅内存，不写文件）。"""
         parts = path.split(".")
         node = self._raw
         for part in parts[:-1]:
@@ -137,15 +111,7 @@ class ConfigCenter:
         node[parts[-1]] = value
 
     def bind(self, schema: Type[C], section: str = "") -> C:
-        """将配置绑定到类型化 ConfigBase 子类。
-
-        Args:
-            schema: ConfigBase 子类。
-            section: 子段点路径，空表示根。
-
-        Returns:
-            类型化配置实例。
-        """
+        """将配置绑定到类型化 ConfigBase 子类。"""
         data = self.get(section, {}) if section else self._raw
         if not isinstance(data, dict):
             raise ConfigError(
@@ -155,31 +121,20 @@ class ConfigCenter:
 
     @property
     def raw(self) -> Dict[str, Any]:
-        """原始配置字典副本。"""
         return copy.deepcopy(self._raw)
 
     @property
     def path(self) -> Optional[Path]:
-        """配置文件路径。"""
         return self._path
 
     def on_change(
         self, path: str, callback: Callable[[Any, Any], Any]
     ) -> None:
-        """注册配置变更回调。
-
-        Args:
-            path: 监听的点路径。
-            callback: 回调(old, new)，支持同步/异步。
-        """
+        """注册配置变更回调；callback(old, new) 支持同步或异步。"""
         self._callbacks.setdefault(path, []).append(callback)
 
     async def reload(self) -> bool:
-        """热重载配置文件并触发变更回调。
-
-        Returns:
-            是否成功。
-        """
+        """热重载配置文件并触发已注册的变更回调。"""
         if self._path is None or not self._path.exists():
             return False
         async with self._get_lock():
@@ -214,11 +169,7 @@ class ConfigCenter:
         return init_from_template(self, **kwargs)
 
     def write(self, data: Optional[Dict[str, Any]] = None) -> None:
-        """将配置写回文件（tomlkit 保留注释）。
-
-        Args:
-            data: 要写入的字典，None 则写入当前 _raw。
-        """
+        """将配置写回文件（tomlkit 保留注释）。"""
         if self._path is None:
             raise ConfigError("配置路径未设置")
         write_toml(self._path, data if data is not None else self._raw)
@@ -226,14 +177,7 @@ class ConfigCenter:
             self._raw = copy.deepcopy(data)
 
     def backup(self, backup_dir: Optional[str] = None) -> Optional[Path]:
-        """创建配置文件的带时间戳备份。
-
-        Args:
-            backup_dir: 备份目录，默认 <config_dir>/template/old。
-
-        Returns:
-            备份文件路径，无配置路径时返回 None。
-        """
+        """创建配置文件的带时间戳备份；默认目录为 <config_dir>/template/old。"""
         if self._path is None or not self._path.exists():
             return None
         if backup_dir is None:
@@ -247,10 +191,6 @@ class ConfigCenter:
         logger.debug("已备份: %s", backup_path)
         return backup_path
 
-    # ------------------------------------------------------------------
-    # __getattr__ 代理
-    # ------------------------------------------------------------------
-
     def bind_proxy(self, schema: Type[C], section: str = "") -> C:
         """绑定 schema 并启用 __getattr__ 代理。
 

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/errors/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""错误模块统一导出。"""
-
 from echotools.base.errors.base import EchoError
 from echotools.base.errors.classify import classify_http_error
 from echotools.base.errors.common import (

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/errors/base.py

@@ -19,13 +19,6 @@ class EchoError(Exception):
         original: Optional[Exception] = None,
         status_code: int = 500,
     ) -> None:
-        """初始化异常。
-
-        Args:
-            message: 错误信息。
-            original: 原始异常。
-            status_code: 关联状态码。
-        """
         super().__init__(message)
         self.message = message
         self.original = original

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/ids/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""ids 模块导出。"""
-
 from echotools.base.ids.generator import gen_tool_id, short_id, span_id, trace_id, uuid7
 
 __all__ = ["uuid7", "short_id", "trace_id", "span_id", "gen_tool_id"]

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/ids/generator.py

@@ -11,11 +11,7 @@ __all__ = ["uuid7", "short_id", "trace_id", "span_id", "gen_tool_id"]
 
 
 def uuid7() -> str:
-    """生成时间有序的 UUIDv7 字符串。
-
-    Returns:
-        符合 UUIDv7 位布局的字符串。
-    """
+    """时间有序的 UUIDv7。"""
     ts_ms = int(time.time() * 1000) & 0xFFFFFFFFFFFF
     rand_bytes = secrets.token_bytes(10)
     rand_a = struct.unpack(">H", rand_bytes[:2])[0] & 0x0FFF
@@ -31,37 +27,19 @@ def uuid7() -> str:
 
 
 def short_id(length: int = 12) -> str:
-    """生成短随机 ID。
-
-    Args:
-        length: 长度，默认为 12。
-
-    Returns:
-        十六进制随机字符串。
-    """
     if length <= 0:
         raise ValueError("length 必须为正整数")
     return uuid.uuid4().hex[:length]
 
 
 def trace_id() -> str:
-    """生成 trace_id（32 位十六进制）。
-
-    Returns:
-        trace_id 字符串。
-    """
     return secrets.token_hex(16)
 
 
 def span_id() -> str:
-    """生成 span_id（16 位十六进制）。
-
-    Returns:
-        span_id 字符串。
-    """
     return secrets.token_hex(8)
 
 
 def gen_tool_id() -> str:
-    """生成 Anthropic 兼容的 tool_use id（``toolu_`` + 24 位十六进制）。"""
+    """Anthropic 兼容 tool_use id（``toolu_`` + 24 hex）。"""
     return f"toolu_{uuid.uuid4().hex[:24]}"

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/io/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""io 模块导出。"""
-
 from echotools.base.io.io_utils import (
     atomic_write_text,
     ensure_directory,

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/io/printstream.py

@@ -1,9 +1,4 @@
-"""Dynamic speed print stream system for controlled console output.
-
-This module provides a PrintStream class that implements dynamic speed
-printing with ordered queue management, suitable for controlled output
-of large text blocks with adaptive speed based on queue depth.
-"""
+"""动态速率打印流：按队列深度自适应输出速度。"""
 
 from __future__ import annotations
 
@@ -17,21 +12,7 @@ from typing import Any, Optional
 
 
 class PrintStream:
-    """Dynamic speed print stream system with ordered queue.
-
-    This class manages a queue of text blocks and outputs them with
-    adaptive speed based on the current queue depth. The output speed
-    increases as more text is pending, providing smooth, controlled output.
-
-    Attributes:
-        min_speed: Minimum output speed in characters per second.
-        max_speed: Maximum output speed in characters per second.
-        decay_factor: Controls how quickly speed adapts to queue depth.
-        smoothing_factor: Controls speed change smoothing (0.0-1.0).
-        current_speed: Current output speed in characters per second.
-        accumulated_chars: Fractional characters pending output.
-        total_pending_chars: Total characters waiting to be output.
-    """
+    """按队列深度自适应输出速度的打印流。"""
 
     def __init__(
         self,
@@ -40,14 +21,6 @@ class PrintStream:
         decay_factor: float = 20.0,
         smoothing_factor: float = 0.8,
     ) -> None:
-        """Initialize the print stream.
-
-        Args:
-            min_speed: Minimum output speed (characters/second).
-            max_speed: Maximum output speed (characters/second).
-            decay_factor: Controls speed adaptation curve.
-            smoothing_factor: Controls speed change smoothing.
-        """
         # Queue management
         self._text_queue: deque[str] = deque()
         self._current_text: str = ""
@@ -80,10 +53,7 @@ class PrintStream:
             self._output_thread.start()
 
     def stop(self) -> None:
-        """Stop the print stream system.
-
-        Waits for all pending output to complete before stopping.
-        """
+        """停止输出；会等待队列中待输出内容排空。"""
         if self._running:
             self._running = False
             # Wait for all content to be output
@@ -98,11 +68,7 @@ class PrintStream:
                 self._output_thread.join(timeout=1)
 
     def add_to_buffer(self, text: str) -> None:
-        """Add text to the output queue.
-
-        Args:
-            text: Text to add to the queue.
-        """
+        """将文本加入输出队列。"""
         if not self._running:
             self.start()
 
@@ -129,14 +95,7 @@ class PrintStream:
             self.accumulated_chars = 0.0
 
     def _calculate_dynamic_speed(self, buffer_length: int) -> float:
-        """Calculate dynamic output speed based on buffer length.
-
-        Args:
-            buffer_length: Number of pending characters.
-
-        Returns:
-            Calculated speed in characters per second.
-        """
+        """根据待输出字符数计算当前输出速率。"""
         if buffer_length <= 0:
             return self.min_speed
 
@@ -201,31 +160,16 @@ class PrintStream:
 
     @property
     def buffer_size(self) -> int:
-        """Get total characters waiting to be output.
-
-        Returns:
-            Number of pending characters.
-        """
         with self._lock:
             queue_chars = sum(len(text) for text in self._text_queue)
             return len(self._current_text) + queue_chars
 
     @property
     def is_running(self) -> bool:
-        """Check if the system is running.
-
-        Returns:
-            True if running, False otherwise.
-        """
         return self._running
 
     @property
     def queue_length(self) -> int:
-        """Get number of text blocks in queue.
-
-        Returns:
-            Number of queued text blocks.
-        """
         with self._lock:
             return len(self._text_queue)
 
@@ -240,17 +184,7 @@ def print_stream(
     end: str = "\n",
     flush: bool = False,
 ) -> None:
-    """Dynamic speed print function.
-
-    This function provides a drop-in replacement for the built-in print()
-    function with dynamic speed output based on queue depth.
-
-    Args:
-        *args: Content to print.
-        sep: Separator between arguments (default: space).
-        end: End character (default: newline).
-        flush: If True, output immediately without queuing.
-    """
+    """动态速率 print 替代；flush=True 时立即输出不入队。"""
     try:
         # Ensure system is started
         if not _global_print_stream.is_running:
@@ -288,39 +222,19 @@ def flush_print_stream() -> None:
 
 
 def get_buffer_size() -> int:
-    """Get current buffer size.
-
-    Returns:
-        Number of pending characters.
-    """
     return _global_print_stream.buffer_size
 
 
 def get_queue_length() -> int:
-    """Get number of text blocks in queue.
-
-    Returns:
-        Number of queued text blocks.
-    """
     return _global_print_stream.queue_length
 
 
 def is_print_stream_running() -> bool:
-    """Check if the print stream system is running.
-
-    Returns:
-        True if running, False otherwise.
-    """
     return _global_print_stream.is_running
 
 
 def set_print_speed(min_speed: float = 5.0, max_speed: float = 50.0) -> None:
-    """Set print speed range.
-
-    Args:
-        min_speed: Minimum print speed (characters/second).
-        max_speed: Maximum print speed (characters/second).
-    """
+    """设置输出速率上下限。"""
     _global_print_stream.min_speed = max(1.0, min_speed)
     _global_print_stream.max_speed = max(_global_print_stream.min_speed, max_speed)
 
@@ -331,14 +245,7 @@ def configure_print_stream(
     decay_factor: float = 20.0,
     smoothing_factor: float = 0.8,
 ) -> None:
-    """Configure print stream system parameters.
-
-    Args:
-        min_speed: Minimum print speed.
-        max_speed: Maximum print speed.
-        decay_factor: Decay factor for speed adaptation.
-        smoothing_factor: Smoothing factor for speed changes.
-    """
+    """配置输出速率与平滑参数。"""
     _global_print_stream.min_speed = max(1.0, min_speed)
     _global_print_stream.max_speed = max(_global_print_stream.min_speed, max_speed)
     _global_print_stream.decay_factor = max(1.0, decay_factor)
@@ -357,8 +264,6 @@ def _cleanup() -> None:
 # Register cleanup function
 atexit.register(_cleanup)
 
-
-# Module exports
 __all__ = [
     "PrintStream",
     "print_stream",

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/logger/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""logger 模块导出。"""
-
 from echotools.base.logger.manager import (
     LoggerManager,
     configure,

{echotools-2.4.7 → echotools-2.4.9}/src/echotools/base/retry/__init__.py

@@ -1,7 +1,5 @@
 from __future__ import annotations
 
-"""retry 模块导出。"""
-
 from echotools.base.retry.retry import (
     retry_async_generator,
     retry_on_empty,