python-library-watch-config 0.1.0__py3-none-any.whl

python_library_watch_config-0.1.0.dist-info/METADATA

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: python-library-watch-config
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: python-library-configlib

python_library_watch_config-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+watch_config/__init__.py,sha256=9Kr0T2jbL2Ic3dQMTMyHeAy3MeF0nhrSL3otsY6C-WQ,293
+watch_config/changelog.py,sha256=InFO0Loj2RpFLFT43dps5nyveMJghp8gyRGQkiKnJ3I,1881
+watch_config/diff.py,sha256=lFBJo8UR_v1FuTHr1uo10ze_JrhwjvHfUpWs5uM9hzE,2992
+watch_config/renderer.py,sha256=RSxsUEP5NMzNBQCtFe3ZUUnz9HS-PJ2bqEBD1QqZDGA,2815
+watch_config/watch_config.py,sha256=GgfE89RQ9yQrt2BsV12QZBvR4X3teQoPvlelKBxgfdk,6858
+python_library_watch_config-0.1.0.dist-info/METADATA,sha256=nVQyV3KVT8n1Jy39cZN_WoSiCmtp7dD2NYP7z8NnIfc,135
+python_library_watch_config-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_library_watch_config-0.1.0.dist-info/RECORD,,

python_library_watch_config-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

watch_config/__init__.py

@@ -0,0 +1,12 @@
+from .changelog import ChangeEntry, ChangeLog, ChangeType
+from .renderer import ChangeRenderer, DefaultRenderer
+from .watch_config import WatchConfig
+
+__all__ = [
+    "ChangeEntry",
+    "ChangeLog",
+    "ChangeType",
+    "ChangeRenderer",
+    "DefaultRenderer",
+    "WatchConfig",
+]

watch_config/changelog.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class ChangeType(StrEnum):
+    ADDED = "added"
+    REMOVED = "removed"
+    UPDATED = "updated"
+    TYPE_CHANGED = "type_changed"
+
+
+@dataclass(slots=True)
+class ChangeEntry:
+    type: ChangeType
+    path: str
+    old_value: Any = None
+    new_value: Any = None
+
+
+@dataclass
+class ChangeLog:
+    entries: list[ChangeEntry] = field(default_factory=list)
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.entries
+
+    def added(self, path: str, value: Any) -> None:
+        self.entries.append(
+            ChangeEntry(
+                type=ChangeType.ADDED,
+                path=path,
+                old_value=None,
+                new_value=value,
+            )
+        )
+
+    def removed(self, path: str, value: Any) -> None:
+        self.entries.append(
+            ChangeEntry(
+                type=ChangeType.REMOVED,
+                path=path,
+                old_value=value,
+                new_value=None,
+            )
+        )
+
+    def updated(self, path: str, old_value: Any, new_value: Any) -> None:
+        self.entries.append(
+            ChangeEntry(
+                type=ChangeType.UPDATED,
+                path=path,
+                old_value=old_value,
+                new_value=new_value,
+            )
+        )
+
+    def type_changed(self, path: str, old_value: Any, new_value: Any) -> None:
+        self.entries.append(
+            ChangeEntry(
+                type=ChangeType.TYPE_CHANGED,
+                path=path,
+                old_value=old_value,
+                new_value=new_value,
+            )
+        )
+
+    def __len__(self) -> int:
+        return len(self.entries)
+
+    def __iter__(self):
+        return iter(self.entries)

