echotools 2.3.7__tar.gz → 2.3.8__tar.gz

{echotools-2.3.7 → echotools-2.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: echotools
-Version: 2.3.7
+Version: 2.3.8
 Summary: 通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链
 Author: nichengfuben
 License: MIT

echotools-2.3.8/README.md

@@ -0,0 +1,3 @@
+# echotools
+
+Documentation: [docs/README.md](docs/README.md)

{echotools-2.3.7 → echotools-2.3.8}/pyproject.toml

@@ -4,9 +4,9 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "echotools"
-version = "2.3.7"
+version = "2.3.8"
 description = "通用基础设施 SDK：配置、日志、事件、调度、插件、协议、调用链"
-readme = "README.md"
+readme = "docs/README.md"
 requires-python = ">=3.8"
 license = { text = "MIT" }
 authors = [{ name = "nichengfuben" }]
@@ -59,7 +59,7 @@ Issues = "https://github.com/nichengfuben/echotools/issues"
 where = ["src"]
 
 [tool.setuptools.package-data]
-echotools = ["py.typed", "web/input_box/**/*"]
+echotools = ["py.typed", "media/web/input_box/**/*"]
 
 [tool.ruff]
 line-length = 88
@@ -91,11 +91,11 @@ disable_error_code = [
 ]
 
 [[tool.mypy.overrides]]
-module = "echotools.terminal.*"
+module = "echotools.exec.terminal.*"
 ignore_errors = true
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
+testpaths = ["src/tests"]
 asyncio_mode = "auto"
 addopts = ["--strict-markers", "--tb=short"]
 markers = [
@@ -112,7 +112,7 @@ omit = [
     "*/__init__.py",
     "*/terminal/*",
     "*/spinner/*",
-    "*/web/input_box/*",
+    "*/media/web/input_box/*",
     "*/lifecycle/updater.py",
     "*/watcher/*",
     "*/process/*",

echotools-2.3.8/src/echotools/__init__.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+"""echotools：通用基础设施 SDK。
+
+完全项目无关，支持调用链，覆盖 Python 3.8-3.14。
+"""
+
+import importlib
+from typing import Any
+
+from echotools.version import get_version
+from echotools.plat.sdk import EchoTools
+
+__version__ = get_version()
+
+__all__ = [
+    "__version__",
+    "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",
+    "ProxySelector",
+    "ProxyRecord",
+    "Plugin",
+    "PluginRegistry",
+    "discover_plugins",
+    "ToolProtocol",
+    "register_protocol",
+    "get_protocol_by_id",
+    "get_protocol",
+    "list_protocols",
+    "LifecycleManager",
+    "AutoUpdater",
+    "ProxyManager",
+    "PortReleaseResult",
+    "ensure_port_available",
+    "RuntimeCollector",
+    "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",
+    "retry_async_generator",
+    "KeyState",
+    "KeyPool",
+    "extract_text_from_messages",
+    "split_text_chunks",
+    "format_translation_response",
+    "TerminalSession",
+    "TerminalCallback",
+    "LocalTerminal",
+    "SSHTerminal",
+    "PrintStream",
+    "print_stream",
+    "start_print_stream",
+    "stop_print_stream",
+    "flush_print_stream",
+    "get_buffer_size",
+    "get_queue_length",
+    "is_print_stream_running",
+    "set_print_speed",
+    "configure_print_stream",
+    "inject_fncall",
+    "FncallStreamParser",
+    "detect_tool_loop",
+    "LoopDetectionResult",
+    "EchoError",
+    "ConfigError",
+    "ValidationError",
+    "NetworkError",
+    "TimeoutError",
+    "NotSupportedError",
+    "NoCandidateError",
+    "PluginError",
+    "ProtocolError",
+    "classify_http_error",
+    "Spinner",
+]
+
+_EXPORTS: dict[str, tuple[str, str]] = {
+    "ConfigBase": ("echotools.base.config", "ConfigBase"),
+    "ConfigCenter": ("echotools.base.config", "ConfigCenter"),
+    "LoggerManager": ("echotools.base.logger", "LoggerManager"),
+    "get_logger": ("echotools.base.logger", "get_logger"),
+    "set_color": ("echotools.base.logger", "set_color"),
+    "configure": ("echotools.base.logger", "configure"),
+    "Event": ("echotools.media.events", "Event"),
+    "EventBus": ("echotools.media.events", "EventBus"),
+    "Tracer": ("echotools.media.tracing", "Tracer"),
+    "Trace": ("echotools.media.tracing", "Trace"),
+    "Span": ("echotools.media.tracing", "Span"),
+    "get_current_trace_id": ("echotools.media.tracing", "get_current_trace_id"),
+    "set_current_trace_id": ("echotools.media.tracing", "set_current_trace_id"),
+    "get_current_span_id": ("echotools.media.tracing", "get_current_span_id"),
+    "set_current_span_id": ("echotools.media.tracing", "set_current_span_id"),
+    "get_request_id": ("echotools.media.tracing", "get_request_id"),
+    "set_request_id": ("echotools.media.tracing", "set_request_id"),
+    "ListCache": ("echotools.base.cache", "ListCache"),
+    "MemoryCache": ("echotools.base.cache", "MemoryCache"),
+    "TaskCandidate": ("echotools.exec.dispatch", "TaskCandidate"),
+    "make_id": ("echotools.exec.dispatch", "make_id"),
+    "AdaptiveSelector": ("echotools.exec.dispatch", "AdaptiveSelector"),
+    "TaskDispatcher": ("echotools.exec.dispatch", "TaskDispatcher"),
+    "TaskScheduler": ("echotools.plat.scheduler", "TaskScheduler"),
+    "ProxySelector": ("echotools.exec.dispatch", "ProxySelector"),
+    "ProxyRecord": ("echotools.exec.dispatch", "ProxyRecord"),
+    "Plugin": ("echotools.plat.plugin", "Plugin"),
+    "PluginRegistry": ("echotools.plat.plugin", "PluginRegistry"),
+    "discover_plugins": ("echotools.plat.plugin", "discover_plugins"),
+    "ToolProtocol": ("echotools.exec.protocol.base", "ToolProtocol"),
+    "register_protocol": ("echotools.exec.protocol.base", "register_protocol"),
+    "get_protocol_by_id": ("echotools.exec.protocol.base", "get_protocol_by_id"),
+    "get_protocol": ("echotools.exec.fncall.registry", "get_protocol"),
+    "list_protocols": ("echotools.exec.fncall.registry", "list_protocols"),
+    "LifecycleManager": ("echotools.exec.lifecycle", "LifecycleManager"),
+    "AutoUpdater": ("echotools.exec.lifecycle", "AutoUpdater"),
+    "ProxyManager": ("echotools.plat.proxy", "ProxyManager"),
+    "PortReleaseResult": ("echotools.exec.process", "PortReleaseResult"),
+    "ensure_port_available": ("echotools.exec.process", "ensure_port_available"),
+    "RuntimeCollector": ("echotools.plat.runtime", "RuntimeCollector"),
+    "WebApplication": ("echotools.media.web.application", "WebApplication"),
+    "json_body": ("echotools.media.web.utils", "json_body"),
+    "safe_flush": ("echotools.media.web.utils", "safe_flush"),
+    "FileUtil": ("echotools.plat.files", "FileUtil"),
+    "uuid7": ("echotools.base.ids", "uuid7"),
+    "short_id": ("echotools.base.ids", "short_id"),
+    "trace_id": ("echotools.base.ids", "trace_id"),
+    "span_id": ("echotools.base.ids", "span_id"),
+    "atomic_write_text": ("echotools.base.io", "atomic_write_text"),
+    "ensure_directory": ("echotools.base.io", "ensure_directory"),
+    "read_text_if_exists": ("echotools.base.io", "read_text_if_exists"),
+    "retry_with_backoff": ("echotools.base.retry", "retry_with_backoff"),
+    "retry_on_empty": ("echotools.base.retry", "retry_on_empty"),
+    "retry_on_exception": ("echotools.base.retry", "retry_on_exception"),
+    "retry_async_generator": ("echotools.base.retry", "retry_async_generator"),
+    "KeyState": ("echotools.exec.keys", "KeyState"),
+    "KeyPool": ("echotools.exec.keys", "KeyPool"),
+    "extract_text_from_messages": ("echotools.media.translate", "extract_text_from_messages"),
+    "split_text_chunks": ("echotools.media.translate", "split_text_chunks"),
+    "format_translation_response": ("echotools.media.translate", "format_translation_response"),
+    "TerminalSession": ("echotools.exec.terminal.session", "TerminalSession"),
+    "TerminalCallback": ("echotools.exec.terminal.session", "TerminalCallback"),
+    "LocalTerminal": ("echotools.exec.terminal.local", "LocalTerminal"),
+    "SSHTerminal": ("echotools.exec.terminal.ssh", "SSHTerminal"),
+    "PrintStream": ("echotools.base.io.printstream", "PrintStream"),
+    "print_stream": ("echotools.base.io.printstream", "print_stream"),
+    "start_print_stream": ("echotools.base.io.printstream", "start_print_stream"),
+    "stop_print_stream": ("echotools.base.io.printstream", "stop_print_stream"),
+    "flush_print_stream": ("echotools.base.io.printstream", "flush_print_stream"),
+    "get_buffer_size": ("echotools.base.io.printstream", "get_buffer_size"),
+    "get_queue_length": ("echotools.base.io.printstream", "get_queue_length"),
+    "is_print_stream_running": ("echotools.base.io.printstream", "is_print_stream_running"),
+    "set_print_speed": ("echotools.base.io.printstream", "set_print_speed"),
+    "configure_print_stream": ("echotools.base.io.printstream", "configure_print_stream"),
+    "inject_fncall": ("echotools.exec.fncall.prompt.inject", "inject_fncall"),
+    "FncallStreamParser": ("echotools.exec.fncall.parsers.stream", "FncallStreamParser"),
+    "detect_tool_loop": ("echotools.exec.fncall.shared.loop_detect", "detect_tool_loop"),
+    "LoopDetectionResult": ("echotools.exec.fncall.shared.loop_detect", "LoopDetectionResult"),
+    "EchoError": ("echotools.base.errors", "EchoError"),
+    "ConfigError": ("echotools.base.errors", "ConfigError"),
+    "ValidationError": ("echotools.base.errors", "ValidationError"),
+    "NetworkError": ("echotools.base.errors", "NetworkError"),
+    "TimeoutError": ("echotools.base.errors", "TimeoutError"),
+    "NotSupportedError": ("echotools.base.errors", "NotSupportedError"),
+    "NoCandidateError": ("echotools.base.errors", "NoCandidateError"),
+    "PluginError": ("echotools.base.errors", "PluginError"),
+    "ProtocolError": ("echotools.base.errors", "ProtocolError"),
+    "classify_http_error": ("echotools.base.errors", "classify_http_error"),
+    "Spinner": ("echotools.media.spinner", "Spinner"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    if name in _EXPORTS:
+        module_path, attr = _EXPORTS[name]
+        module = importlib.import_module(module_path)
+        return getattr(module, attr)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

echotools-2.3.8/src/echotools/base/cache/__init__.py

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

{echotools-2.3.7/src/echotools → echotools-2.3.8/src/echotools/base}/cache/list_cache.py

@@ -11,7 +11,7 @@ import time
 from pathlib import Path
 from typing import Awaitable, Callable, List, Optional
 
-from echotools.logger.manager import get_logger
+from echotools.base.logger.manager import get_logger
 
 __all__ = ["ListCache"]
 

{echotools-2.3.7/src/echotools → echotools-2.3.8/src/echotools/base}/config/__init__.py

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

echotools-2.3.8/src/echotools/base/config/base.py

@@ -0,0 +1,146 @@
+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 is list:
+            item_type = args[0] if args else Any
+            return _convert_list_field(cls, value, item_type)
+        if origin is set:
+            item_type = args[0] if args else Any
+            return _convert_set_field(cls, value, item_type)
+        if origin is tuple:
+            return _convert_tuple_field(cls, value, args)
+        if origin is dict:
+            key_type, val_type = args if len(args) == 2 else (Any, Any)
+            return _convert_dict_field(cls, value, key_type, val_type)
+        if origin is Union:
+            return _convert_union_field(cls, value, args)
+        if origin is Literal:
+            return _convert_literal_field(value, field_type)
+        if isinstance(field_type, type):
+            return _convert_scalar_field(value, field_type)
+        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]
+
+
+def _convert_list_field(cls: type, value: Any, item_type: Any) -> list:
+    if not isinstance(value, list):
+        raise TypeError("Expected list, got {}".format(type(value).__name__))
+    return [cls._convert_field(i, item_type) for i in value]
+
+
+def _convert_set_field(cls: type, value: Any, item_type: Any) -> set:
+    if not isinstance(value, list):
+        raise TypeError("Expected list, got {}".format(type(value).__name__))
+    return {cls._convert_field(i, item_type) for i in value}
+
+
+def _convert_tuple_field(cls: type, value: Any, args: tuple) -> tuple:
+    return tuple(cls._convert_field(i, a) for i, a in zip(value, args))
+
+
+def _convert_dict_field(cls: type, value: Any, key_type: Any, val_type: Any) -> dict:
+    if not isinstance(value, dict):
+        raise TypeError("Expected dict, got {}".format(type(value).__name__))
+    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
+
+
+def _convert_union_field(cls: type, value: Any, args: tuple) -> Any:
+    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)
+
+
+def _convert_literal_field(value: Any, field_type: Any) -> Any:
+    allowed = get_args(field_type)
+    if value not in allowed:
+        raise TypeError("Value '{}' not in allowed values {}".format(value, allowed))
+    return value
+
+
+def _convert_scalar_field(value: Any, field_type: type) -> Any:
+    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