python-library-configlib 0.1.0__tar.gz

python_library_configlib-0.1.0/.gitignore

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

python_library_configlib-0.1.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: python-library-configlib
+Version: 0.1.0
+Requires-Python: >=3.10
+Requires-Dist: json5>=0.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'

python_library_configlib-0.1.0/assets/base.yaml

@@ -0,0 +1,3 @@
+title: hello
+nested:
+  value: 123

python_library_configlib-0.1.0/assets/data.json5

@@ -0,0 +1,6 @@
+{
+    user: {
+      name: "alice",
+      age: 18,
+    },
+  }

python_library_configlib-0.1.0/assets/data.toml

@@ -0,0 +1,3 @@
+[server]
+host = "127.0.0.1"
+port = 8080

python_library_configlib-0.1.0/assets/example.yaml

@@ -0,0 +1,14 @@
+app:
+  name: demo
+  version: "1.0"
+
+base: !include base.yaml
+json_data: !include data.json5
+toml_data: !include data.toml
+
+refs:
+  app_name: ${app.name}
+  base_title: ${base.title}
+  local:
+    name: child
+    parent_name: ${..name}

python_library_configlib-0.1.0/configlib/__init__.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+from .loader import ConfigLoader
+from .json import is_json, load_json, load_json_raw
+from .toml import is_toml, load_toml, load_toml_raw
+from .yaml import is_yaml, load_yaml, load_yaml_raw
+
+
+def load_config_raw(file_path: str | Path) -> dict | list:
+    """加载配置文件（不解析变量）"""
+    file_path = str(file_path)
+    if is_json(file_path):
+        return load_json_raw(file_path)
+    elif is_toml(file_path):
+        return load_toml_raw(file_path)
+    elif is_yaml(file_path):
+        return load_yaml_raw(file_path)
+    else:
+        raise ValueError(f"不支持的文件格式: {file_path}")
+
+
+def load_config(file_path: str | Path) -> dict | list:
+    """加载配置文件"""
+    file_path = str(file_path)
+    if is_json(file_path):
+        return load_json(file_path)
+    elif is_toml(file_path):
+        return load_toml(file_path)
+    elif is_yaml(file_path):
+        return load_yaml(file_path)
+    else:
+        raise ValueError(f"不支持的文件格式: {file_path}")
+
+__all__ = [
+    "load_config",
+    "load_config_raw",
+    "ConfigLoader",
+]

python_library_configlib-0.1.0/configlib/json.py

@@ -0,0 +1,22 @@
+import json5
+import os
+
+from .resolver import resolve_variables
+
+SUFFIXES = {'.json', '.json5'}
+
+
+def is_json(file_path: str) -> bool:
+    return os.path.splitext(file_path)[1] in SUFFIXES
+
+
+def load_json(file_path: str) -> dict | list:
+    with open(file_path, 'r', encoding='utf-8') as f:
+        data = json5.load(f)
+    return resolve_variables(data)
+
+def load_json_raw(file_path: str) -> dict | list:
+    with open(file_path, 'r', encoding='utf-8') as f:
+        return json5.load(f)
+
+__all__ = ['is_json', 'load_json', 'load_json_raw']

