python-hwpx 2.10.2__py3-none-any.whl → 2.11.0__py3-none-any.whl

hwpx/__init__.py

@@ -25,6 +25,63 @@ from .tools.text_extractor import (
     TextExtractor,
 )
 from .tools.object_finder import FoundElement, ObjectFinder
+from .tools.advanced_generators import (
+    build_image_grid,
+    build_meeting_nameplates,
+    build_organization_chart,
+)
+from .tools.doc_diff import (
+    DOC_DIFF_REPORT_VERSION,
+    REFERENCE_CONSISTENCY_REPORT_VERSION,
+    build_comparison_table_plan,
+    diff_paragraphs,
+    doc_diff,
+    inspect_reference_consistency,
+)
+from .tools.mail_merge import (
+    MAIL_MERGE_REPORT_VERSION,
+    inspect_mail_merge_placeholders,
+    load_mail_merge_rows,
+    mail_merge,
+)
+from .tools.table_compute import (
+    TABLE_COMPUTE_REPORT_VERSION,
+    table_compute,
+)
+from .tools.official_lint import (
+    OFFICIAL_DOCUMENT_STYLE_REPORT_VERSION,
+    inspect_official_document_style,
+)
+from .tools.package_validator import (
+    EditorOpenSafetyReport,
+    PackageValidationReport,
+    validate_editor_open_safety,
+    validate_package,
+)
+from .tools.style_profile import (
+    STYLE_PROFILE_COMPARISON_SCHEMA_VERSION,
+    STYLE_PROFILE_SCHEMA_VERSION,
+    TEMPLATE_REGISTRY_SCHEMA_VERSION,
+    apply_style_profile_to_plan,
+    compare_style_profiles,
+    describe_template,
+    extract_style_profile,
+    list_templates,
+    placeholder_fill_report,
+    register_template,
+)
+from .tools.layout_preview import (
+    LayoutPreview,
+    PreviewPage,
+    render_layout_preview,
+)
+from .patch import (
+    BytePreservingPatchResult,
+    ParagraphTextPatch,
+    PatchApplied,
+    PatchSkipped,
+    paragraph_patch,
+)
 from .document import HwpxDocument
 from .package import HwpxPackage
 from .authoring import (
@@ -42,6 +99,7 @@ from .authoring import (
     normalize_document_plan,
     validate_document_plan,
 )
+from .builder import approval_box
 from .template_formfit import (
     TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION,
     TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION,
@@ -58,22 +116,62 @@ __all__ = [
     "DocumentBlock",
     "DocumentPlan",
     "DocumentStylePreset",
+    "EditorOpenSafetyReport",
     "ParagraphInfo",
+    "PackageValidationReport",
+    "BytePreservingPatchResult",
     "PlanValidationReport",
+    "ParagraphTextPatch",
+    "PatchApplied",
+    "PatchSkipped",
+    "LayoutPreview",
+    "PreviewPage",
     "SectionInfo",
     "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION",
     "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION",
     "TextExtractor",
     "FoundElement",
     "ObjectFinder",
+    "OFFICIAL_DOCUMENT_STYLE_REPORT_VERSION",
+    "DOC_DIFF_REPORT_VERSION",
+    "REFERENCE_CONSISTENCY_REPORT_VERSION",
+    "MAIL_MERGE_REPORT_VERSION",
+    "STYLE_PROFILE_COMPARISON_SCHEMA_VERSION",
+    "STYLE_PROFILE_SCHEMA_VERSION",
+    "TEMPLATE_REGISTRY_SCHEMA_VERSION",
+    "TABLE_COMPUTE_REPORT_VERSION",
+    "apply_style_profile_to_plan",
+    "build_comparison_table_plan",
+    "build_image_grid",
+    "build_meeting_nameplates",
+    "build_organization_chart",
+    "diff_paragraphs",
+    "doc_diff",
+    "compare_style_profiles",
     "PlanValidationIssue",
     "HwpxDocument",
     "HwpxPackage",
     "create_document_from_plan",
     "analyze_template_formfit",
     "apply_template_formfit",
+    "approval_box",
+    "describe_template",
+    "extract_style_profile",
     "inspect_document_authoring_quality",
+    "inspect_mail_merge_placeholders",
+    "inspect_official_document_style",
+    "inspect_reference_consistency",
     "inspect_operating_plan_quality",
+    "list_templates",
+    "load_mail_merge_rows",
+    "mail_merge",
     "normalize_document_plan",
+    "placeholder_fill_report",
     "validate_document_plan",
+    "validate_editor_open_safety",
+    "validate_package",
+    "paragraph_patch",
+    "render_layout_preview",
+    "register_template",
+    "table_compute",
 ]

hwpx/authoring.py

@@ -26,11 +26,13 @@ from .builder import (
     Run as BuilderRun,
     Section as BuilderSection,
     Table as BuilderTable,
+    approval_box as BuilderApprovalBox,
 )
 from .builder.core import Toc as BuilderToc
 from .document import HwpxDocument
 from .tools.package_validator import validate_package
 from .tools.table_cleanup import normalize_cell_text
+from .tools.advanced_generators import build_image_grid
 from .tools.report_utils import (
     calculate_age,
     calculate_ratios,
@@ -603,9 +605,13 @@ def _validate_v2_block(raw_block: Any, *, path: str) -> list[PlanValidationIssue
         "numberedList",
         "table",
         "image",
+        "image_grid",
+        "imageGrid",
         "toc",
         "page_break",
         "pageBreak",
+        "approval_box",
+        "approvalBox",
     }
     if block_type not in supported:
         return [
@@ -627,6 +633,27 @@ def _validate_v2_block(raw_block: Any, *, path: str) -> list[PlanValidationIssue
                     suggestion=f"Add non-empty {text_key}.",
                 )
             ]
+    if block_type in {"image_grid", "imageGrid"}:
+        images = raw_block.get("images")
+        if not isinstance(images, list) or not images:
+            return [
+                _plan_issue(
+                    "missing_image_grid_images",
+                    f"{path}.images",
+                    f"{path}.images must be a non-empty list",
+                    suggestion="Add image items with path and optional caption fields.",
+                )
+            ]
+        for image_index, image in enumerate(images):
+            if not isinstance(image, Mapping) or not str(image.get("path") or "").strip():
+                return [
+                    _plan_issue(
+                        "missing_image_path",
+                        f"{path}.images[{image_index}].path",
+                        f"{path}.images[{image_index}].path is required",
+                        suggestion="Set a non-empty image path.",
+                    )
+                ]
     if block_type in {"bullets", "bullet", "numbered_list", "numberedList"}:
         if not _string_list(raw_block.get("items")):
             return [
@@ -672,6 +699,14 @@ def _validate_v2_block(raw_block: Any, *, path: str) -> list[PlanValidationIssue
             if isinstance(row, (list, tuple)):
                 for col_index, value in enumerate(row):
                     issues.extend(_computed_field_issues(value, path=f"{path}.rows[{row_index}][{col_index}]"))
+    elif block_type in {"image_grid", "imageGrid"}:
+        for image_index, image in enumerate(raw_block.get("images") or []):
+            if isinstance(image, Mapping):
+                issues.extend(_computed_field_issues(image.get("caption"), path=f"{path}.images[{image_index}].caption"))
+    elif block_type in {"approval_box", "approvalBox"}:
+        for label_index, label in enumerate(raw_block.get("labels") or []):
+            issues.extend(_computed_field_issues(label, path=f"{path}.labels[{label_index}]"))
+        issues.extend(_computed_field_issues(raw_block.get("delegated"), path=f"{path}.delegated"))
     elif block_type == "toc":
         issues.extend(_computed_field_issues(raw_block.get("title"), path=f"{path}.title"))
         for entry_index, entry in enumerate(raw_block.get("entries") or []):
@@ -1325,11 +1360,15 @@ def _normalize_v2_section(raw_section: Any, *, index: int) -> BuilderSection:
     if not isinstance(raw_section, Mapping):
         raise TypeError(f"sections[{index}] must be a mapping")
     raw_blocks = raw_section.get("blocks", raw_section.get("children"))
+    children: list[Any] = []
+    for block_index, raw_block in enumerate(raw_blocks or []):
+        normalized = _normalize_v2_block(raw_block, path=f"sections[{index}].blocks[{block_index}]")
+        if isinstance(normalized, tuple):
+            children.extend(normalized)
+        else:
+            children.append(normalized)
     return BuilderSection(
-        children=tuple(
-            _normalize_v2_block(raw_block, path=f"sections[{index}].blocks[{block_index}]")
-            for block_index, raw_block in enumerate(raw_blocks or [])
-        ),
+        children=tuple(children),
         page=_normalize_v2_page(raw_section.get("page")),
         margins=_normalize_v2_margins(raw_section.get("margins")),
         header=_normalize_v2_header_footer(raw_section.get("header"), kind="header"),
@@ -1455,6 +1494,23 @@ def _normalize_v2_block(raw_block: Any, *, path: str) -> Any:
                 for item in raw_block.get("columnWidths", raw_block.get("column_widths")) or ()
             ),
         )
+    if block_type in {"approval_box", "approvalBox"}:
+        labels = tuple(replace_computed_fields(str(item)) for item in _string_list(raw_block.get("labels")))
+        return BuilderApprovalBox(
+            labels=labels or None,
+            approver_rows=_int_value(
+                raw_block.get("approverRows", raw_block.get("approver_rows")),
+                default=2,
+            ),
+            delegated=(
+                replace_computed_fields(str(raw_block.get("delegated")))
+                if raw_block.get("delegated") is not None
+                else None
+            ),
+            header_shading=str(raw_block.get("headerShading", raw_block.get("header_shading")) or "EAF1FB"),
+        )
+    if block_type in {"image_grid", "imageGrid"}:
+        return _image_grid_builder_nodes(raw_block)
     if block_type == "image":
         return BuilderImage(
             path=str(raw_block.get("path") or ""),
@@ -1481,6 +1537,49 @@ def _normalize_v2_block(raw_block: Any, *, path: str) -> Any:
     raise ValueError(f"{path}.type is unsupported: {block_type!r}")
 
 
+def _image_grid_builder_nodes(raw_block: Mapping[str, Any]) -> tuple[Any, ...]:
+    block = build_image_grid(
+        [
+            {
+                "path": str(image.get("path") or ""),
+                "caption": replace_computed_fields(str(image.get("caption") or "")),
+            }
+            for image in raw_block.get("images") or ()
+            if isinstance(image, Mapping)
+        ],
+        columns=_int_value(raw_block.get("columns"), default=2),
+        image_width_mm=_optional_number(raw_block.get("imageWidthMm", raw_block.get("image_width_mm"))),
+    )
+    columns = int(block["columns"])
+    images = list(block["images"])
+    rows: list[tuple[str, ...]] = []
+    for offset in range(0, len(images), columns):
+        row = []
+        for image_index, image in enumerate(images[offset : offset + columns], start=offset + 1):
+            row.append(f"{image_index}. {image['caption']} ({Path(str(image['path'])).name})")
+        row.extend("" for _ in range(columns - len(row)))
+        rows.append(tuple(row))
+    image_width = _optional_number(raw_block.get("imageWidthMm", raw_block.get("image_width_mm")))
+    nodes: list[Any] = [
+        BuilderTable(
+            header=tuple(f"사진 {index + 1}" for index in range(columns)),
+            rows=tuple(rows),
+            header_shading=_optional_str(raw_block.get("headerShading", raw_block.get("header_shading"))) or "EAF1FB",
+            column_widths=tuple(1 for _ in range(columns)),
+        )
+    ]
+    for image_index, image in enumerate(images, start=1):
+        nodes.append(
+            BuilderImage(
+                path=str(image["path"]),
+                width_mm=image_width,
+                align=_optional_str(raw_block.get("align")) or "center",
+                caption=f"{image_index}. {image['caption']}",
+            )
+        )
+    return tuple(nodes)
+
+
 def _lower_plan_to_builder_document(plan: DocumentPlan) -> BuilderDocument:
     """Lower a normalized document plan to builder nodes.
 

hwpx/builder/__init__.py

@@ -18,6 +18,7 @@ from .core import (
     Run,
     Section,
     Table,
+    approval_box,
 )
 from .report import BuilderSaveReport, ReopenReport
 
@@ -40,4 +41,5 @@ __all__ = [
     "Run",
     "Section",
     "Table",
+    "approval_box",
 ]

hwpx/builder/core.py

@@ -7,6 +7,7 @@ from pathlib import Path
 from typing import Any, Mapping, Sequence
 
 from hwpx.document import HwpxDocument
+from hwpx.tools.package_validator import validate_editor_open_safety
 from hwpx.tools.package_validator import validate_package
 from hwpx.tools.validator import validate_document
 
@@ -71,8 +72,8 @@ class _BuilderPreset:
         if self.is_government_report:
             if run.bold and color is None:
                 color = "1F4E79"
-            if (run.bold or run.underline or run.highlight) and font is None:
-                font = "함초롬바탕"
+        if (run.bold or run.underline or run.highlight) and font is None:
+            font = "함초롬바탕"
         return {
             "bold": run.bold,
             "italic": run.italic,
@@ -361,6 +362,50 @@ class Table:
             table.set_column_widths(self.column_widths)
 
 
+def approval_box(
+    *,
+    labels: Sequence[str] | None = None,
+    approver_rows: int = 2,
+    delegated: str | None = None,
+    header_shading: str = "EAF1FB",
+) -> Table:
+    """Return a merged approval/sign-off table for official documents."""
+
+    normalized_labels = tuple(str(label).strip() for label in (labels or ("기안", "검토", "결재", "전결")) if str(label).strip())
+    if not normalized_labels:
+        normalized_labels = ("기안", "검토", "결재", "전결")
+    delegated_label = str(delegated or "").strip()
+    if delegated_label and delegated_label not in normalized_labels:
+        normalized_labels = (*normalized_labels, delegated_label)
+    row_count = max(int(approver_rows), 1)
+    rows = tuple(tuple("" for _ in normalized_labels) for _ in range(row_count))
+    if row_count < 2:
+        merges: tuple[str, ...] = ()
+    else:
+        merges = tuple(
+            f"{_spreadsheet_column_name(index)}2:{_spreadsheet_column_name(index)}{row_count + 1}"
+            for index in range(len(normalized_labels))
+        )
+    return Table(
+        header=normalized_labels,
+        rows=rows,
+        merges=merges,
+        header_shading=header_shading,
+        column_widths=tuple(1 for _ in normalized_labels),
+    )
+
+
+def _spreadsheet_column_name(index: int) -> str:
+    if index < 0:
+        raise ValueError("column index must be non-negative")
+    value = index + 1
+    letters: list[str] = []
+    while value:
+        value, remainder = divmod(value - 1, 26)
+        letters.append(chr(ord("A") + remainder))
+    return "".join(reversed(letters))
+
+
 @dataclass(frozen=True)
 class Image:
     path: str | PathLike[str] | bytes
@@ -576,13 +621,24 @@ def _merge_flags(*flag_sets: dict[str, bool]) -> dict[str, bool]:
     return merged
 
 
-def _hard_gates(package_report: object, document_report: object, reopen_report: ReopenReport) -> dict[str, str]:
+def _hard_gates(
+    package_report: object,
+    document_report: object,
+    reopen_report: ReopenReport,
+    editor_open_safety_report: object | None = None,
+) -> dict[str, str]:
     document_warnings = getattr(document_report, "warnings", ())
+    editor_open_safety_ok = (
+        True
+        if editor_open_safety_report is None
+        else bool(getattr(editor_open_safety_report, "ok", False))
+    )
     return {
         "package_validation": "pass" if getattr(package_report, "ok", False) else "fail",
         "document_errors": "pass" if getattr(document_report, "ok", False) else "fail",
         "schema_lint": "warning" if document_warnings else "pass",
         "reopen": "pass" if reopen_report.ok else "fail",
+        "editor_open_safety": "pass" if editor_open_safety_ok else "fail",
         "id_integrity": "unavailable",
     }
 
@@ -696,6 +752,7 @@ class Document:
         document.save_to_path(path)
         package_report = validate_package(path)
         document_report = validate_document(path)
+        editor_open_safety_report = validate_editor_open_safety(path)
         try:
             reopened_document = HwpxDocument.open(path)
             reopen_report = ReopenReport(ok=True, document=reopened_document)
@@ -713,8 +770,14 @@ class Document:
             validate_document=document_report,
             reopened=reopen_report,
             metadata=self.metadata.as_dict() if self.metadata is not None else {},
-            hard_gates=_hard_gates(package_report, document_report, reopen_report),
+            hard_gates=_hard_gates(
+                package_report,
+                document_report,
+                reopen_report,
+                editor_open_safety_report,
+            ),
             visual_review_required=visual_review_required,
             feature_flags=feature_flags,
+            editor_open_safety=editor_open_safety_report,
         )
         return report

hwpx/builder/report.py

@@ -6,7 +6,7 @@ from os import PathLike
 from typing import Any
 
 from hwpx.tools.id_integrity import IdIntegrityReport, check_id_integrity
-from hwpx.tools.package_validator import PackageValidationReport
+from hwpx.tools.package_validator import EditorOpenSafetyReport, PackageValidationReport
 from hwpx.tools.validator import ValidationReport
 
 
@@ -32,6 +32,7 @@ class BuilderSaveReport:
     visual_review_required: bool = False
     feature_flags: dict[str, bool] = field(default_factory=dict)
     id_integrity: IdIntegrityReport | None = None
+    editor_open_safety: EditorOpenSafetyReport | None = None
 
     def __post_init__(self) -> None:
         hard_gates = dict(self.hard_gates)
@@ -52,6 +53,11 @@ class BuilderSaveReport:
             "hard_gates": dict(self.hard_gates),
             "visual_review_required": self.visual_review_required,
             "feature_flags": dict(self.feature_flags),
+            "editor_open_safety": (
+                None
+                if self.editor_open_safety is None
+                else self.editor_open_safety.to_dict()
+            ),
             "validate_package": {
                 "ok": self.validate_package.ok,
                 "checked_parts": list(self.validate_package.checked_parts),
@@ -76,6 +82,16 @@ class BuilderSaveReport:
                 else {
                     "ok": self.id_integrity.ok,
                     "dangling": [str(item) for item in self.id_integrity.dangling],
+                    "orphan_bin_data": [
+                        {
+                            "item_id": item.item_id,
+                            "path": item.path,
+                            "aliases": list(item.aliases),
+                            "sources": list(item.sources),
+                            "severity": item.severity,
+                        }
+                        for item in self.id_integrity.orphan_bin_data
+                    ],
                     "ignored": [
                         {
                             "part": item.part,