python-library-watch-config 0.1.0__tar.gz

python_library_watch_config-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+.pytest_cache/
+config.yaml
+logs/

python_library_watch_config-0.1.0/PKG-INFO

@@ -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/example/__main__.py

@@ -0,0 +1,34 @@
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+from watch_config import WatchConfig
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s - %(message)s",
+    datefmt="%H:%M:%S",
+)
+
+CONFIG_FILEPATH = Path(__file__).parent / "config.yaml"
+
+
+@dataclass
+class AppConfig:
+    host: str
+    port: int
+    debug: bool = False
+
+
+watcher = WatchConfig(CONFIG_FILEPATH, AppConfig)
+
+
+@watcher
+def on_config(cfg: AppConfig):
+    logging.getLogger(__name__).info(
+        "Config loaded: host=%s, port=%s, debug=%s",
+        cfg.host, cfg.port, cfg.debug,
+    )
+
+
+watcher.run()

python_library_watch_config-0.1.0/example.bat

@@ -0,0 +1,11 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+
+python example

python_library_watch_config-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-watch-config"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "python-library-configlib",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["watch_config"]
+
+[tool.hatch.metadata]
+allow-direct-references = true

python_library_watch_config-0.1.0/test.bat

@@ -0,0 +1,10 @@
+@echo off
+cd /d %~dp0
+
+if not exist .venv (
+    python -m venv .venv
+)
+
+call .venv\Scripts\activate.bat
+python -m pip install -e .
+python -m unittest discover -s tests -p "test_*.py"