watch_config/diff.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import is_dataclass
+from typing import Any
+
+from .changelog import ChangeLog
+
+
+def diff_values(
+    old: Any,
+    new: Any,
+    path: str = "$",
+    out: ChangeLog | None = None,
+) -> ChangeLog:
+    if out is None:
+        out = ChangeLog()
+
+    if type(old) is not type(new):
+        out.type_changed(path, old, new)
+        return out
+
+    if isinstance(old, dict):
+        old_keys = set(old)
+        new_keys = set(new)
+
+        for key in sorted(old_keys - new_keys, key=str):
+            out.removed(_join_path(path, key), old[key])
+
+        for key in sorted(new_keys - old_keys, key=str):
+            out.added(_join_path(path, key), new[key])
+
+        for key in sorted(old_keys & new_keys, key=str):
+            diff_values(old[key], new[key], _join_path(path, key), out)
+
+        return out
+
+    if isinstance(old, (list, tuple)):
+        common = min(len(old), len(new))
+
+        for i in range(common):
+            diff_values(old[i], new[i], f"{path}[{i}]", out)
+
+        for i in range(common, len(old)):
+            out.removed(f"{path}[{i}]", old[i])
+
+        for i in range(common, len(new)):
+            out.added(f"{path}[{i}]", new[i])
+
+        return out
+
+    if isinstance(old, (set, frozenset)):
+        if old != new:
+            out.updated(path, old, new)
+        return out
+
+    if old != new:
+        out.updated(path, old, new)
+
+    return out
+
+
+def build_object(model_type: type[Any], data: Any) -> Any:
+    payload = deepcopy(data)
+
+    if model_type is dict:
+        if not isinstance(payload, dict):
+            raise TypeError("model_type=dict 时，配置顶层必须是 dict")
+        return payload
+
+    if model_type is list:
+        if not isinstance(payload, list):
+            raise TypeError("model_type=list 时，配置顶层必须是 list")
+        return payload
+
+    if model_type is set:
+        if isinstance(payload, set):
+            return payload
+        if isinstance(payload, (list, tuple)):
+            return set(payload)
+        raise TypeError("model_type=set 时，配置顶层必须是 set/list/tuple")
+
+    if _is_pydantic_model_class(model_type):
+        return model_type.model_validate(payload)
+
+    if is_dataclass(model_type):
+        if not isinstance(payload, dict):
+            raise TypeError("dataclass 类型要求配置顶层为 dict")
+        return model_type(**payload)
+
+    if isinstance(payload, dict):
+        return model_type(**payload)
+
+    return model_type(payload)
+
+
+def _join_path(base: str, key: Any) -> str:
+    if isinstance(key, int):
+        return f"{base}[{key}]"
+    key_text = str(key)
+    if key_text.isidentifier():
+        return f"{base}.{key_text}"
+    return f"{base}[{key_text!r}]"
+
+
+def _is_pydantic_model_class(tp: Any) -> bool:
+    return hasattr(tp, "model_validate") and hasattr(tp, "model_fields")

