python-library-configlib 0.1.0__tar.gz → 0.1.1__tar.gz

{python_library_configlib-0.1.0 → python_library_configlib-0.1.1}/.gitignore

@@ -8,4 +8,6 @@ build/
 .env
 .pytest_cache/
 config.yaml
-logs/
+logs/
+.cursor/
+uv.lock

{python_library_configlib-0.1.0 → python_library_configlib-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-library-configlib
-Version: 0.1.0
+Version: 0.1.1
 Requires-Python: >=3.10
 Requires-Dist: json5>=0.9.0
 Requires-Dist: pydantic>=2.0.0

{python_library_configlib-0.1.0 → python_library_configlib-0.1.1}/configlib/yaml.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from typing import Any
 import yaml
 from .resolver import resolve_variables
+from .yaml_compose import apply_composition, preprocess_yaml_compose
 
 SUFFIXES = {".yaml", ".yml"}
 _YAML_LOAD_STACK: ContextVar[list[Path] | None] = ContextVar("_YAML_LOAD_STACK", default=None)
@@ -41,7 +42,8 @@ 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)
+        resolved = resolve_variables(data)
+        return apply_composition(resolved)
 
 
 def load_yaml_raw(file_path: str) -> dict | list:
@@ -63,8 +65,9 @@ def _load_yaml_raw(path: Path) -> Any:
 
     _YamlIncludeLoader.add_constructor("!include", construct_include)
 
-    with path.open("r", encoding="utf-8") as f:
-        return yaml.load(f, Loader=_YamlIncludeLoader)
+    text = path.read_text(encoding="utf-8")
+    text = preprocess_yaml_compose(text)
+    return yaml.load(text, Loader=_YamlIncludeLoader)
 
 
 __all__ = ["is_yaml", "load_yaml", "load_yaml_raw"]

