python-hwpx 2.10.3__py3-none-any.whl → 2.11.1__py3-none-any.whl

hwpx/__init__.py

@@ -25,12 +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 (
@@ -48,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,
@@ -67,23 +119,59 @@ __all__ = [
     "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,
@@ -166,16 +168,30 @@ class DocumentStylePreset:
     heading_bold: bool = True
     heading_underline: bool = True
     table_header_bold: bool = True
+    title_size: int = 18
+    subtitle_size: int = 12
+    heading_size: int = 14
+    font: str = "함초롬바탕"
 
     def ensure_tokens(self, document: HwpxDocument) -> dict[str, str]:
         """Create/reuse run styles and return semantic token IDs."""
 
         return {
-            "title": document.ensure_run_style(bold=self.title_bold),
-            "subtitle": document.ensure_run_style(italic=self.subtitle_italic),
+            "title": document.ensure_run_style(
+                bold=self.title_bold,
+                size=self.title_size,
+                font=self.font,
+            ),
+            "subtitle": document.ensure_run_style(
+                italic=self.subtitle_italic,
+                size=self.subtitle_size,
+                font=self.font,
+            ),
             "heading": document.ensure_run_style(
                 bold=self.heading_bold,
                 underline=self.heading_underline,
+                size=self.heading_size,
+                font=self.font,
             ),
             "body": document.ensure_run_style(),
             "bullet": document.ensure_run_style(),
@@ -184,6 +200,25 @@ class DocumentStylePreset:
         }
 
 
+def _outline_style_refs(document: HwpxDocument, level: int) -> dict[str, str | int]:
+    """Return paragraph style refs for a HWP outline heading level, if available."""
+
+    safe_level = min(10, max(1, int(level)))
+    for style in document.styles.values():
+        name = str(style.name or "")
+        eng_name = str(style.eng_name or "")
+        if name == f"개요 {safe_level}" or eng_name == f"Outline {safe_level}":
+            refs: dict[str, str | int] = {}
+            style_id = style.raw_id if style.raw_id is not None else style.id
+            if style_id is None:
+                continue
+            refs["style_id_ref"] = style_id
+            if style.para_pr_id_ref is not None:
+                refs["para_pr_id_ref"] = int(style.para_pr_id_ref)
+            return refs
+    return {}
+
+
 def _plan_issue(
     code: str,
     path: str,
@@ -603,9 +638,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 +666,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 +732,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 +1393,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 +1527,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 +1570,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.
 
@@ -1618,6 +1750,7 @@ def _render_block(
             block.text,
             char_pr_id_ref=tokens["heading"],
             inherit_style=False,
+            **_outline_style_refs(document, block.level),
         )
         return
     if isinstance(block, BuilderParagraph):

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

@@ -25,6 +25,25 @@ _A4_HWP_SIZE = (59528, 84188)
 # changing default node contracts or the plan-v1 authoring style-token path.
 
 
+def _outline_style_refs(document: HwpxDocument, level: int) -> dict[str, str | int]:
+    """Return paragraph style refs for the built-in HWP outline level, if present."""
+
+    safe_level = min(10, max(1, int(level)))
+    for style in document.styles.values():
+        name = str(style.name or "")
+        eng_name = str(style.eng_name or "")
+        if name == f"개요 {safe_level}" or eng_name == f"Outline {safe_level}":
+            refs: dict[str, str | int] = {}
+            style_id = style.raw_id if style.raw_id is not None else style.id
+            if style_id is None:
+                continue
+            refs["style_id_ref"] = style_id
+            if style.para_pr_id_ref is not None:
+                refs["para_pr_id_ref"] = int(style.para_pr_id_ref)
+            return refs
+    return {}
+
+
 @dataclass(frozen=True)
 class _BuilderPreset:
     name: str = "default"
@@ -72,8 +91,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,
@@ -264,6 +283,7 @@ class Heading:
             section_index=section_index,
             char_pr_id_ref=char_pr_id,
             inherit_style=False,
+            **_outline_style_refs(document, self.level),
         )
 
 
@@ -362,6 +382,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

hwpx/builder/report.py

@@ -82,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,