python_library_watch_config-0.1.0/tests/test_changelog.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import unittest
+
+from watch_config import ChangeEntry, ChangeLog, ChangeType
+
+
+class ChangeLogTests(unittest.TestCase):
+    def test_is_empty_true_when_no_entries(self) -> None:
+        log = ChangeLog()
+        self.assertTrue(log.is_empty)
+        self.assertEqual(len(log), 0)
+
+    def test_added_removed_updated_type_changed(self) -> None:
+        log = ChangeLog()
+        log.added("$.a", 1)
+        log.removed("$.b", 2)
+        log.updated("$.c", 0, 9)
+        log.type_changed("$.d", "x", 1)
+
+        self.assertFalse(log.is_empty)
+        self.assertEqual(len(log), 4)
+
+        types = [e.type for e in log.entries]
+        self.assertEqual(
+            types,
+            [
+                ChangeType.ADDED,
+                ChangeType.REMOVED,
+                ChangeType.UPDATED,
+                ChangeType.TYPE_CHANGED,
+            ],
+        )
+
+        self.assertEqual(log.entries[0].path, "$.a")
+        self.assertIsNone(log.entries[0].old_value)
+        self.assertEqual(log.entries[0].new_value, 1)
+
+        self.assertEqual(log.entries[1].old_value, 2)
+        self.assertIsNone(log.entries[1].new_value)
+
+        self.assertEqual(log.entries[2].old_value, 0)
+        self.assertEqual(log.entries[2].new_value, 9)
+
+        self.assertEqual(log.entries[3].old_value, "x")
+        self.assertEqual(log.entries[3].new_value, 1)
+
+    def test_iter_yields_entries(self) -> None:
+        log = ChangeLog()
+        log.added("$.x", 1)
+        iterated = list(log)
+        self.assertEqual(len(iterated), 1)
+        self.assertIsInstance(iterated[0], ChangeEntry)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_library_watch_config-0.1.0/tests/test_diff.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import unittest
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from watch_config import ChangeType
+from watch_config.diff import build_object, diff_values
+
+
+class DiffValuesTests(unittest.TestCase):
+    def test_identical_primitives_empty(self) -> None:
+        log = diff_values(1, 1)
+        self.assertTrue(log.is_empty)
+
+    def test_primitive_updated(self) -> None:
+        log = diff_values(1, 2)
+        self.assertEqual(len(log), 1)
+        e = log.entries[0]
+        self.assertEqual(e.type, ChangeType.UPDATED)
+        self.assertEqual(e.path, "$")
+        self.assertEqual(e.old_value, 1)
+        self.assertEqual(e.new_value, 2)
+
+    def test_type_changed(self) -> None:
+        log = diff_values(1, "1")
+        self.assertEqual(len(log), 1)
+        self.assertEqual(log.entries[0].type, ChangeType.TYPE_CHANGED)
+
+    def test_dict_key_added_removed_updated(self) -> None:
+        old = {"a": 1, "b": 2}
+        new = {"a": 10, "c": 3}
+        log = diff_values(old, new)
+        paths = {(e.type, e.path) for e in log.entries}
+        self.assertIn((ChangeType.UPDATED, "$.a"), paths)
+        self.assertIn((ChangeType.REMOVED, "$.b"), paths)
+        self.assertIn((ChangeType.ADDED, "$.c"), paths)
+
+    def test_list_length_change(self) -> None:
+        log = diff_values([1, 2], [1])
+        types_paths = [(e.type, e.path) for e in log.entries]
+        self.assertIn((ChangeType.REMOVED, "$[1]"), types_paths)
+
+    def test_list_item_updated(self) -> None:
+        log = diff_values([1, 2], [1, 3])
+        self.assertEqual(len(log), 1)
+        self.assertEqual(log.entries[0].path, "$[1]")
+        self.assertEqual(log.entries[0].type, ChangeType.UPDATED)
+
+    def test_tuple_treated_as_sequence(self) -> None:
+        log = diff_values((1,), (1, 2))
+        added = [e for e in log.entries if e.type == ChangeType.ADDED]
+        self.assertEqual(len(added), 1)
+        self.assertEqual(added[0].path, "$[1]")
+
+    def test_set_unequal_single_updated(self) -> None:
+        log = diff_values({1, 2}, {1, 3})
+        self.assertEqual(len(log), 1)
+        self.assertEqual(log.entries[0].type, ChangeType.UPDATED)
+
+    def test_set_equal_empty(self) -> None:
+        log = diff_values({1}, {1})
+        self.assertTrue(log.is_empty)
+
+    def test_nested_dict_non_identifier_key_in_path(self) -> None:
+        old = {"a-b": 1}
+        new = {"a-b": 2}
+        log = diff_values(old, new)
+        self.assertTrue(any("a-b" in e.path for e in log.entries))
+
+    def test_reuses_out_parameter(self) -> None:
+        from watch_config import ChangeLog
+
+        out = ChangeLog()
+        diff_values({"x": 1}, {"x": 2}, out=out)
+        self.assertFalse(out.is_empty)
+
+
+@dataclass
+class SampleDC:
+    name: str
+    count: int
+
+
+class SampleModel(BaseModel):
+    name: str
+    count: int = 0
+
+
+class BuildObjectTests(unittest.TestCase):
+    def test_dict_model_requires_dict_payload(self) -> None:
+        self.assertEqual(build_object(dict, {"a": 1}), {"a": 1})
+        with self.assertRaises(TypeError):
+            build_object(dict, [])
+
+    def test_list_model(self) -> None:
+        self.assertEqual(build_object(list, [1, 2]), [1, 2])
+        with self.assertRaises(TypeError):
+            build_object(list, {})
+
+    def test_set_model_from_list(self) -> None:
+        self.assertEqual(build_object(set, [1, 2]), {1, 2})
+
+    def test_set_model_from_set(self) -> None:
+        self.assertEqual(build_object(set, {1}), {1})
+
+    def test_set_model_invalid_payload(self) -> None:
+        with self.assertRaises(TypeError):
+            build_object(set, "nope")
+
+    def test_dataclass_from_dict(self) -> None:
+        obj = build_object(SampleDC, {"name": "x", "count": 3})
+        self.assertIsInstance(obj, SampleDC)
+        self.assertEqual(obj.name, "x")
+        self.assertEqual(obj.count, 3)
+
+    def test_dataclass_requires_dict(self) -> None:
+        with self.assertRaises(TypeError):
+            build_object(SampleDC, [])
+
+    def test_pydantic_model_validate(self) -> None:
+        obj = build_object(SampleModel, {"name": "p", "count": 5})
+        self.assertIsInstance(obj, SampleModel)
+        self.assertEqual(obj.name, "p")
+        self.assertEqual(obj.count, 5)
+
+    def test_plain_class_kwargs_from_dict(self) -> None:
+        class Box:
+            def __init__(self, w: int, h: int) -> None:
+                self.w = w
+                self.h = h
+
+        obj = build_object(Box, {"w": 2, "h": 3})
+        self.assertEqual(obj.w, 2)
+        self.assertEqual(obj.h, 3)
+
+    def test_plain_callable_payload(self) -> None:
+        obj = build_object(int, "42")
+        self.assertEqual(obj, 42)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_library_watch_config-0.1.0/tests/test_renderer.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import logging
+import unittest
+
+from watch_config import ChangeLog, ChangeType, DefaultRenderer
+
+
+class DefaultRendererTests(unittest.TestCase):
+    def test_empty_changelog_returns_empty_string(self) -> None:
+        r = DefaultRenderer(color=False)
+        self.assertEqual(r.render(ChangeLog()), "")
+
+    def test_render_contains_paths_and_icons(self) -> None:
+        log = ChangeLog()
+        log.added("$.foo", {"k": 1})
+        log.removed("$.bar", 2)
+        log.updated("$.baz", 0, 1)
+
+        r = DefaultRenderer(color=False, max_value_length=200)
+        text = r.render(log)
+
+        self.assertIn("Config Changes (3):", text)
+        self.assertIn("+ foo", text)
+        self.assertIn("- bar", text)
+        self.assertIn("~ baz", text)
+
+    def test_emit_logs_when_non_empty(self) -> None:
+        log = ChangeLog()
+        log.added("$.x", 1)
+        r = DefaultRenderer(color=False)
+        logger = logging.getLogger("test_renderer_emit")
+        logger.setLevel(logging.INFO)
+        with self.assertLogs(logger, level="INFO") as cm:
+            r.emit(log, logger)
+        self.assertTrue(any("Config Changes" in rec.message for rec in cm.records))
+
+    def test_emit_skips_empty_string(self) -> None:
+        r = DefaultRenderer(color=False)
+        logger = logging.getLogger("test_renderer_emit_empty")
+        logger.setLevel(logging.INFO)
+        with self.assertLogs(logger, level="INFO") as cm:
+            logger.info("marker")
+            r.emit(ChangeLog(), logger)
+        self.assertEqual(len(cm.records), 1)
+        self.assertIn("marker", cm.records[0].getMessage())
+
+    def test_long_value_truncated(self) -> None:
+        log = ChangeLog()
+        log.added("$.v", "x" * 100)
+        r = DefaultRenderer(color=False, max_value_length=20)
+        text = r.render(log)
+        self.assertIn("...", text)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_library_watch_config-0.1.0/tests/test_watch_config.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import logging
+import time
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from typing import Any
+
+from watch_config import ChangeLog, ChangeRenderer, WatchConfig
+
+
+class BoomRenderer(ChangeRenderer):
+    def render(self, changelog: ChangeLog) -> str:
+        raise RuntimeError("render boom")
+
+
+class WatchConfigTests(unittest.TestCase):
+    def _write_yaml(self, path: Path, content: str) -> None:
+        path.write_text(content.strip() + "\n", encoding="utf-8")
+
+    def test_start_loads_file_and_sets_value(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "cfg.yaml"
+            self._write_yaml(p, "x: 1\ny: two")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            try:
+                w.start()
+                self.assertIsNotNone(w.value)
+                self.assertEqual(w.value, {"x": 1, "y": "two"})
+                self.assertEqual(w.file_path, p.resolve())
+            finally:
+                w.stop()
+
+    def test_decorator_registers_callbacks(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "n: 0")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            seen: list[tuple[Any, ChangeLog]] = []
+
+            @w
+            def cb(cfg: dict, changelog: ChangeLog) -> None:
+                seen.append((dict(cfg), changelog))
+
+            try:
+                w.start()
+                self.assertEqual(len(seen), 1)
+                self.assertEqual(seen[0][0], {"n": 0})
+                self.assertTrue(seen[0][1].is_empty)
+            finally:
+                w.stop()
+
+    def test_callback_zero_or_one_arg(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "a: 1")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            calls: list[str] = []
+
+            @w
+            def cb0() -> None:
+                calls.append("0")
+
+            @w
+            def cb1(cfg: dict) -> None:
+                calls.append("1")
+
+            try:
+                w.start()
+                self.assertEqual(sorted(calls), ["0", "1"])
+            finally:
+                w.stop()
+
+    def test_reload_after_file_change_non_empty_changelog(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "k: 1")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            try:
+                w.start()
+                self._write_yaml(p, "k: 2")
+                time.sleep(0.05)
+                log = w.reload()
+                self.assertFalse(log.is_empty)
+                self.assertEqual(w.value, {"k": 2})
+            finally:
+                w.stop()
+
+    def test_set_path_reloads(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p1 = Path(tmp) / "a.yaml"
+            p2 = Path(tmp) / "b.yaml"
+            self._write_yaml(p1, "u: 1")
+            self._write_yaml(p2, "u: 2")
+            w = WatchConfig(p1, dict, interval=0.05, debounce=0.05)
+            try:
+                w.start()
+                self.assertEqual(w.value, {"u": 1})
+                w.set_path(p2)
+                self.assertEqual(w.file_path, p2.resolve())
+                self.assertEqual(w.value, {"u": 2})
+            finally:
+                w.stop()
+
+    def test_has_changed_false_when_missing(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "missing.yaml"
+            w = WatchConfig(p, dict)
+            self.assertFalse(w.has_changed())
+
+    def test_has_changed_after_write(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "a: 1")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            try:
+                w.start()
+                self.assertFalse(w.has_changed())
+                self._write_yaml(p, "a: 2")
+                self.assertTrue(w.has_changed())
+            finally:
+                w.stop()
+
+    def test_double_start_is_idempotent(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "z: 1")
+            w = WatchConfig(p, dict, interval=0.05, debounce=0.05)
+            try:
+                w.start()
+                t1 = w._thread
+                w.start()
+                self.assertIs(w._thread, t1)
+            finally:
+                w.stop()
+
+    def test_renderer_failure_still_invokes_callbacks(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "c.yaml"
+            self._write_yaml(p, "q: 1")
+            logger = logging.getLogger("test_watch_renderer_fail")
+            logger.handlers.clear()
+            logger.addHandler(logging.NullHandler())
+            logger.propagate = False
+            logger.setLevel(logging.ERROR)
+            w = WatchConfig(
+                p,
+                dict,
+                renderer=BoomRenderer(),
+                interval=0.05,
+                debounce=0.05,
+                logger_=logger,
+            )
+            ok: list[bool] = []
+
+            @w
+            def cb(cfg: dict) -> None:
+                ok.append(True)
+
+            try:
+                w.start()
+                self._write_yaml(p, "q: 2")
+                w.reload()
+                self.assertEqual(ok, [True, True])
+            finally:
+                w.stop()
+
+    def test_reload_raises_propagates_to_caller(self) -> None:
+        with TemporaryDirectory() as tmp:
+            p = Path(tmp) / "bad.yaml"
+            p.write_text("{ not yaml", encoding="utf-8")
+            w = WatchConfig(p, dict)
+            with self.assertRaises(Exception):
+                w.reload()
+
+
+if __name__ == "__main__":
+    unittest.main()

python_library_watch_config-0.1.0/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",
+]

python_library_watch_config-0.1.0/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)

python_library_watch_config-0.1.0/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")

python_library_watch_config-0.1.0/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)

python_library_watch_config-0.1.0/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()