python-library-configlib 0.1.0__py3-none-any.whl

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

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']

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"]

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

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']

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+configlib/__init__.py,sha256=nHRPxw4VSMahSttIrTI0r5yphgzKgk_mGZnPyckNh9s,1139
+configlib/json.py,sha256=niF-J3FoHRsQKIZo4GUmkaEXpwLriRjF2Mpj1-F77rc,562
+configlib/loader.py,sha256=IJX-50m_7WWa7vgDaiDA-8L8PbbiTlK09ImftCph2WY,3518
+configlib/resolver.py,sha256=CoTOzgxvQvkAOS1qjHf3ZaLWZY7Yc2Y6iGfszX2KDrg,7524
+configlib/toml.py,sha256=TwBvnLi055OqVd2qcSA8kh0VRx4MIA6DfhRHXX0LF_w,578
+configlib/yaml.py,sha256=ngUjqAiL5kyoC3lciLX1TH5yIeNlAAWAU2lIdK0Dp8I,2092
+python_library_configlib-0.1.0.dist-info/METADATA,sha256=XiN2pIWRZHs_ZHBGuYXmcsEfXAR2FTBgE8_odMBML-Y,233
+python_library_configlib-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+python_library_configlib-0.1.0.dist-info/RECORD,,

python_library_configlib-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