python-hwpx 5.0.2__tar.gz → 5.1.1__tar.gz

{python_hwpx-5.0.2/src/python_hwpx.egg-info → python_hwpx-5.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.0.2
+Version: 5.1.1
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.0.2 → python_hwpx-5.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.0.2"
+version = "5.1.1"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-5.0.2 → python_hwpx-5.1.1}/src/hwpx/_document/fields.py

@@ -211,10 +211,16 @@ def _form_field_payload(
         name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
-        prompt = _field_parameter_value(parameters, *_FORM_FIELD_PARAM_NAMES)
+        # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
+        prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
+    memo = _field_parameter_value(parameters, "HelpState", "memo")
+    dirty = (field_begin.get("dirty") or "").strip()
+    # Contract: while dirty != "1" the content between begin/end is the prompt
+    # placeholder (screen-only, not printed), not a user value.
+    is_placeholder = dirty != "1" and bool(prompt) and current_value == prompt
     return {
         "index": index,
         "field_id": _field_identifier(field_begin),
@@ -223,9 +229,13 @@ def _form_field_payload(
         "name": name,
         "prompt": prompt,
         "instruction": instruction,
+        "memo": memo,
+        "dirty": dirty,
+        "is_placeholder": is_placeholder,
         "current_value": current_value,
         "field_type": field_begin.get("type", ""),
         "control_type": ctrl.get("type", ""),
+        "_field_begin": field_begin,
         "section_index": section_index,
         "paragraph_index": paragraph_index,
         "paragraph_index_in_section": paragraph_index_in_section,
@@ -320,6 +330,62 @@ def list_form_fields(doc: "HwpxDocument") -> list[dict[str, Any]]:
     ]
 
 
+_PROMPT_TEXT_COLOR = "#FF0000"
+
+
+def add_form_field(
+    doc: "HwpxDocument",
+    name: str,
+    *,
+    prompt: str = "",
+    memo: str = "",
+    editable: bool = True,
+    paragraph: Any | None = None,
+    section: Any | None = None,
+    section_index: int | None = None,
+) -> dict[str, Any]:
+    """Create a click-here (누름틀) form field and return its field payload.
+
+    The emitted XML follows the real-Hancom CLICKHERE contract
+    (reverse-engineered from Hancom Office 12.0.0.3288 gold documents). The
+    prompt (안내문) is materialized as a screen-only red-italic run, exactly as
+    Hancom authors it. The created field is immediately re-read through the
+    standard ``list_form_fields`` matcher — creation fails loudly if the
+    standard consumer would not recognize it (no special-casing by design).
+    """
+
+    if not str(name).strip():
+        raise ValueError("form field name must be a non-empty string")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index, include_run=False,
+        )
+
+    prompt_char_pr: str | None = None
+    if _sanitize_field_text(prompt):
+        prompt_char_pr = doc.ensure_run_style(italic=True, color=_PROMPT_TEXT_COLOR)
+
+    control = paragraph.add_form_field(
+        name,
+        prompt=prompt,
+        memo=memo,
+        editable=editable,
+        prompt_char_pr_id_ref=prompt_char_pr,
+    )
+    _clear_form_field_layout_cache(paragraph.element)
+
+    field_begin = control.element.find(f"{_HP}fieldBegin")
+    created_id = field_begin.get("id", "") if field_begin is not None else ""
+    for match in _iter_form_field_matches(doc):
+        if match.get("id") == created_id:
+            return {
+                key: value for key, value in match.items() if not key.startswith("_")
+            }
+    raise RuntimeError(
+        "created form field was not recognized by the standard form-field matcher"
+    )
+
+
 def _select_form_field(
     doc: "HwpxDocument",
     matches: Sequence[dict[str, Any]],
@@ -447,9 +513,23 @@ def fill_form_field(
             node.text = ""
             for child in list(node):
                 child.tail = ""
+        if match.get("is_placeholder"):
+            # Contract (P0 gold): Hancom swaps the screen-only prompt style for
+            # the surrounding style when a value replaces the placeholder.
+            begin_run = runs[int(match["_begin_run_index"])]
+            begin_ref = begin_run.get("charPrIDRef")
+            primary_run = primary.getparent()
+            if begin_ref is not None and primary_run is not None:
+                primary_run.set("charPrIDRef", begin_ref)
     else:
         _insert_form_field_text_run(doc, match, sanitized)
 
+    # Contract (P0 gold): a field that went through fill machinery carries
+    # dirty="1"; while dirty != "1" readers treat the content as the prompt.
+    field_begin = match.get("_field_begin")
+    if field_begin is not None:
+        field_begin.set("dirty", "1")
+
     if fit_result is not None:
         _apply_form_field_fit_style(doc, match, fit_result)
 

{python_hwpx-5.0.2 → python_hwpx-5.1.1}/src/hwpx/document.py

@@ -1388,6 +1388,48 @@ class HwpxDocument:
             section_index=section_index,
         )
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a click-here (누름틀) form field. **Experimental contract.**
+
+        Emits the real-Hancom CLICKHERE shape (안내문 placeholder run included)
+        so the created field is indistinguishable from a Hancom-authored one:
+        ``list_form_fields``/``fill_form_field`` recognize it with no
+        special-casing, and real Hancom Office enumerates and fills it.
+
+        Args:
+            name: Field name (non-empty).
+            prompt: 안내문 shown while the field is empty. Screen-only —
+                Hancom does not print it.
+            memo: Help text (``HelpState``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+
+        Returns:
+            The created field's payload, same shape as a ``list_form_fields``
+            entry.
+        """
+
+        return _fields.add_form_field(
+            self,
+            name,
+            prompt=prompt,
+            memo=memo,
+            editable=editable,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+        )
+
 
     def set_page_size(
         self,

{python_hwpx-5.0.2 → python_hwpx-5.1.1}/src/hwpx/oxml/paragraph.py

@@ -27,7 +27,7 @@ from ._document_primitives import (
     _sanitize_text,
 )
 from .memo import HwpxOxmlNote
-from .namespaces import tag_local_name
+from .namespaces import XML_NS, tag_local_name
 from .objects import (
     HwpxOxmlInlineObject,
     HwpxOxmlShape,
@@ -834,6 +834,105 @@ class HwpxOxmlParagraph:
         self.section.mark_dirty()
         return HwpxOxmlInlineObject(ctrl1, self)
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        prompt_char_pr_id_ref: str | int | None = None,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a click-here (누름틀) form field at the end of this paragraph.
+
+        Emits the real-Hancom CLICKHERE shape (reverse-engineered from Hancom
+        Office 12.0.0.3288 gold documents):
+        a ``fieldBegin`` ctrl run carrying the ``Prop``/``Command``/``Direction``/
+        ``HelpState`` parameters, an optional prompt run showing *prompt* (the
+        안내문, screen-only — Hancom does not print it), and a ``fieldEnd`` ctrl
+        run. ``Command`` lengths count UTF-16 characters, so values may contain
+        spaces. ``id``/``fieldid`` values are semantically free — Hancom reissues
+        its own on save.
+
+        Args:
+            name: Field name used by ``list_form_fields``/``fill_form_field``.
+            prompt: 안내문 text shown while the field is empty (``Direction``).
+            memo: Help text (``HelpState``).
+            prompt_char_pr_id_ref: charPr for the prompt run (callers normally
+                pass a red-italic style; Hancom uses one).
+
+        Returns:
+            The ``<hp:ctrl>`` element wrapping the ``<hp:fieldBegin>``.
+        """
+        field_id = _object_id()
+        field_instance_id = _object_id()
+        direction = _sanitize_text(prompt)
+        help_state = _sanitize_text(memo)
+
+        # Run 1: fieldBegin with the CLICKHERE parameter block
+        run1 = self._create_run_for_object(char_pr_id_ref=char_pr_id_ref)
+        ctrl1 = _append_child(run1, f"{_HP}ctrl", {})
+        field_begin = _append_child(ctrl1, f"{_HP}fieldBegin", {
+            "id": field_id,
+            "type": "CLICK_HERE",
+            "name": _sanitize_text(name),
+            "editable": "1" if editable else "0",
+            "dirty": "0",
+            "zorder": "-1",
+            "fieldid": field_instance_id,
+            "metaTag": "",
+        })
+        payload = (
+            f"Direction:wstring:{len(direction)}:{direction} "
+            f"HelpState:wstring:{len(help_state)}:{help_state} "
+        )
+        param_count = 2 + (1 if direction else 0) + (1 if help_state else 0)
+        parameters = _append_child(
+            field_begin, f"{_HP}parameters", {"cnt": str(param_count), "name": ""}
+        )
+        prop = _append_child(parameters, f"{_HP}integerParam", {"name": "Prop"})
+        prop.text = "9"
+        command = _append_child(parameters, f"{_HP}stringParam", {
+            "name": "Command",
+            f"{{{XML_NS}}}space": "preserve",
+        })
+        command.text = f"Clickhere:set:{len(payload)}:{payload} "
+        if direction:
+            direction_param = _append_child(
+                parameters, f"{_HP}stringParam", {"name": "Direction"}
+            )
+            direction_param.text = direction
+        if help_state:
+            help_param = _append_child(
+                parameters, f"{_HP}stringParam", {"name": "HelpState"}
+            )
+            help_param.text = help_state
+
+        # Run 2: the prompt placeholder (only while a prompt exists)
+        if direction:
+            run2 = self._create_run_for_object(
+                char_pr_id_ref=(
+                    prompt_char_pr_id_ref
+                    if prompt_char_pr_id_ref is not None
+                    else char_pr_id_ref
+                ),
+            )
+            prompt_text = _append_child(run2, f"{_HP}t", {})
+            prompt_text.text = direction
+
+        # Run 3: fieldEnd + trailing empty text node (gold shape)
+        run3 = self._create_run_for_object(char_pr_id_ref=char_pr_id_ref)
+        ctrl3 = _append_child(run3, f"{_HP}ctrl", {})
+        _append_child(ctrl3, f"{_HP}fieldEnd", {
+            "beginIDRef": field_id,
+            "fieldid": field_instance_id,
+        })
+        _append_child(run3, f"{_HP}t", {})
+
+        self.section.mark_dirty()
+        return HwpxOxmlInlineObject(ctrl1, self)
+
     @property
     def bookmarks(self) -> list[str]:
         """Return the names of all bookmarks in this paragraph."""

{python_hwpx-5.0.2 → python_hwpx-5.1.1/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.0.2
+Version: 5.1.1
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-5.0.2 → python_hwpx-5.1.1}/src/python_hwpx.egg-info/SOURCES.txt

@@ -137,6 +137,7 @@ tests/test_equation_render.py
 tests/test_error_messages.py
 tests/test_evalplan_core_primitives.py
 tests/test_existing_document_format_editing.py
+tests/test_form_field_authoring.py
 tests/test_form_fields.py
 tests/test_form_fill_core_primitives.py
 tests/test_form_fit.py

python_hwpx-5.1.1/tests/test_form_field_authoring.py

@@ -0,0 +1,222 @@
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from hwpx import HwpxDocument
+from hwpx.tools.package_validator import validate_editor_open_safety
+
+import pytest
+
+HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+HH = "{http://www.hancom.co.kr/hwpml/2011/head}"
+DATA = Path(__file__).parent / "data"
+
+
+def _roundtrip(doc: HwpxDocument) -> HwpxDocument:
+    buffer = io.BytesIO()
+    doc.save_to_stream(buffer)
+    buffer.seek(0)
+    return HwpxDocument.open(buffer)
+
+
+def _field_begin(doc: HwpxDocument, name: str):
+    for section in doc.sections:
+        for fb in section.element.iter(f"{HP}fieldBegin"):
+            if fb.get("name") == name:
+                return fb
+    raise AssertionError(f"fieldBegin not found: {name}")
+
+
+class TestGoldContractShape:
+    """The emitted XML must match the real-Hancom CLICKHERE gold pair
+    (specs/053-formfield-authoring/evidence/p0/clickhere-contract.md)."""
+
+    def test_field_begin_attributes(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("성명", prompt="이름 입력", memo="도움말")
+        fb = _field_begin(doc, "성명")
+        assert fb.get("type") == "CLICK_HERE"
+        assert fb.get("editable") == "1"
+        assert fb.get("dirty") == "0"
+        assert fb.get("zorder") == "-1"
+        assert fb.get("metaTag") == ""
+        assert fb.get("id") and fb.get("fieldid")
+
+    def test_command_serialization_counts_characters(self) -> None:
+        # Korean + spaces inside values: lengths are UTF-16 character counts.
+        doc = HwpxDocument.new()
+        doc.add_form_field("f", prompt="안내 문", memo="m 1")
+        fb = _field_begin(doc, "f")
+        params = {
+            p.get("name"): (p.text or "")
+            for p in fb.find(f"{HP}parameters")
+        }
+        payload = "Direction:wstring:4:안내 문 HelpState:wstring:3:m 1 "
+        assert params["Command"] == f"Clickhere:set:{len(payload)}:{payload} "
+        assert params["Direction"] == "안내 문"
+        assert params["HelpState"] == "m 1"
+        assert params["Prop"] == "9"
+        command_param = fb.find(f"{HP}parameters/{HP}stringParam[@name='Command']")
+        assert command_param.get(
+            "{http://www.w3.org/XML/1998/namespace}space"
+        ) == "preserve"
+
+    def test_param_count_omits_empty_entries(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("only_name")
+        fb = _field_begin(doc, "only_name")
+        parameters = fb.find(f"{HP}parameters")
+        assert parameters.get("cnt") == "2"
+        names = [p.get("name") for p in parameters]
+        assert names == ["Prop", "Command"]
+
+    def test_prompt_run_is_red_italic_and_field_end_pairs(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("f", prompt="누르세요")
+        fb = _field_begin(doc, "f")
+        paragraph = fb.getparent().getparent().getparent()
+        runs = [child for child in paragraph if child.tag == f"{HP}run"]
+        begin_index = next(
+            i for i, run in enumerate(runs)
+            if run.find(f"{HP}ctrl/{HP}fieldBegin") is not None
+        )
+        prompt_run = runs[begin_index + 1]
+        assert prompt_run.find(f"{HP}t").text == "누르세요"
+        char_pr = doc.headers[0].element.find(
+            f".//{HH}charPr[@id='{prompt_run.get('charPrIDRef')}']"
+        )
+        assert char_pr.get("textColor", "").upper() == "#FF0000"
+        assert char_pr.find(f"{HH}italic") is not None
+        end_run = runs[begin_index + 2]
+        fe = end_run.find(f"{HP}ctrl/{HP}fieldEnd")
+        assert fe.get("beginIDRef") == fb.get("id")
+        assert fe.get("fieldid") == fb.get("fieldid")
+        assert end_run.find(f"{HP}t") is not None
+
+    def test_no_prompt_run_when_prompt_empty(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("bare")
+        fb = _field_begin(doc, "bare")
+        paragraph = fb.getparent().getparent().getparent()
+        runs = [child for child in paragraph if child.tag == f"{HP}run"]
+        begin_index = next(
+            i for i, run in enumerate(runs)
+            if run.find(f"{HP}ctrl/{HP}fieldBegin") is not None
+        )
+        assert runs[begin_index + 1].find(f"{HP}ctrl/{HP}fieldEnd") is not None
+
+
+class TestRoundTrip:
+    """Created fields must be consumed by the standard list/fill APIs with no
+    special-casing, across a save/reopen boundary."""
+
+    def test_create_save_reopen_list(self) -> None:
+        doc = HwpxDocument.new()
+        created = doc.add_form_field("부서", prompt="부서 입력", memo="조직명")
+        assert created["name"] == "부서"
+        assert created["prompt"] == "부서 입력"
+        assert created["memo"] == "조직명"
+        assert created["is_placeholder"] is True
+        assert created["has_end"] is True
+
+        reopened = _roundtrip(doc)
+        fields = reopened.list_form_fields()
+        assert [f["name"] for f in fields] == ["부서"]
+        field = fields[0]
+        assert field["dirty"] == "0"
+        assert field["is_placeholder"] is True
+        assert field["current_value"] == "부서 입력"
+
+    def test_fill_swaps_placeholder_style_and_sets_dirty(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("성명", prompt="이름 입력")
+        reopened = _roundtrip(doc)
+        response = reopened.fill_form_field("홍길동", name="성명")
+        assert response["ok"] is True
+        field = response["field"]
+        assert field["current_value"] == "홍길동"
+        assert field["dirty"] == "1"
+        assert field["is_placeholder"] is False
+
+        fb = _field_begin(reopened, "성명")
+        paragraph = fb.getparent().getparent().getparent()
+        runs = [child for child in paragraph if child.tag == f"{HP}run"]
+        begin_index = next(
+            i for i, run in enumerate(runs)
+            if run.find(f"{HP}ctrl/{HP}fieldBegin") is not None
+        )
+        # value run must carry the surrounding style, not the red prompt style
+        assert (
+            runs[begin_index + 1].get("charPrIDRef")
+            == runs[begin_index].get("charPrIDRef")
+        )
+
+        final = _roundtrip(reopened)
+        assert final.list_form_fields()[0]["current_value"] == "홍길동"
+
+    def test_field_in_table_cell(self) -> None:
+        doc = HwpxDocument.new()
+        table = doc.add_table(2, 2)
+        cell_paragraph = table.cell(0, 0).paragraphs[0]
+        doc.add_form_field("셀필드", prompt="셀 입력", paragraph=cell_paragraph)
+        reopened = _roundtrip(doc)
+        fields = reopened.list_form_fields()
+        assert [f["name"] for f in fields] == ["셀필드"]
+        reopened.fill_form_field("값123", name="셀필드")
+        assert reopened.list_form_fields()[0]["current_value"] == "값123"
+
+    def test_multiple_fields_pair_independently(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("a", prompt="가")
+        doc.add_form_field("b")
+        doc.add_form_field("c", prompt="다", memo="m")
+        reopened = _roundtrip(doc)
+        fields = reopened.list_form_fields()
+        assert [f["name"] for f in fields] == ["a", "b", "c"]
+        assert all(f["has_end"] for f in fields)
+        begin_ids = {f["id"] for f in fields}
+        assert len(begin_ids) == 3
+
+    def test_open_safety(self) -> None:
+        doc = HwpxDocument.new()
+        doc.add_form_field("f", prompt="입력")
+        buffer = io.BytesIO()
+        doc.save_to_stream(buffer)
+        report = validate_editor_open_safety(buffer.getvalue())
+        assert report.ok, report
+
+
+class TestValidation:
+    def test_blank_name_rejected(self) -> None:
+        doc = HwpxDocument.new()
+        with pytest.raises(ValueError):
+            doc.add_form_field("   ")
+
+    def test_illegal_control_chars_sanitized(self) -> None:
+        doc = HwpxDocument.new()
+        created = doc.add_form_field("ok", prompt="안내\x00문")
+        assert created["prompt"] == "안내문"
+
+
+class TestHancomGoldFixtures:
+    """Reader regression against real Hancom-authored CLICKHERE documents
+    (P0 gold pair, Hancom 12.0.0.3288)."""
+
+    def test_gold_empty_reads_prompt_memo_placeholder(self) -> None:
+        doc = HwpxDocument.open(DATA / "clickhere_gold_empty.hwpx")
+        (field,) = doc.list_form_fields()
+        assert field["name"] == "NAMETEXT_THREE"
+        assert field["field_type"] == "CLICK_HERE"
+        assert field["prompt"] == "DIRTEXT_ONE"
+        assert field["memo"] == "MEMOTEXT_TWO"
+        assert field["dirty"] == "0"
+        assert field["is_placeholder"] is True
+        assert field["current_value"] == "DIRTEXT_ONE"
+
+    def test_gold_filled_reads_value_not_placeholder(self) -> None:
+        doc = HwpxDocument.open(DATA / "clickhere_gold_filled.hwpx")
+        (field,) = doc.list_form_fields()
+        assert field["current_value"] == "FILLED_VALUE_X"
+        assert field["dirty"] == "1"
+        assert field["is_placeholder"] is False