python-hwpx-automation 6.0.3__py3-none-any.whl

hwpx_automation/office/quality/page_guard.py

@@ -0,0 +1,277 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Proxy checks for layout drift between a reference and an output HWPX.
+
+This module does not calculate rendered page counts. It compares structural and
+textual metrics that often correlate with page-layout drift.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import BinaryIO, Iterable, Sequence
+
+from hwpx import HwpxPackage
+from lxml import etree  # pyright: ignore[reportAttributeAccessIssue]
+
+NS = {
+    "hp": "http://www.hancom.co.kr/hwpml/2011/paragraph",
+    "hs": "http://www.hancom.co.kr/hwpml/2011/section",
+    "opf": "http://www.idpf.org/2007/opf/",
+}
+
+_SHAPE_TAGS = {
+    "line",
+    "rect",
+    "ellipse",
+    "arc",
+    "polygon",
+    "curve",
+    "connectLine",
+    "textart",
+    "pic",
+    "compose",
+    "equation",
+    "ole",
+    "container",
+}
+
+__all__ = [
+    "DocumentMetrics",
+    "collect_metrics",
+    "compare_metrics",
+    "main",
+]
+
+
+@dataclass(frozen=True)
+class DocumentMetrics:
+    section_count: int
+    paragraph_count: int
+    page_break_count: int
+    column_break_count: int
+    table_count: int
+    shape_count: int
+    control_count: int
+    table_shapes: list[tuple[str, str, str, str, str, str]]
+    shape_types: list[tuple[str, int]]
+    control_types: list[tuple[str, int]]
+    text_char_total: int
+    text_char_total_nospace: int
+    paragraph_text_lengths: list[int]
+
+
+def _text_of_t_node(node: etree._Element) -> str:
+    return "".join(node.itertext())
+
+
+def _local_name(tag: str) -> str:
+    if "}" in tag:
+        return tag.split("}", 1)[1]
+    return tag
+
+
+def _iter_section_roots(source: str | Path | bytes | BinaryIO) -> Iterable[etree._Element]:
+    package = HwpxPackage.open(source)
+    for name in package.section_paths():
+        yield package.get_xml(name)
+
+
+def collect_metrics(source: str | Path | bytes | BinaryIO) -> DocumentMetrics:
+    section_roots = list(_iter_section_roots(source))
+
+    paragraphs: list[etree._Element] = []
+    tables: list[etree._Element] = []
+    table_shapes: list[tuple[str, str, str, str, str, str]] = []
+    shape_types: dict[str, int] = {}
+    control_types: dict[str, int] = {}
+    paragraph_text_lengths: list[int] = []
+    text_char_total = 0
+    text_char_total_nospace = 0
+    page_break_count = 0
+    column_break_count = 0
+
+    for root in section_roots:
+        section_paragraphs = root.xpath(".//hs:sec/hp:p", namespaces=NS)
+        if not section_paragraphs:
+            section_paragraphs = root.xpath(".//hp:p", namespaces=NS)
+        paragraphs.extend(section_paragraphs)
+
+        section_tables = root.xpath(".//hp:tbl", namespaces=NS)
+        tables.extend(section_tables)
+
+        for element in root.iter():
+            name = _local_name(element.tag)
+            if name in _SHAPE_TAGS:
+                shape_types[name] = shape_types.get(name, 0) + 1
+            if name == "ctrl":
+                control_counted = False
+                for child in element:
+                    child_name = _local_name(child.tag)
+                    control_types[child_name] = control_types.get(child_name, 0) + 1
+                    control_counted = True
+                if not control_counted:
+                    control_types["ctrl"] = control_types.get("ctrl", 0) + 1
+
+        for table in section_tables:
+            size = table.find("hp:sz", namespaces=NS)
+            table_shapes.append(
+                (
+                    table.get("rowCnt", ""),
+                    table.get("colCnt", ""),
+                    size.get("width", "") if size is not None else "",
+                    size.get("height", "") if size is not None else "",
+                    table.get("repeatHeader", ""),
+                    table.get("pageBreak", ""),
+                )
+            )
+
+        for paragraph in section_paragraphs:
+            if paragraph.get("pageBreak") == "1":
+                page_break_count += 1
+            if paragraph.get("columnBreak") == "1":
+                column_break_count += 1
+            paragraph_length = 0
+            for text_node in paragraph.xpath(".//hp:t", namespaces=NS):
+                text = _text_of_t_node(text_node)
+                paragraph_length += len(text)
+                text_char_total += len(text)
+                text_char_total_nospace += len("".join(text.split()))
+            paragraph_text_lengths.append(paragraph_length)
+
+    return DocumentMetrics(
+        section_count=len(section_roots),
+        paragraph_count=len(paragraphs),
+        page_break_count=page_break_count,
+        column_break_count=column_break_count,
+        table_count=len(tables),
+        shape_count=sum(shape_types.values()),
+        control_count=sum(control_types.values()),
+        table_shapes=table_shapes,
+        shape_types=sorted(shape_types.items()),
+        control_types=sorted(control_types.items()),
+        text_char_total=text_char_total,
+        text_char_total_nospace=text_char_total_nospace,
+        paragraph_text_lengths=paragraph_text_lengths,
+    )
+
+
+def _ratio_delta(reference_value: int, output_value: int) -> float:
+    base = max(reference_value, 1)
+    return abs(output_value - reference_value) / base
+
+
+def compare_metrics(
+    reference: DocumentMetrics,
+    output: DocumentMetrics,
+    *,
+    max_text_delta_ratio: float = 0.15,
+    max_paragraph_delta_ratio: float = 0.25,
+) -> list[str]:
+    errors: list[str] = []
+
+    if reference.section_count != output.section_count:
+        errors.append(
+            f"section count mismatch: ref={reference.section_count}, out={output.section_count}"
+        )
+    if reference.paragraph_count != output.paragraph_count:
+        errors.append(
+            f"paragraph count mismatch: ref={reference.paragraph_count}, out={output.paragraph_count}"
+        )
+    if reference.page_break_count != output.page_break_count:
+        errors.append(
+            "pageBreak count mismatch: "
+            f"ref={reference.page_break_count}, out={output.page_break_count}"
+        )
+    if reference.column_break_count != output.column_break_count:
+        errors.append(
+            "columnBreak count mismatch: "
+            f"ref={reference.column_break_count}, out={output.column_break_count}"
+        )
+    if reference.table_count != output.table_count:
+        errors.append(f"table count mismatch: ref={reference.table_count}, out={output.table_count}")
+    if reference.shape_count != output.shape_count:
+        errors.append(f"shape count mismatch: ref={reference.shape_count}, out={output.shape_count}")
+    if reference.control_count != output.control_count:
+        errors.append(
+            f"control count mismatch: ref={reference.control_count}, out={output.control_count}"
+        )
+    if reference.table_shapes != output.table_shapes:
+        errors.append("table shape mismatch (rowCnt/colCnt/width/height/repeatHeader/pageBreak)")
+    if reference.shape_types != output.shape_types:
+        errors.append("shape type histogram mismatch")
+    if reference.control_types != output.control_types:
+        errors.append("control type histogram mismatch")
+
+    text_delta = _ratio_delta(reference.text_char_total_nospace, output.text_char_total_nospace)
+    if text_delta > max_text_delta_ratio:
+        errors.append(
+            "total text length drift exceeded: "
+            f"ref={reference.text_char_total_nospace}, out={output.text_char_total_nospace}, "
+            f"delta={text_delta:.2%}, limit={max_text_delta_ratio:.2%}"
+        )
+
+    if len(reference.paragraph_text_lengths) == len(output.paragraph_text_lengths):
+        for index, (ref_len, out_len) in enumerate(
+            zip(reference.paragraph_text_lengths, output.paragraph_text_lengths),
+            start=1,
+        ):
+            if ref_len == 0 and out_len == 0:
+                continue
+            delta = _ratio_delta(ref_len, out_len)
+            if delta > max_paragraph_delta_ratio:
+                errors.append(
+                    f"paragraph {index} text drift exceeded: "
+                    f"ref={ref_len}, out={out_len}, delta={delta:.2%}, "
+                    f"limit={max_paragraph_delta_ratio:.2%}"
+                )
+    return errors
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Reference-vs-output HWPX layout-drift proxy checker"
+    )
+    parser.add_argument("--reference", "-r", required=True, help="Reference HWPX path")
+    parser.add_argument("--output", "-o", required=True, help="Output HWPX path")
+    parser.add_argument("--max-text-delta-ratio", type=float, default=0.15)
+    parser.add_argument("--max-paragraph-delta-ratio", type=float, default=0.25)
+    parser.add_argument("--json", action="store_true", help="Print collected metrics as JSON")
+    args = parser.parse_args(argv)
+
+    try:
+        reference = collect_metrics(args.reference)
+        output = collect_metrics(args.output)
+    except Exception as exc:
+        print(f"ERROR: {exc}")
+        return 1
+
+    if args.json:
+        print(
+            json.dumps(
+                {"reference": asdict(reference), "output": asdict(output)},
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+
+    errors = compare_metrics(
+        reference,
+        output,
+        max_text_delta_ratio=args.max_text_delta_ratio,
+        max_paragraph_delta_ratio=args.max_paragraph_delta_ratio,
+    )
+    if errors:
+        print("FAIL: page guard")
+        for error in errors:
+            print(f" - {error}")
+        return 1
+
+    print("PASS: page guard")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI convenience
+    raise SystemExit(main())

hwpx_automation/office/rendering/__init__.py

@@ -0,0 +1,145 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Canonical Hancom rendering owner for the automation application layer.
+
+The package owns runtime discovery, renderer execution, serialized worker
+policy, fixture orchestration, and visual-QA measurement.  ``python-hwpx``
+supplies only renderer-neutral contracts and deterministic geometry helpers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from hwpx.quality import SavePipeline
+from hwpx.quality.rendering import EditMask, VisualReport
+
+if TYPE_CHECKING:
+    from .oracle import (
+        MacHancomOracle,
+        NullOracle,
+        RenderBackend,
+        RenderOracle,
+        WindowsComOracle,
+        resolve_oracle,
+        visual_check,
+    )
+
+_ORACLE_EXPORTS = (
+    "MacHancomOracle",
+    "NullOracle",
+    "RenderBackend",
+    "RenderOracle",
+    "WindowsComOracle",
+    "resolve_oracle",
+    "visual_check",
+)
+
+
+def __getattr__(name: str) -> Any:
+    """Load the Hancom side only when someone asks for it.
+
+    Importing this package eagerly would drag the oracle in behind any import of
+    a neutral contract — ``block_splits``, ``detectors``, ``diff`` — because a
+    submodule import initialises its package first. Those contracts exist so
+    exam typesetting can compute question splits with no renderer present, and
+    that promise is worth nothing if reaching them starts one.
+
+    Core's ``hwpx.visual`` used the same lazy hook for the same reason. The move
+    to this owner dropped it, and the boundary test caught it.
+    """
+    if name in _ORACLE_EXPORTS:
+        import importlib
+
+        return getattr(importlib.import_module(f"{__name__}.oracle"), name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *_ORACLE_EXPORTS})
+
+
+def _runtime_export(name: str) -> Any:
+    """Resolve a lazy export while preserving an explicit runtime patch."""
+
+    value = globals().get(name)
+    return value if value is not None else __getattr__(name)
+
+
+class HancomRenderBackend:
+    """Adapt a discovered Hancom render transport to the core check protocol."""
+
+    def __init__(self, oracle: Any) -> None:
+        self._oracle = oracle
+
+    def available(self) -> bool:
+        return bool(self._oracle is not None and self._oracle.available())
+
+    def check(
+        self,
+        before_hwpx: str | None,
+        after_hwpx: str,
+        *,
+        edit_mask: EditMask | None = None,
+        diff_eps: float = 0.005,
+        dpi: int = 150,
+        work_dir: str | None = None,
+        keep_artifacts: bool = False,
+    ) -> VisualReport:
+        # Module-dict lookup, not a direct submodule import: a test that
+        # patches ``rendering.visual_check`` must still win, and __getattr__
+        # only runs when the name is absent from the module dict.
+        return _runtime_export("visual_check")(
+            before_hwpx,
+            after_hwpx,
+            oracle=self._oracle,
+            edit_mask=edit_mask,
+            diff_eps=diff_eps,
+            dpi=dpi,
+            work_dir=work_dir,
+            keep_artifacts=keep_artifacts,
+        )
+
+
+def resolve_hancom_backend(*, dpi: int = 150, **_options: Any) -> HancomRenderBackend:
+    """Discover Hancom at the application boundary and return a core backend."""
+
+    return HancomRenderBackend(resolve_hancom_oracle(dpi=dpi))
+
+
+def resolve_hancom_oracle(*, dpi: int = 150, **_options: Any) -> Any:
+    """Return the canonical Hancom transport at the automation boundary."""
+
+    return _runtime_export("resolve_oracle")(dpi=dpi)
+
+
+@contextmanager
+def bind_document_rendering(document: Any) -> Iterator[None]:
+    """Temporarily bind automation-owned rendering to one core document save."""
+
+    sentinel = object()
+    previous = getattr(document, "_save_pipeline", sentinel)
+    document._save_pipeline = SavePipeline(oracle_factory=resolve_hancom_backend)
+    try:
+        yield
+    finally:
+        if previous is sentinel:
+            delattr(document, "_save_pipeline")
+        else:
+            document._save_pipeline = previous
+
+
+__all__ = [
+    "HancomRenderBackend",
+    "MacHancomOracle",
+    "NullOracle",
+    "RenderBackend",
+    "RenderOracle",
+    "WindowsComOracle",
+    "bind_document_rendering",
+    "resolve_hancom_backend",
+    "resolve_hancom_oracle",
+    "resolve_oracle",
+    "visual_check",
+]