watch_config/renderer.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import sys
+import logging
+from pprint import pformat
+from typing import Any
+from .changelog import ChangeLog, ChangeType
+from abc import ABC, abstractmethod
+
+class ChangeRenderer(ABC):
+    @abstractmethod
+    def render(self, changelog: ChangeLog) -> str: ...
+
+    def emit(self, changelog: ChangeLog, logger: logging.Logger) -> None:
+        text = self.render(changelog)
+        if text:
+            logger.info(text)
+
+
+class DefaultRenderer(ChangeRenderer):
+    _ICONS = {
+        ChangeType.ADDED: "+",
+        ChangeType.REMOVED: "-",
+        ChangeType.UPDATED: "~",
+        ChangeType.TYPE_CHANGED: "!",
+    }
+
+    _COLORS = {
+        ChangeType.ADDED: "\033[32m",
+        ChangeType.REMOVED: "\033[31m",
+        ChangeType.UPDATED: "\033[33m",
+        ChangeType.TYPE_CHANGED: "\033[35m",
+    }
+
+    _RESET = "\033[0m"
+    _BOLD = "\033[1m"
+    _DIM = "\033[2m"
+
+    def __init__(self, *, color: bool | None = None, max_value_length: int = 120) -> None:
+        if color is None:
+            color = sys.stderr.isatty()
+        self.color = color
+        self.max_value_length = max_value_length
+
+    def render(self, changelog: ChangeLog) -> str:
+        if changelog.is_empty:
+            return ""
+
+        title = self._style(
+            f"Config Changes ({len(changelog.entries)}):",
+            self._BOLD,
+        )
+        lines = [title]
+
+        for entry in changelog.entries:
+            icon = self._ICONS[entry.type]
+            color = self._COLORS[entry.type]
+            path = entry.path.removeprefix("$.").removeprefix("$")
+            lines.append(self._style(f"{icon} {path}", color))
+
+            if entry.type == ChangeType.ADDED:
+                lines.append(self._style(f"  + {self._pretty(entry.new_value)}", self._COLORS[ChangeType.ADDED]))
+            elif entry.type == ChangeType.REMOVED:
+                lines.append(self._style(f"  - {self._pretty(entry.old_value)}", self._COLORS[ChangeType.REMOVED]))
+            else:
+                lines.append(self._style(f"  - {self._pretty(entry.old_value)}", self._COLORS[ChangeType.REMOVED]))
+                lines.append(self._style(f"  + {self._pretty(entry.new_value)}", self._COLORS[ChangeType.ADDED]))
+
+        return "\n".join(lines)
+
+    def _pretty(self, value: Any) -> str:
+        text = pformat(value, compact=True, sort_dicts=False, width=88)
+        if len(text) <= self.max_value_length:
+            return text
+        return text[: self.max_value_length - 3] + "..."
+
+    def _style(self, text: str, code: str) -> str:
+        if not self.color:
+            return text
+        return f"{code}{text}{self._RESET}"
+
+    def _dim(self, text: str) -> str:
+        return self._style(text, self._DIM)