python_library_configlib-0.1.1/configlib/yaml_compose.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+import copy
+import re
+from typing import Any, Literal
+
+SPREAD_KEY = "__configlib_spread__"
+MERGES_KEY = "__configlib_merges__"
+
+_BARE_VAR_LINE = re.compile(r"^(\s*)(\$\{[^{}]+\})\s*(#.*)?$")
+_RESERVED_KEYS = frozenset({SPREAD_KEY, MERGES_KEY})
+
+
+def preprocess_yaml_compose(source: str) -> str:
+    """将块式 YAML 中独占一行的 ${} 改写成可解析的占位结构。"""
+    if not source:
+        return source
+    lines = source.splitlines(keepends=True)
+    if not lines:
+        return source
+
+    infos = [_line_info(line) for line in lines]
+    out: list[str] = []
+    i = 0
+    while i < len(lines):
+        info = infos[i]
+        if not info.is_bare_var:
+            out.append(lines[i])
+            i += 1
+            continue
+
+        parent_indent = _parent_indent(infos, i)
+        block_end = _block_end_index(infos, i, parent_indent)
+        block = infos[i:block_end]
+        siblings = _siblings_at_indent(infos, i, parent_indent)
+        mode = _infer_block_mode(siblings)
+
+        if mode == "seq":
+            for entry in block:
+                if entry.is_bare_var:
+                    out.append(
+                        f"{entry.indent_str}- {SPREAD_KEY}: {entry.bare_expr}{entry.comment_suffix}\n"
+                    )
+            i = block_end
+            continue
+
+        merge_exprs = [entry.bare_expr for entry in block if entry.is_bare_var]
+        if merge_exprs:
+            base_indent = block[0].indent_str
+            out.append(f"{base_indent}{MERGES_KEY}:\n")
+            for expr in merge_exprs:
+                out.append(f"{base_indent}  - {expr}\n")
+        i = block_end
+
+    if source.endswith("\n") and out and not out[-1].endswith("\n"):
+        out[-1] = out[-1] + "\n"
+    return "".join(out)
+
+
+def apply_composition(data: Any) -> Any:
+    """在变量解析完成后展开列表拼接与字典合并占位。"""
+    if isinstance(data, dict):
+        return _compose_mapping(data)
+    if isinstance(data, list):
+        return _compose_sequence(data)
+    return data
+
+
+class _LineInfo:
+    __slots__ = (
+        "indent",
+        "indent_str",
+        "is_bare_var",
+        "bare_expr",
+        "comment_suffix",
+        "is_dash_item",
+        "is_mapping_entry",
+        "is_blank",
+    )
+
+    def __init__(self, line: str) -> None:
+        stripped = line.lstrip(" \t")
+        self.indent = len(line) - len(stripped)
+        self.indent_str = line[: self.indent]
+        self.is_blank = not stripped or stripped.startswith("#")
+        self.is_dash_item = stripped.startswith("- ")
+        self.is_mapping_entry = (
+            not self.is_blank
+            and not self.is_dash_item
+            and ":" in stripped
+            and not stripped.startswith("${")
+        )
+        match = _BARE_VAR_LINE.match(stripped)
+        self.is_bare_var = match is not None and not self.is_blank
+        self.bare_expr = match.group(2) if match else ""
+        self.comment_suffix = match.group(3) or "" if match else ""
+
+
+def _line_info(line: str) -> _LineInfo:
+    return _LineInfo(line)
+
+
+def _parent_indent(infos: list[_LineInfo], index: int) -> int:
+    indent = infos[index].indent
+    for pos in range(index - 1, -1, -1):
+        info = infos[pos]
+        if info.is_blank:
+            continue
+        if info.indent < indent:
+            return info.indent
+    return -1
+
+
+def _siblings_at_indent(
+    infos: list[_LineInfo],
+    index: int,
+    parent_indent: int,
+) -> list[_LineInfo]:
+    indent = infos[index].indent
+    siblings: list[_LineInfo] = []
+    for pos, info in enumerate(infos):
+        if info.is_blank:
+            continue
+        if info.indent != indent:
+            continue
+        if _parent_indent(infos, pos) != parent_indent:
+            continue
+        siblings.append(info)
+    return siblings
+
+
+def _block_end_index(infos: list[_LineInfo], start: int, parent_indent: int) -> int:
+    indent = infos[start].indent
+    pos = start
+    while pos < len(infos):
+        info = infos[pos]
+        if not info.is_blank and info.indent < indent and pos > start:
+            break
+        if not info.is_blank and info.indent == indent:
+            if pos > start and not info.is_bare_var:
+                break
+        if not info.is_blank and info.indent > indent:
+            pos += 1
+            continue
+        pos += 1
+    return pos
+
+
+def _infer_block_mode(block: list[_LineInfo]) -> Literal["seq", "map"]:
+    for info in block:
+        if info.is_dash_item:
+            return "seq"
+        if info.is_mapping_entry:
+            return "map"
+    return "map"
+
+
+def _deep_merge_dict(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]:
+    """递归合并 mapping；双方均为 dict 的同名键继续下钻，否则由 overlay 覆盖。"""
+    result = copy.deepcopy(base)
+    for key, value in overlay.items():
+        if (
+            key in result
+            and isinstance(result[key], dict)
+            and isinstance(value, dict)
+        ):
+            result[key] = _deep_merge_dict(result[key], value)
+        else:
+            result[key] = copy.deepcopy(value)
+    return result
+
+
+def _compose_mapping(data: dict[str, Any]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    merge_sources: list[dict[str, Any]] = []
+
+    for key, value in data.items():
+        if key == MERGES_KEY:
+            resolved = _compose_sequence(value) if isinstance(value, list) else value
+            if not isinstance(resolved, list):
+                raise TypeError(f"{MERGES_KEY} 必须是列表")
+            for item in resolved:
+                if not isinstance(item, dict):
+                    raise TypeError(f"{MERGES_KEY} 每一项必须是字典")
+                merge_sources.append(apply_composition(item))
+            continue
+        if key in _RESERVED_KEYS:
+            raise ValueError(f"保留键 {key!r} 只能由预处理生成")
+        merged[key] = apply_composition(value)
+
+    result: dict[str, Any] = {}
+    for source in merge_sources:
+        result = _deep_merge_dict(result, source)
+    return _deep_merge_dict(result, merged)
+
+
+def _compose_sequence(data: list[Any]) -> list[Any]:
+    result: list[Any] = []
+    for item in data:
+        if isinstance(item, dict) and SPREAD_KEY in item and len(item) == 1:
+            spread_value = apply_composition(item[SPREAD_KEY])
+            if not isinstance(spread_value, list):
+                raise TypeError(f"{SPREAD_KEY} 必须是列表")
+            result.extend(spread_value)
+            continue
+        if isinstance(item, dict) and SPREAD_KEY in item:
+            raise ValueError(f"{SPREAD_KEY} 不能与其他键混用")
+        result.append(apply_composition(item))
+    return result
+
+
+__all__ = [
+    "SPREAD_KEY",
+    "MERGES_KEY",
+    "preprocess_yaml_compose",
+    "apply_composition",
+]

{python_library_configlib-0.1.0 → python_library_configlib-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "python-library-configlib"
-version = "0.1.0"
+version = "0.1.1"
 requires-python = ">=3.10"
 dependencies = [
     "pydantic>=2.0.0",

python_library_configlib-0.1.1/tests/test_yaml_compose.py

@@ -0,0 +1,206 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+from textwrap import dedent
+
+from configlib import load_config, load_config_raw
+from configlib.yaml_compose import apply_composition, preprocess_yaml_compose
+from configlib.resolver import resolve_variables
+
+
+class PreprocessTests(unittest.TestCase):
+    def test_list_spread_line_gets_dash_placeholder(self) -> None:
+        source = dedent("""
+            items:
+              - a
+              ${extra}
+              - b
+        """)
+        out = preprocess_yaml_compose(source)
+        self.assertIn("- __configlib_spread__: ${extra}", out)
+
+    def test_dict_merge_lines_collapsed(self) -> None:
+        source = dedent("""
+            cfg:
+              ${base}
+              ${more}
+              flag: true
+        """)
+        out = preprocess_yaml_compose(source)
+        self.assertIn("__configlib_merges__:", out)
+        self.assertIn("- ${base}", out)
+        self.assertIn("- ${more}", out)
+
+
+class ComposeIntegrationTests(unittest.TestCase):
+    def test_list_spread_and_nested_item(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    shared: [s1, s2]
+                    items:
+                      - head
+                      ${shared}
+                      - tail
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(data["items"], ["head", "s1", "s2", "tail"])
+
+    def test_list_nested_variable_stays_one_element(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    shared: [1, 2]
+                    items:
+                      - ${shared}
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(data["items"], [[1, 2]])
+
+    def test_dict_deep_merge_nested_override(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    base:
+                      x2:
+                        x3: v1
+                        x4: v2
+                      x5: v3
+                    x1:
+                      ${base}
+                      x2:
+                        x4: vvvv
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(
+                data["x1"],
+                {"x2": {"x3": "v1", "x4": "vvvv"}, "x5": "v3"},
+            )
+
+    def test_cfg_merge_base_then_nested_local_keys(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    base:
+                      a: 1
+                      b:
+                        c: old
+                        d: keep
+                    cfg:
+                      ${base}
+                      b:
+                        c: v1
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(
+                data["cfg"],
+                {"a": 1, "b": {"c": "v1", "d": "keep"}},
+            )
+
+    def test_include_then_deep_merge_via_variable(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "a.yaml").write_text(
+                dedent("""
+                    x1:
+                      x2:
+                        x3: v1
+                        x4: v2
+                      x5: v3
+                """),
+                encoding="utf-8",
+            )
+            (root / "b.yaml").write_text(
+                dedent("""
+                    from_a: !include a.yaml
+                    x1:
+                      ${from_a.x1}
+                      x2:
+                        x4: vvvv
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(root / "b.yaml")
+            self.assertEqual(
+                data["x1"],
+                {"x2": {"x3": "v1", "x4": "vvvv"}, "x5": "v3"},
+            )
+
+    def test_dict_merge_then_local_override(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    base:
+                      a: 1
+                      b: old
+                    cfg:
+                      ${base}
+                      b: new
+                      c: 3
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(data["cfg"], {"a": 1, "b": "new", "c": 3})
+
+    def test_dict_nested_key_keeps_subtree(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    base:
+                      x: 1
+                    root:
+                      nested: ${base}
+                """),
+                encoding="utf-8",
+            )
+            data = load_config(path)
+            self.assertEqual(data["root"]["nested"], {"x": 1})
+
+    def test_raw_keeps_placeholders_without_resolve(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "cfg.yaml"
+            path.write_text(
+                dedent("""
+                    items:
+                      - head
+                      ${shared}
+                """),
+                encoding="utf-8",
+            )
+            raw = load_config_raw(path)
+            self.assertIn("__configlib_spread__", str(raw))
+
+    def test_spread_non_list_raises(self) -> None:
+        tree = resolve_variables({"n": 1, "items": [{"__configlib_spread__": "${n}"}]})
+        with self.assertRaises(TypeError):
+            apply_composition(tree)
+
+
+class ComposeUnitTests(unittest.TestCase):
+    def test_apply_list_spread(self) -> None:
+        data = [{"__configlib_spread__": [1, 2]}, 3]
+        self.assertEqual(apply_composition(data), [1, 2, 3])
+
+    def test_apply_dict_merges(self) -> None:
+        data = {
+            "__configlib_merges__": [{"a": 1}, {"b": 2}],
+            "b": 9,
+        }
+        self.assertEqual(apply_composition(data), {"a": 1, "b": 9})