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

hwpx_automation/ops_services/_border_fill.py

@@ -0,0 +1,283 @@
+# SPDX-License-Identifier: Apache-2.0
+
+"""Leaf helpers for table border-fill resolution, matching, and construction.
+
+Private to the ops_services package: imported only by ``tables.py``. This module
+holds no service class and depends solely on the standard library and the typed
+``upstream`` seam, so it can never participate in an import cycle.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import NamedTuple, Optional
+from xml.etree import ElementTree as ET
+
+from ..upstream import HH_NS, HwpxDocument
+
+
+class _BorderFillSpec(NamedTuple):
+    border_type: str
+    width_value: str
+    diagonal_width_value: str
+    width_token: str
+    diagonal_width_token: str
+    edge_color: Optional[str]
+    diagonal_color: Optional[str]
+    fill_color: Optional[str]
+
+
+def _normalize_border_length(value: Optional[str | float | int], default: str) -> str:
+    if value is None:
+        return default
+    if isinstance(value, (int, float)):
+        return f"{value:g} mm"
+    text = str(value).strip()
+    if not text:
+        return default
+    match = re.fullmatch(r"([0-9]+(?:\\.[0-9]+)?)\\s*([A-Za-z]+)?", text)
+    if match:
+        number, unit = match.groups()
+        unit = (unit or "mm").lower()
+        return f"{number} {unit}"
+    return text
+
+
+def _normalize_length_token(value: Optional[str]) -> str:
+    if not value:
+        return ""
+    return re.sub(r"\s+", "", str(value)).lower()
+
+
+def _resolve_border_fill_spec(
+    normalized_style: Optional[str],
+    normalized_border_color: Optional[str],
+    normalized_fill_color: Optional[str],
+    border_width: Optional[str | float | int],
+) -> _BorderFillSpec:
+    border_type = "NONE" if normalized_style == "none" else "SOLID"
+    if border_type == "NONE":
+        width_default = "0 mm"
+        diag_default = "0 mm"
+    else:
+        width_default = "0.12 mm"
+        diag_default = "0.1 mm"
+
+    width_value = _normalize_border_length(border_width, width_default)
+    if border_width is not None:
+        diagonal_width_value = _normalize_border_length(border_width, width_default)
+    else:
+        diagonal_width_value = _normalize_border_length(None, diag_default)
+    width_token = _normalize_length_token(width_value)
+    diagonal_width_token = _normalize_length_token(diagonal_width_value)
+
+    edge_color: Optional[str] = normalized_border_color
+    diagonal_color: Optional[str] = normalized_border_color
+    if border_type == "SOLID":
+        edge_color = normalized_border_color or "#000000"
+        diagonal_color = edge_color
+    # Non-solid borders retain the optional normalized color.
+    return _BorderFillSpec(
+        border_type=border_type,
+        width_value=width_value,
+        diagonal_width_value=diagonal_width_value,
+        width_token=width_token,
+        diagonal_width_token=diagonal_width_token,
+        edge_color=edge_color,
+        diagonal_color=diagonal_color,
+        fill_color=normalized_fill_color,
+    )
+
+
+def _shortcut_border_fill_id(
+    document: HwpxDocument,
+    normalized_style: Optional[str],
+    normalized_border_color: Optional[str],
+    normalized_fill_color: Optional[str],
+    border_width: Optional[str | float | int],
+) -> Optional[str]:
+    if normalized_style == "none" and not any(
+        [normalized_border_color, normalized_fill_color, border_width]
+    ):
+        return "0"
+
+    if (
+        normalized_style in {None, "solid"}
+        and normalized_border_color is None
+        and normalized_fill_color is None
+        and border_width is None
+    ):
+        return document.oxml.ensure_basic_border_fill()
+
+    return None
+
+
+def _border_fill_flags_match(existing: ET.Element) -> bool:
+    if (existing.get("threeD") or "0") != "0":
+        return False
+    if (existing.get("shadow") or "0") != "0":
+        return False
+    if (existing.get("centerLine") or "NONE").upper() != "NONE":
+        return False
+    if (existing.get("breakCellSeparateLine") or "0") != "0":
+        return False
+    return True
+
+
+def _border_fill_slashes_match(existing: ET.Element) -> bool:
+    for slash_name in ("slash", "backSlash"):
+        slash = existing.find(f"{HH_NS}{slash_name}")
+        if slash is None:
+            return False
+        if (slash.get("type") or "NONE").upper() != "NONE":
+            return False
+        if slash.get("Crooked", "0") != "0":
+            return False
+        if slash.get("isCounter", "0") != "0":
+            return False
+    return True
+
+
+def _border_fill_edges_match(
+    existing: ET.Element,
+    border_type: str,
+    width_token: str,
+    edge_color: Optional[str],
+) -> bool:
+    for child_name in ("leftBorder", "rightBorder", "topBorder", "bottomBorder"):
+        border_child = existing.find(f"{HH_NS}{child_name}")
+        if border_child is None:
+            return False
+        if (border_child.get("type") or "").upper() != border_type:
+            return False
+        if _normalize_length_token(border_child.get("width")) != width_token:
+            return False
+        if edge_color is not None:
+            if (border_child.get("color") or "").upper() != edge_color:
+                return False
+        else:
+            if border_child.get("color") not in (None, ""):
+                return False
+    return True
+
+
+def _border_fill_diagonal_matches(
+    existing: ET.Element,
+    border_type: str,
+    diagonal_width_token: str,
+    diagonal_color: Optional[str],
+) -> bool:
+    diagonal_child = existing.find(f"{HH_NS}diagonal")
+    if diagonal_child is None:
+        return False
+    expected_diagonal_type = "SOLID" if border_type == "SOLID" else "NONE"
+    if (diagonal_child.get("type") or "").upper() != expected_diagonal_type:
+        return False
+    if _normalize_length_token(diagonal_child.get("width")) != diagonal_width_token:
+        return False
+    if diagonal_color is not None:
+        if (diagonal_child.get("color") or "").upper() != diagonal_color:
+            return False
+    else:
+        if diagonal_child.get("color") not in (None, ""):
+            return False
+    return True
+
+
+def _border_fill_fill_matches(
+    existing: ET.Element, normalized_fill_color: Optional[str]
+) -> bool:
+    fill_brush = existing.find(f"{HH_NS}fillBrush")
+    if normalized_fill_color is None:
+        if fill_brush is not None:
+            return False
+    else:
+        if fill_brush is None:
+            return False
+        solid_brush = fill_brush.find(f"{HH_NS}solidBrush")
+        if solid_brush is None:
+            return False
+        if (solid_brush.get("type") or "SOLID").upper() != "SOLID":
+            return False
+        if (solid_brush.get("color") or "").upper() != normalized_fill_color:
+            return False
+    return True
+
+
+def _border_fill_matches(existing: ET.Element, spec: _BorderFillSpec) -> bool:
+    return (
+        _border_fill_flags_match(existing)
+        and _border_fill_slashes_match(existing)
+        and _border_fill_edges_match(
+            existing, spec.border_type, spec.width_token, spec.edge_color
+        )
+        and _border_fill_diagonal_matches(
+            existing, spec.border_type, spec.diagonal_width_token, spec.diagonal_color
+        )
+        and _border_fill_fill_matches(existing, spec.fill_color)
+    )
+
+
+def _find_matching_border_fill(
+    border_fills_element: ET.Element, spec: _BorderFillSpec
+) -> Optional[str]:
+    for candidate in border_fills_element.findall(f"{HH_NS}borderFill"):
+        identifier = candidate.get("id")
+        if not identifier:
+            continue
+        if _border_fill_matches(candidate, spec):
+            return identifier
+    return None
+
+
+def _build_border_fill_element(
+    border_fills_element: ET.Element, new_id: str, spec: _BorderFillSpec
+) -> None:
+    border_fill_element = ET.SubElement(
+        border_fills_element,
+        f"{HH_NS}borderFill",
+        {
+            "id": new_id,
+            "threeD": "0",
+            "shadow": "0",
+            "centerLine": "NONE",
+            "breakCellSeparateLine": "0",
+        },
+    )
+
+    for slash_name in ("slash", "backSlash"):
+        ET.SubElement(
+            border_fill_element,
+            f"{HH_NS}{slash_name}",
+            {"type": "NONE", "Crooked": "0", "isCounter": "0"},
+        )
+
+    def append_border(
+        name: str, *, width: str, color: Optional[str], kind: str
+    ) -> None:
+        attrs = {"type": kind}
+        if width:
+            attrs["width"] = width
+        if color is not None:
+            attrs["color"] = color
+        ET.SubElement(border_fill_element, f"{HH_NS}{name}", attrs)
+
+    for side in ("leftBorder", "rightBorder", "topBorder", "bottomBorder"):
+        append_border(
+            side, width=spec.width_value, color=spec.edge_color, kind=spec.border_type
+        )
+
+    append_border(
+        "diagonal",
+        width=spec.diagonal_width_value,
+        color=spec.diagonal_color,
+        kind="SOLID" if spec.border_type == "SOLID" else "NONE",
+    )
+
+    if spec.fill_color is not None:
+        fill_brush = ET.SubElement(border_fill_element, f"{HH_NS}fillBrush")
+        ET.SubElement(
+            fill_brush,
+            f"{HH_NS}solidBrush",
+            {"type": "SOLID", "color": spec.fill_color, "alpha": "255"},
+        )

hwpx_automation/ops_services/composition.py

@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Explicit composition root for bounded ``HwpxOps`` services."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .content_layout import ContentLayoutService
+from .context import DocumentContext
+from .form_fields import FormFieldService
+from .media import MediaService
+from .memo_style import MemoStyleService
+from .package_validation import PackageValidationService
+from .planning import PlanningService
+from .preview_export import PreviewExportService
+from .read_query import ReadQueryService
+from .save_policy import SavePolicy
+from .tables import TableService
+from .transactions import TransactionService
+
+
+@dataclass(frozen=True, slots=True)
+class HwpxOpsServices:
+    context: DocumentContext
+    save: SavePolicy
+    transactions: TransactionService
+    read_query: ReadQueryService
+    content_layout: ContentLayoutService
+    tables: TableService
+    form_fields: FormFieldService
+    media: MediaService
+    memo_style: MemoStyleService
+    preview_export: PreviewExportService
+    package_validation: PackageValidationService
+    planning: PlanningService
+
+
+def build_hwpx_ops_services(context: DocumentContext) -> HwpxOpsServices:
+    save = SavePolicy(context)
+    transactions = TransactionService(context, save)
+    memo_style = MemoStyleService(context, save)
+    return HwpxOpsServices(
+        context=context,
+        save=save,
+        transactions=transactions,
+        read_query=ReadQueryService(context),
+        content_layout=ContentLayoutService(context, save, transactions, memo_style),
+        tables=TableService(context, save, memo_style),
+        form_fields=FormFieldService(context, save, transactions),
+        media=MediaService(context, save),
+        memo_style=memo_style,
+        preview_export=PreviewExportService(context),
+        package_validation=PackageValidationService(context),
+        planning=PlanningService(context),
+    )

hwpx_automation/ops_services/content_layout.py

@@ -0,0 +1,322 @@
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional, Sequence
+
+from ..upstream import (
+    HP_NS,
+)
+
+from .context import DocumentContext
+from .save_policy import SavePolicy
+from .transactions import TransactionService
+from .memo_style import MemoStyleService
+
+logger = logging.getLogger("hwpx_automation.hwpx_ops")
+
+
+class ContentLayoutService:
+    def __init__(
+        self,
+        context: DocumentContext,
+        save: SavePolicy,
+        transactions: TransactionService,
+        styles: MemoStyleService,
+    ) -> None:
+        self._context = context
+        self._save = save
+        self._transactions = transactions
+        self._styles = styles
+
+    def replace_text_in_runs(
+        self,
+        path: str,
+        search: str,
+        replacement: str,
+        *,
+        style_filter: Optional[Dict[str, Any]] = None,
+        limit_per_run: Optional[int] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        filter_args: Dict[str, Any] = {}
+        if style_filter:
+            if "colorHex" in style_filter and style_filter["colorHex"]:
+                filter_args["text_color"] = self._styles._normalize_color(
+                    style_filter["colorHex"]
+                )
+            if "underline" in style_filter:
+                filter_args["underline_type"] = (
+                    "SOLID" if style_filter["underline"] else "NONE"
+                )
+            if "charPrIDRef" in style_filter and style_filter["charPrIDRef"]:
+                filter_args["char_pr_id_ref"] = style_filter["charPrIDRef"]
+        replaced = document.replace_text_in_runs(
+            search,
+            replacement,
+            limit=limit_per_run,
+            **filter_args,
+        )
+        if not dry_run and replaced:
+            self._save._save_document(document, resolved)
+        return {"replacedCount": replaced}
+
+    def add_paragraph(
+        self,
+        path: str,
+        text: str = "",
+        *,
+        section_index: Optional[int] = None,
+        run_style: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        char_id = self._styles._ensure_char_style(document, run_style)
+        paragraph = document.add_paragraph(
+            text,
+            section_index=section_index,
+            char_pr_id_ref=char_id,
+        )
+        paragraphs = self._context._iter_paragraphs(document)
+        index = len(paragraphs) - 1
+        element_id = id(paragraph.element)
+        for idx, candidate in enumerate(paragraphs):
+            if id(candidate.element) == element_id:
+                index = idx
+                break
+        self._save._save_document(document, resolved)
+        return {"paragraphIndex": index}
+
+    def insert_paragraphs_bulk(
+        self,
+        path: str,
+        paragraphs: Sequence[str],
+        *,
+        section_index: Optional[int] = None,
+        run_style: Optional[Dict[str, Any]] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        if not paragraphs:
+            return {"added": 0}
+
+        if dry_run:
+            return {"added": len(paragraphs)}
+
+        document, resolved = self._context._open_document(path)
+        char_id = self._styles._ensure_char_style(document, run_style)
+        count = 0
+        for text in paragraphs:
+            document.add_paragraph(
+                text,
+                section_index=section_index,
+                char_pr_id_ref=char_id,
+            )
+            count += 1
+        self._save._save_document(document, resolved)
+        return {"added": count}
+
+    def set_paragraph_format(
+        self,
+        path: str,
+        *,
+        paragraph_index: Optional[int] = None,
+        paragraph_indexes: Optional[Sequence[int]] = None,
+        alignment: Optional[str] = None,
+        line_spacing_percent: Optional[float] = None,
+        indent_left_mm: Optional[float] = None,
+        indent_right_mm: Optional[float] = None,
+        first_line_indent_mm: Optional[float] = None,
+        spacing_before_pt: Optional[float] = None,
+        spacing_after_pt: Optional[float] = None,
+        outline_level: Optional[int] = None,
+        keep_with_next: Optional[bool] = None,
+        keep_lines: Optional[bool] = None,
+        page_break_before: Optional[bool] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        result = document.set_paragraph_format(
+            paragraph_index=paragraph_index,
+            paragraph_indexes=paragraph_indexes,
+            alignment=alignment,
+            line_spacing_percent=line_spacing_percent,
+            indent_left_mm=indent_left_mm,
+            indent_right_mm=indent_right_mm,
+            first_line_indent_mm=first_line_indent_mm,
+            spacing_before_pt=spacing_before_pt,
+            spacing_after_pt=spacing_after_pt,
+            outline_level=outline_level,
+            keep_with_next=keep_with_next,
+            keep_lines=keep_lines,
+            page_break_before=page_break_before,
+        )
+        result.update({"ok": True, "filename": path})
+        return self._transactions._with_transaction_verification(
+            result, document, resolved, dry_run=dry_run
+        )
+
+    def set_page_setup(
+        self,
+        path: str,
+        *,
+        paper_size: Optional[str] = None,
+        width_mm: Optional[float] = None,
+        height_mm: Optional[float] = None,
+        orientation: Optional[str] = None,
+        margins_mm: Optional[Dict[str, float]] = None,
+        margin_left_mm: Optional[float] = None,
+        margin_right_mm: Optional[float] = None,
+        margin_top_mm: Optional[float] = None,
+        margin_bottom_mm: Optional[float] = None,
+        header_margin_mm: Optional[float] = None,
+        footer_margin_mm: Optional[float] = None,
+        gutter_mm: Optional[float] = None,
+        columns: Optional[int] = None,
+        column_gap_mm: Optional[float] = None,
+        section_index: Optional[int] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        result = document.set_page_setup(
+            paper_size=paper_size,
+            width_mm=width_mm,
+            height_mm=height_mm,
+            orientation=orientation,
+            margins_mm=margins_mm,
+            margin_left_mm=margin_left_mm,
+            margin_right_mm=margin_right_mm,
+            margin_top_mm=margin_top_mm,
+            margin_bottom_mm=margin_bottom_mm,
+            header_margin_mm=header_margin_mm,
+            footer_margin_mm=footer_margin_mm,
+            gutter_mm=gutter_mm,
+            columns=columns,
+            column_gap_mm=column_gap_mm,
+            section_index=section_index,
+        )
+        result.update({"ok": True, "filename": path})
+        return self._transactions._with_transaction_verification(
+            result, document, resolved, dry_run=dry_run
+        )
+
+    def _header_footer_payload(
+        self,
+        wrapper: Any,
+        *,
+        kind: str,
+        page_type: str,
+    ) -> Dict[str, Any]:
+        element = getattr(wrapper, "element", None)
+        page_number_count = 0
+        if element is not None and hasattr(element, "iter"):
+            page_number_count = sum(1 for _ in element.iter(f"{HP_NS}pageNum"))
+        return {
+            "kind": kind,
+            "pageType": page_type,
+            "id": getattr(wrapper, "id", None),
+            "text": getattr(wrapper, "text", ""),
+            "pageNumberCount": page_number_count,
+        }
+
+    def set_header_footer(
+        self,
+        path: str,
+        *,
+        kind: str,
+        text: Optional[str] = None,
+        content: Optional[Sequence[Dict[str, Any]]] = None,
+        section_index: Optional[int] = None,
+        page_type: str = "BOTH",
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        wrapper = document.set_header_footer(
+            kind=kind,
+            text=text,
+            content=content,
+            section_index=section_index,
+            page_type=page_type,
+        )
+        result = {
+            "ok": True,
+            "filename": path,
+            "headerFooter": self._header_footer_payload(
+                wrapper,
+                kind=kind,
+                page_type=page_type,
+            ),
+        }
+        return self._transactions._with_transaction_verification(
+            result, document, resolved, dry_run=dry_run
+        )
+
+    def set_page_number(
+        self,
+        path: str,
+        *,
+        target: str = "footer",
+        page_type: str = "BOTH",
+        format: str = "page",
+        align: str = "CENTER",
+        position: str = "BOTTOM_CENTER",
+        prefix: str = "",
+        suffix: str = "",
+        format_type: Optional[str] = None,
+        section_index: Optional[int] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        wrapper = document.set_page_number(
+            target=target,
+            page_type=page_type,
+            format=format,
+            align=align,
+            position=position,
+            prefix=prefix,
+            suffix=suffix,
+            format_type=format_type,
+            section_index=section_index,
+        )
+        result = {
+            "ok": True,
+            "filename": path,
+            "target": target,
+            "format": format,
+            "headerFooter": self._header_footer_payload(
+                wrapper,
+                kind=target,
+                page_type=page_type,
+            ),
+        }
+        return self._transactions._with_transaction_verification(
+            result, document, resolved, dry_run=dry_run
+        )
+
+    def set_list_format(
+        self,
+        path: str,
+        *,
+        paragraph_index: Optional[int] = None,
+        paragraph_indexes: Optional[Sequence[int]] = None,
+        kind: str = "bullet",
+        level: int = 1,
+        bullet_char: Optional[str] = None,
+        number_format: Optional[str] = None,
+        start: Optional[int] = None,
+        dry_run: bool = False,
+    ) -> Dict[str, Any]:
+        document, resolved = self._context._open_document(path)
+        result = document.set_list_format(
+            paragraph_index=paragraph_index,
+            paragraph_indexes=paragraph_indexes,
+            kind=kind,
+            level=level,
+            bullet_char=bullet_char,
+            number_format=number_format,
+            start=start,
+        )
+        result.update({"ok": True, "filename": path})
+        return self._transactions._with_transaction_verification(
+            result, document, resolved, dry_run=dry_run
+        )