watch_config/watch_config.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+import sys
+import inspect
+import logging
+import threading
+from pathlib import Path
+from typing import Any, Callable, Generic, TypeVar
+
+from configlib import load_config
+
+from .changelog import ChangeLog
+from .diff import build_object, diff_values
+from .renderer import ChangeRenderer, DefaultRenderer
+
+if sys.platform == "win32":
+    import os
+    os.system("")
+
+logger = logging.getLogger(__name__)
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable)
+
+
+class WatchConfig(Generic[T]):
+    """
+    配置热更新器。
+
+    实例化后作为装饰器注册回调函数，
+    初次加载和每次文件变更时，回调收到一个完整的新配置对象。
+
+    用法::
+
+        watcher = WatchConfig("config.yaml", AppConfig)
+
+        @watcher
+        def on_config(cfg: AppConfig):
+            ...
+
+        watcher.start()
+    """
+
+    def __init__(
+        self,
+        file_path: str | Path,
+        model_type: type[T],
+        renderer: ChangeRenderer | None = None,
+        *,
+        interval: float = 1.0,
+        debounce: float = 0.3,
+        logger_: logging.Logger | None = None,
+    ) -> None:
+        self._file_path = Path(file_path).resolve()
+        self._model_type = model_type
+        self._renderer = renderer or DefaultRenderer()
+        self._interval = interval
+        self._debounce = debounce
+        self._logger = logger_ or logger
+
+        self._callbacks: list[Callable] = []
+        self._lock = threading.Lock()
+        self._stop_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._file_state: tuple[int, int] | None = None
+        self._raw_data: Any = None
+        self._value: T | None = None
+
+    def __call__(self, fn: F) -> F:
+        """注册回调函数。支持作为装饰器使用。
+
+        回调签名可以是：
+            fn()
+            fn(cfg)
+            fn(cfg, changelog)
+        """
+        self._callbacks.append(fn)
+        return fn
+
+    @property
+    def value(self) -> T | None:
+        """当前配置对象。start() 之前为 None。"""
+        return self._value
+
+    @property
+    def file_path(self) -> Path:
+        return self._file_path
+
+    def start(self) -> "WatchConfig[T]":
+        """加载配置 → 调用回调 → 启动文件监控线程。"""
+        if self._thread and self._thread.is_alive():
+            return self
+
+        self._load_and_notify()
+
+        self._stop_event.clear()
+        self._thread = threading.Thread(
+            target=self._watch_loop,
+            name=f"WatchConfig:{self._file_path.name}",
+            daemon=True,
+        )
+        self._thread.start()
+
+        self._logger.info("WatchConfig started: %s", self._file_path)
+        return self
+
+    def stop(self) -> None:
+        """停止文件监控。"""
+        self._stop_event.set()
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=5)
+        self._logger.info("WatchConfig stopped: %s", self._file_path)
+
+    def run(self) -> None:
+        """start + wait + stop 的快捷方式。Ctrl+C 可退出。"""
+        self.start()
+        try:
+            self.wait()
+        except KeyboardInterrupt:
+            pass
+        finally:
+            self.stop()
+
+    def wait(self) -> None:
+        """阻塞当前线程，直到 stop() 被调用。支持 Ctrl+C 中断。"""
+        while not self._stop_event.is_set():
+            self._stop_event.wait(timeout=0.1)
+
+    def reload(self) -> ChangeLog:
+        """手动触发一次重新加载。"""
+        return self._load_and_notify()
+
+    def set_path(self, file_path: str | Path) -> "WatchConfig[T]":
+        """修改配置文件路径并立即重新加载。"""
+        self._file_path = Path(file_path).resolve()
+        self._load_and_notify()
+        return self
+
+    def has_changed(self) -> bool:
+        """检查配置文件是否发生了变化。"""
+        try:
+            state = self._get_file_state()
+        except FileNotFoundError:
+            return False
+        return self._file_state is None or state != self._file_state
+
+    def _load_and_notify(self) -> ChangeLog:
+        new_data = self._read_config()
+        new_obj = build_object(self._model_type, new_data)
+        file_state = self._get_file_state()
+
+        with self._lock:
+            old_data = self._raw_data
+            self._raw_data = new_data
+            self._value = new_obj
+            self._file_state = file_state
+
+        if old_data is not None:
+            changelog = diff_values(old_data, new_data)
+        else:
+            changelog = ChangeLog()
+
+
+        if not changelog.is_empty:
+            try:
+                self._renderer.emit(changelog, self._logger)
+            except Exception:
+                self._logger.exception("Renderer failed")
+
+        for cb in self._callbacks:
+            try:
+                _call_flexible(cb, new_obj, changelog)
+            except Exception:
+                self._logger.exception("Callback %r failed", cb)
+
+        return changelog
+
+    def _watch_loop(self) -> None:
+        while not self._stop_event.is_set():
+            try:
+                if self.has_changed():
+                    if self._stop_event.wait(self._debounce):
+                        return
+
+                    if self.has_changed():
+                        try:
+                            self._load_and_notify()
+                        except Exception:
+                            self._logger.exception(
+                                "Config reload failed: %s",
+                                self._file_path,
+                            )
+            except Exception:
+                self._logger.exception("Watch loop error: %s", self._file_path)
+
+            if self._stop_event.wait(self._interval):
+                return
+
+    def _read_config(self) -> Any:
+        return load_config(str(self._file_path))
+
+    def _get_file_state(self) -> tuple[int, int]:
+        stat = self._file_path.stat()
+        return (stat.st_mtime_ns, stat.st_size)
+
+
+def _call_flexible(fn: Callable, obj: Any, changelog: ChangeLog) -> Any:
+    try:
+        sig = inspect.signature(fn)
+    except (TypeError, ValueError):
+        return fn(obj, changelog)
+
+    params = [
+        p
+        for p in sig.parameters.values()
+        if p.default is inspect.Parameter.empty
+        and p.kind
+        not in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        )
+    ]
+
+    count = len(params)
+    if count >= 2:
+        return fn(obj, changelog)
+    elif count == 1:
+        return fn(obj)
+    else:
+        return fn()