python_library_configlib-0.1.0/configlib/loader.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+import inspect
+from pathlib import Path
+from typing import Callable
+from pydantic import BaseModel, ConfigDict, PrivateAttr
+from typing import TypeVar
+T = TypeVar("T", bound="ConfigLoader")
+
+ReloadCallback = Callable[..., None]
+
+
+class ConfigLoader(BaseModel):
+    model_config = ConfigDict(validate_assignment=True)
+
+    _file_path: Path | None = PrivateAttr(default=None)
+    _on_update: ReloadCallback | None = PrivateAttr(default=None)
+    _file_state: tuple[int, int] | None = PrivateAttr(default=None)
+
+    @classmethod
+    def from_file(
+        cls: type[T],
+        file_path: str | Path,
+        on_update: ReloadCallback | None = None,
+    ) -> T:
+        path = Path(file_path).resolve()
+        if not path.exists():
+            raise FileNotFoundError(f"配置文件 {path} 不存在")
+
+        data = cls._load_dict(path)
+
+        obj = cls.model_validate(data)
+        obj._file_path = path
+        obj._on_update = on_update
+        obj._file_state = obj._get_file_state()
+        return obj
+
+    @staticmethod
+    def _load_dict(path: Path) -> dict:
+        from . import load_config
+        data = load_config(str(path))
+        if not isinstance(data, dict):
+            raise TypeError(f"配置顶层必须是 dict，实际得到 {type(data).__name__}")
+        return data
+
+    def _get_file_state(self) -> tuple[int, int]:
+        """获取文件状态"""
+        if self._file_path is None:
+            raise RuntimeError("此实例未绑定配置文件，请使用 from_file() 创建")
+        stat = self._file_path.stat()
+        return (stat.st_mtime_ns, stat.st_size)
+
+    def has_changed(self) -> bool:
+        """判断配置文件是否发生变化（纯查询，不更新内部状态）"""
+        if self._file_path is None:
+            return False
+        return self._file_state is None or self._file_state != self._get_file_state()
+
+    def reload(self) -> bool:
+        """重新加载配置文件"""
+        if not self.has_changed():
+            return False
+
+        data = self._load_dict(self._file_path)
+
+        old = self.model_copy(deep=True)
+        new_obj = self.__class__.model_validate(data)
+
+        for field_name in self.__class__.model_fields:
+            setattr(self, field_name, getattr(new_obj, field_name))
+
+        self._file_state = self._get_file_state()
+        self._call_update_callback(old)
+
+        return True
+
+    def _call_update_callback(self, old: "ConfigLoader") -> None:
+        """调用更新回调函数"""
+        if self._on_update is None:
+            return
+        callback = self._on_update
+        try:
+            sig = inspect.signature(callback)
+        except (ValueError, TypeError):
+            for args in [(self, old), (self,), ()]:
+                try:
+                    callback(*args)
+                    return
+                except TypeError:
+                    continue
+            raise TypeError(f"无法调用回调函数 {callback!r}，请检查其参数签名")
+
+        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)
+        ]
+        if len(params) >= 2:
+            callback(self, old)
+        elif len(params) == 1:
+            callback(self)
+        else:
+            callback()
+
+__all__ = ["ConfigLoader"]

python_library_configlib-0.1.0/configlib/resolver.py

@@ -0,0 +1,218 @@
+from __future__ import annotations
+
+import os
+import re
+from typing import Any
+
+_VAR_PATTERN = re.compile(r"\$\{([^{}]+)\}")
+
+_SENTINEL = object()
+
+
+def resolve_variables(data: Any) -> Any:
+    """对已加载的配置数据进行 ${} 变量解析。"""
+    return _VariableResolver(data).resolve()
+
+
+def _auto_convert(value: str) -> str | int | float | bool | None:
+    """将字符串自动转换为合适的 Python 类型。"""
+    lower = value.strip().lower()
+    if lower in ("true", "yes", "on"):
+        return True
+    if lower in ("false", "no", "off"):
+        return False
+    if lower in ("null", "none", "~"):
+        return None
+    try:
+        return int(value)
+    except ValueError:
+        pass
+    try:
+        return float(value)
+    except ValueError:
+        pass
+    return value
+
+
+class _VariableResolver:
+    """
+    解析三种变量语法：
+      - ${key.path}     绝对路径引用
+      - ${..key}        相对路径引用
+      - ${env:NAME}     显式环境变量
+      - ${env:NAME:默认值}  带默认值的环境变量
+    以及隐式回退：单级 ${KEY} 在配置中找不到时，自动查找同名环境变量。
+    """
+
+    def __init__(self, root: Any):
+        self.root = root
+        self._cache: dict[tuple[Any, ...], Any] = {}
+        self._resolving: set[tuple[Any, ...]] = set()
+
+    def resolve(self) -> Any:
+        return self._resolve_at(())
+
+    def _resolve_at(self, path: tuple[Any, ...]) -> Any:
+        if path in self._cache:
+            return self._cache[path]
+        if path in self._resolving:
+            raise ValueError(f"检测到循环变量引用: {self._format_path(path)}")
+
+        self._resolving.add(path)
+        try:
+            node = self._get_node(path)
+            resolved = self._resolve_node(node, path)
+            self._cache[path] = resolved
+            return resolved
+        finally:
+            self._resolving.remove(path)
+
+    def _resolve_node(self, node: Any, path: tuple[Any, ...]) -> Any:
+        if isinstance(node, dict):
+            return {key: self._resolve_at(path + (key,)) for key in node}
+        if isinstance(node, list):
+            return [self._resolve_at(path + (index,)) for index, _ in enumerate(node)]
+        if isinstance(node, str):
+            return self._resolve_string(node, path)
+        return node
+
+    def _resolve_string(self, value: str, path: tuple[Any, ...]) -> Any:
+        full_match = _VAR_PATTERN.fullmatch(value)
+        if full_match:
+            expr = full_match.group(1)
+            env_result = self._try_resolve_env(expr)
+            if env_result is not _SENTINEL:
+                return env_result
+            target_path = self._resolve_reference(expr, path)
+            return self._resolve_at(target_path)
+
+        def replace(match: re.Match[str]) -> str:
+            expr = match.group(1)
+            env_result = self._try_resolve_env(expr)
+            if env_result is not _SENTINEL:
+                return str(env_result)
+            target_path = self._resolve_reference(expr, path)
+            return str(self._resolve_at(target_path))
+
+        return _VAR_PATTERN.sub(replace, value)
+
+    def _try_resolve_env(self, expr: str) -> Any:
+        """解析 env:VAR 或 env:VAR:default。不匹配 env: 前缀则返回 _SENTINEL。"""
+        expr = expr.strip()
+        if not expr.startswith("env:"):
+            return _SENTINEL
+
+        rest = expr[4:]
+        colon_pos = rest.find(":")
+        if colon_pos == -1:
+            env_name = rest.strip()
+            default = _SENTINEL
+        else:
+            env_name = rest[:colon_pos].strip()
+            default = rest[colon_pos + 1:]
+
+        if not env_name:
+            raise ValueError("环境变量名不能为空: ${env:}")
+
+        value = os.environ.get(env_name)
+        if value is not None:
+            return _auto_convert(value)
+        if default is not _SENTINEL:
+            return _auto_convert(default)
+        raise KeyError(f"环境变量不存在: {env_name}")
+
+    # ---- 配置内引用 ----
+
+    def _resolve_reference(self, expr: str, current_path: tuple[Any, ...]) -> tuple[Any, ...]:
+        expr = expr.strip()
+        if not expr:
+            raise ValueError("变量表达式不能为空")
+        if expr.startswith("."):
+            return self._resolve_relative_path(expr, current_path)
+        return self._split_path(expr)
+
+    def _resolve_relative_path(
+        self,
+        expr: str,
+        current_path: tuple[Any, ...],
+    ) -> tuple[Any, ...]:
+        dot_count = 0
+        while dot_count < len(expr) and expr[dot_count] == ".":
+            dot_count += 1
+
+        if dot_count < 2 or dot_count % 2 != 0:
+            raise ValueError(f"不支持的相对路径变量: {expr}")
+
+        remainder = expr[dot_count:]
+        if remainder.startswith(".") or not remainder:
+            raise ValueError(f"不支持的相对路径变量: {expr}")
+
+        up_levels = dot_count // 2
+        mapping_paths = self._get_mapping_paths(current_path)
+        if len(mapping_paths) < up_levels:
+            raise ValueError(f"相对路径越界: {expr}，当前位置 {self._format_path(current_path)}")
+        base_path = mapping_paths[-up_levels]
+        return base_path + self._split_path(remainder)
+
+    def _get_mapping_paths(self, current_path: tuple[Any, ...]) -> list[tuple[Any, ...]]:
+        mapping_paths: list[tuple[Any, ...]] = []
+        node = self.root
+        walked: list[Any] = []
+
+        if isinstance(node, dict):
+            mapping_paths.append(())
+
+        for key in current_path[:-1]:
+            if isinstance(node, dict):
+                node = node[key]
+            elif isinstance(node, list):
+                node = node[key]
+            else:
+                break
+            walked.append(key)
+            if isinstance(node, dict):
+                mapping_paths.append(tuple(walked))
+
+        return mapping_paths
+
+    def _split_path(self, expr: str) -> tuple[Any, ...]:
+        parts = [part.strip() for part in expr.split(".")]
+        if any(not part for part in parts):
+            raise ValueError(f"无效的变量路径: {expr}")
+
+        result: list[Any] = []
+        for part in parts:
+            if part.isdigit():
+                result.append(int(part))
+            else:
+                result.append(part)
+        return tuple(result)
+
+    def _get_node(self, path: tuple[Any, ...]) -> Any:
+        node = self.root
+        for key in path:
+            try:
+                node = node[key]
+            except (KeyError, IndexError, TypeError):
+                if isinstance(key, int) and isinstance(node, dict):
+                    try:
+                        node = node[str(key)]
+                        continue
+                    except KeyError:
+                        pass
+                if len(path) == 1 and isinstance(path[0], str):
+                    env_val = os.environ.get(path[0])
+                    if env_val is not None:
+                        return _auto_convert(env_val)
+                raise KeyError(f"变量引用不存在: {self._format_path(path)}")
+        return node
+
+    def _format_path(self, path: tuple[Any, ...]) -> str:
+        if not path:
+            return "<root>"
+        return ".".join(str(part) for part in path)
+
+
+__all__ = [
+    "resolve_variables",
+]

python_library_configlib-0.1.0/configlib/toml.py

@@ -0,0 +1,25 @@
+import os
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+from .resolver import resolve_variables
+
+SUFFIXES = {'.toml'}
+
+
+def is_toml(file_path: str) -> bool:
+    return os.path.splitext(file_path)[1] in SUFFIXES
+
+
+def load_toml(file_path: str) -> dict:
+    with open(file_path, "rb") as f:
+        data = tomllib.load(f)
+    return resolve_variables(data)
+
+def load_toml_raw(file_path: str) -> dict:
+    with open(file_path, "rb") as f:
+        return tomllib.load(f)
+
+__all__ = ['is_toml', 'load_toml', 'load_toml_raw']

python_library_configlib-0.1.0/configlib/yaml.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+import os
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any
+import yaml
+from .resolver import resolve_variables
+
+SUFFIXES = {".yaml", ".yml"}
+_YAML_LOAD_STACK: ContextVar[list[Path] | None] = ContextVar("_YAML_LOAD_STACK", default=None)
+
+
+@contextmanager
+def _include_guard(path: Path):
+    """管理 include 循环检测栈，顶层调用结束后复位。"""
+    stack = _YAML_LOAD_STACK.get()
+    is_top_level = stack is None
+    if is_top_level:
+        stack = []
+        _YAML_LOAD_STACK.set(stack)
+
+    if path in stack:
+        chain = " -> ".join(str(item) for item in [*stack, path])
+        raise ValueError(f"检测到循环 include: {chain}")
+
+    stack.append(path)
+    try:
+        yield
+    finally:
+        stack.pop()
+        if is_top_level:
+            _YAML_LOAD_STACK.set(None)
+
+
+def is_yaml(file_path: str) -> bool:
+    return os.path.splitext(file_path)[1] in SUFFIXES
+
+
+def load_yaml(file_path: str) -> dict | list:
+    path = Path(file_path).resolve()
+    with _include_guard(path):
+        data = _load_yaml_raw(path)
+        return resolve_variables(data)
+
+
+def load_yaml_raw(file_path: str) -> dict | list:
+    """加载 YAML 但不解析变量（供 include 使用）"""
+    path = Path(file_path).resolve()
+    with _include_guard(path):
+        return _load_yaml_raw(path)
+
+
+def _load_yaml_raw(path: Path) -> Any:
+    class _YamlIncludeLoader(yaml.SafeLoader):
+        pass
+
+    def construct_include(loader: _YamlIncludeLoader, node: yaml.Node) -> Any:
+        relative_path = loader.construct_scalar(node)
+        target_path = (path.parent / relative_path).resolve()
+        from . import load_config_raw
+        return load_config_raw(str(target_path))
+
+    _YamlIncludeLoader.add_constructor("!include", construct_include)
+
+    with path.open("r", encoding="utf-8") as f:
+        return yaml.load(f, Loader=_YamlIncludeLoader)
+
+
+__all__ = ["is_yaml", "load_yaml", "load_yaml_raw"]

python_library_configlib-0.1.0/pyproject.toml

@@ -0,0 +1,17 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "python-library-configlib"
+version = "0.1.0"
+requires-python = ">=3.10"
+dependencies = [
+    "pydantic>=2.0.0",
+    "json5>=0.9.0",
+    "PyYAML>=6.0.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["configlib"]

python_library_configlib-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_configlib-0.1.0/tests/test_json.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from configlib.json import is_json, load_json, load_json_raw
+
+
+class JsonHelpersTests(unittest.TestCase):
+    def test_is_json_suffixes(self) -> None:
+        self.assertTrue(is_json("app.json"))
+        self.assertTrue(is_json(r"C:\x\config.json5"))
+        self.assertFalse(is_json("x.yaml"))
+        self.assertFalse(is_json("noext"))
+
+    def test_load_json_resolves_full_placeholder(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "c.json5"
+            path.write_text(
+                '{"port": 8080, "label": "${port}"}',
+                encoding="utf-8",
+            )
+            data = load_json(str(path))
+            self.assertEqual(data["label"], 8080)
+
+    def test_load_json_raw_skips_resolution(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "c.json5"
+            path.write_text(
+                '{"x": "${y}", "y": 1}',
+                encoding="utf-8",
+            )
+            data = load_json_raw(str(path))
+            self.assertEqual(data["x"], "${y}")
+
+    def test_load_json_interpolates_in_string(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "c.json5"
+            path.write_text(
+                '{"host": "127.0.0.1", "dsn": "postgres://${host}/db"}',
+                encoding="utf-8",
+            )
+            data = load_json(str(path))
+            self.assertEqual(data["dsn"], "postgres://127.0.0.1/db")

python_library_configlib-0.1.0/tests/test_load_config.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from configlib import load_config, load_config_raw
+
+
+class LoadConfigDispatchTests(unittest.TestCase):
+    def test_unsupported_extension_raises(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.txt"
+            path.write_text("{}", encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "不支持的文件格式"):
+                load_config(path)
+            with self.assertRaisesRegex(ValueError, "不支持的文件格式"):
+                load_config_raw(path)
+
+    def test_load_config_accepts_path_object(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        path = base_dir / "assets" / "example.yaml"
+        self.assertIsInstance(load_config(path), dict)
+
+    def test_raw_does_not_resolve_variables(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        path = base_dir / "assets" / "example.yaml"
+        data = load_config_raw(path)
+        self.assertEqual(data["refs"]["app_name"], "${app.name}")
+
+    def test_resolved_matches_full_tree(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        resolved = load_config(base_dir / "assets" / "example.yaml")
+        raw = load_config_raw(base_dir / "assets" / "example.yaml")
+        self.assertNotEqual(resolved["refs"]["app_name"], raw["refs"]["app_name"])
+        self.assertEqual(resolved["refs"]["app_name"], "demo")

python_library_configlib-0.1.0/tests/test_loader.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+from configlib import ConfigLoader
+
+
+class AppConfig(ConfigLoader):
+    name: str = ""
+    port: int = 0
+    debug: bool = False
+
+
+def _write_text(path: Path, text: str) -> None:
+    path.write_text(text, encoding="utf-8")
+
+
+class ConfiglibLoaderTests(unittest.TestCase):
+    def test_reload_and_on_update(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            config_path = root / "config.json5"
+
+            _write_text(
+                config_path,
+                """{
+  name: "demo",
+  port: 8080,
+  debug: false,
+}""",
+            )
+
+            called: list[tuple[str, int, bool]] = []
+
+            def on_update(cfg: AppConfig) -> None:
+                called.append((cfg.name, cfg.port, cfg.debug))
+
+            cfg = AppConfig.from_file(
+                file_path=str(config_path),
+                on_update=on_update,
+            )
+
+            self.assertEqual(cfg.name, "demo")
+            self.assertEqual(cfg.port, 8080)
+            self.assertIs(cfg.debug, False)
+
+            self.assertIs(cfg.reload(), False)
+            self.assertEqual(called, [])
+
+            time.sleep(0.01)
+            _write_text(
+                config_path,
+                """{
+  name: "demo2",
+  port: 9090,
+  debug: true,
+}""",
+            )
+
+            self.assertIs(cfg.reload(), True)
+            self.assertEqual(cfg.name, "demo2")
+            self.assertEqual(cfg.port, 9090)
+            self.assertIs(cfg.debug, True)
+            self.assertEqual(called, [("demo2", 9090, True)])
+
+    def test_from_file_missing_raises(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            missing = Path(tmp) / "nope.json5"
+            with self.assertRaises(FileNotFoundError):
+                AppConfig.from_file(missing)
+
+    def test_from_file_rejects_non_dict_top_level(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "list.json5"
+            _write_text(path, "[1, 2, 3]")
+            with self.assertRaisesRegex(TypeError, "配置顶层必须是 dict"):
+                AppConfig.from_file(path)
+
+    def test_has_changed_detects_modification(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            config_path = root / "config.json5"
+            _write_text(
+                config_path,
+                """{ name: "a", port: 1, debug: false }""",
+            )
+            cfg = AppConfig.from_file(config_path)
+            self.assertFalse(cfg.has_changed())
+            time.sleep(0.01)
+            _write_text(
+                config_path,
+                """{ name: "b", port: 2, debug: true }""",
+            )
+            self.assertTrue(cfg.has_changed())
+
+    def test_on_update_two_arg_receives_old_snapshot(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            config_path = root / "config.json5"
+            _write_text(
+                config_path,
+                """{ name: "first", port: 1, debug: false }""",
+            )
+            events: list[tuple[str, str]] = []
+
+            def on_update(new: AppConfig, old: AppConfig) -> None:
+                events.append((new.name, old.name))
+
+            cfg = AppConfig.from_file(config_path, on_update=on_update)
+            time.sleep(0.01)
+            _write_text(
+                config_path,
+                """{ name: "second", port: 1, debug: false }""",
+            )
+            self.assertTrue(cfg.reload())
+            self.assertEqual(events, [("second", "first")])
+
+    def test_on_update_zero_arg(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            config_path = root / "config.json5"
+            _write_text(config_path, """{ name: "x", port: 1, debug: false }""")
+            count = 0
+
+            def on_update() -> None:
+                nonlocal count
+                count += 1
+
+            cfg = AppConfig.from_file(config_path, on_update=on_update)
+            time.sleep(0.01)
+            _write_text(config_path, """{ name: "y", port: 1, debug: false }""")
+            self.assertTrue(cfg.reload())
+            self.assertEqual(count, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

python_library_configlib-0.1.0/tests/test_resolver.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import os
+import unittest
+from unittest.mock import patch
+
+from configlib.resolver import resolve_variables
+
+
+class ResolverTests(unittest.TestCase):
+    def test_pass_through_non_string_nodes(self) -> None:
+        self.assertIsNone(resolve_variables(None))
+        self.assertEqual(resolve_variables(42), 42)
+        self.assertEqual(resolve_variables([1, {"a": 2}]), [1, {"a": 2}])
+
+    def test_full_placeholder_resolves_sibling(self) -> None:
+        data = {"a": 1, "b": "${a}"}
+        self.assertEqual(resolve_variables(data)["b"], 1)
+
+    def test_nested_path(self) -> None:
+        data = {"x": {"y": "ok"}, "z": "${x.y}"}
+        self.assertEqual(resolve_variables(data)["z"], "ok")
+
+    def test_list_index_in_path(self) -> None:
+        data = {"items": [{"id": 9}], "first": "${items.0.id}"}
+        self.assertEqual(resolve_variables(data)["first"], 9)
+
+    def test_relative_reference(self) -> None:
+        data = {
+            "block": {
+                "name": "inner",
+                "copy": "${..name}",
+            },
+            "name": "outer",
+        }
+        out = resolve_variables(data)
+        self.assertEqual(out["block"]["copy"], "inner")
+
+    def test_env_explicit(self) -> None:
+        data = {"p": "${env:CFG_TEST_LIB_PORT}"}
+        with patch.dict(os.environ, {"CFG_TEST_LIB_PORT": "3000"}, clear=False):
+            self.assertEqual(resolve_variables(data)["p"], 3000)
+
+    def test_env_with_default_when_missing(self) -> None:
+        env_name = "CFG_TEST_LIB_SHOULD_NOT_EXIST_XYZ"
+        self.assertIsNone(os.environ.get(env_name))
+        data = {"p": "${env:" + env_name + ":fallback}"}
+        self.assertEqual(resolve_variables(data)["p"], "fallback")
+
+    def test_env_missing_raises(self) -> None:
+        env_name = "CFG_TEST_LIB_ABSENT_VAR"
+        self.assertIsNone(os.environ.get(env_name))
+        data = {"p": "${env:" + env_name + "}"}
+        with self.assertRaises(KeyError):
+            resolve_variables(data)
+
+    def test_single_segment_falls_back_to_env(self) -> None:
+        name = "CFG_TEST_LIB_SINGLE"
+        data = {"p": "${" + name + "}"}
+        with patch.dict(os.environ, {name: "yes"}, clear=False):
+            self.assertIs(resolve_variables(data)["p"], True)
+
+    def test_partial_string_interpolation(self) -> None:
+        data = {"host": "h", "s": "x-${host}-y"}
+        self.assertEqual(resolve_variables(data)["s"], "x-h-y")
+
+    def test_circular_reference_raises(self) -> None:
+        data: dict[str, object] = {"a": "${b}", "b": "${a}"}
+        with self.assertRaisesRegex(ValueError, "循环变量引用"):
+            resolve_variables(data)
+
+    def test_invalid_relative_path_raises(self) -> None:
+        data = {"x": "${.bad}"}
+        with self.assertRaisesRegex(ValueError, "不支持的相对路径变量"):
+            resolve_variables(data)

python_library_configlib-0.1.0/tests/test_toml.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from configlib.toml import is_toml, load_toml, load_toml_raw
+
+
+class TomlHelpersTests(unittest.TestCase):
+    def test_is_toml_suffix(self) -> None:
+        self.assertTrue(is_toml("cfg.toml"))
+        self.assertFalse(is_toml("x.json"))
+
+    def test_load_toml_resolves_variables(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "c.toml"
+            path.write_text(
+                '[app]\nname = "demo"\nlabel = "${app.name}"\n',
+                encoding="utf-8",
+            )
+            data = load_toml(str(path))
+            self.assertEqual(data["app"]["label"], "demo")
+
+    def test_load_toml_raw_no_resolution(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "c.toml"
+            path.write_text(
+                'x = "${y}"\ny = 1\n',
+                encoding="utf-8",
+            )
+            data = load_toml_raw(str(path))
+            self.assertEqual(data["x"], "${y}")

python_library_configlib-0.1.0/tests/test_yaml.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from configlib import load_config, load_config_raw
+from configlib.yaml import is_yaml, load_yaml_raw
+
+
+class ConfiglibYamlTests(unittest.TestCase):
+    def test_load_example_yaml(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        result = load_config(str(base_dir / "assets" / "example.yaml"))
+
+        expected = {
+            "app": {
+                "name": "demo",
+                "version": "1.0",
+            },
+            "base": {
+                "title": "hello",
+                "nested": {
+                    "value": 123,
+                },
+            },
+            "json_data": {
+                "user": {
+                    "name": "alice",
+                    "age": 18,
+                },
+            },
+            "toml_data": {
+                "server": {
+                    "host": "127.0.0.1",
+                    "port": 8080,
+                },
+            },
+            "refs": {
+                "app_name": "demo",
+                "base_title": "hello",
+                "local": {
+                    "name": "child",
+                    "parent_name": "child",
+                },
+            },
+        }
+
+        self.assertEqual(result, expected)
+
+    def test_is_yaml_suffixes(self) -> None:
+        self.assertTrue(is_yaml("a.yaml"))
+        self.assertTrue(is_yaml("b.yml"))
+        self.assertFalse(is_yaml("c.json"))
+
+    def test_load_yaml_raw_keeps_placeholders(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        path = base_dir / "assets" / "example.yaml"
+        data = load_yaml_raw(str(path))
+        self.assertEqual(data["refs"]["app_name"], "${app.name}")
+
+    def test_load_config_raw_yaml_matches_load_yaml_raw(self) -> None:
+        base_dir = Path(__file__).resolve().parent.parent
+        path = base_dir / "assets" / "example.yaml"
+        self.assertEqual(load_config_raw(path), load_yaml_raw(str(path)))
+
+    def test_include_cycle_raises(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            a = root / "a.yaml"
+            b = root / "b.yaml"
+            a.write_text("v: !include b.yaml\n", encoding="utf-8")
+            b.write_text("v: !include a.yaml\n", encoding="utf-8")
+            with self.assertRaisesRegex(ValueError, "循环 include"):
+                load_config(str(a))
+
+
+if __name__ == "__main__":
+    unittest.main()