python-hwpx 5.6.0__tar.gz → 5.7.0__tar.gz

{python_hwpx-5.6.0/src/python_hwpx.egg-info → python_hwpx-5.7.0}/PKG-INFO

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

{python_hwpx-5.6.0 → python_hwpx-5.7.0}/pyproject.toml

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

{python_hwpx-5.6.0 → python_hwpx-5.7.0}/src/hwpx/_document/fields.py

@@ -386,6 +386,121 @@ def add_form_field(
     )
 
 
+_CHECK_BOX_TAG = f"{_HP}checkBtn"
+
+
+def _iter_check_boxes(doc: "HwpxDocument") -> list[dict[str, Any]]:
+    """Every ``<hp:checkBtn>`` in document order, with its owning element."""
+
+    found: list[dict[str, Any]] = []
+    index = 0
+    for section_index, section in enumerate(doc.sections):
+        for element in section.element.iter(_CHECK_BOX_TAG):
+            found.append(
+                {
+                    "index": index,
+                    "sectionIndex": section_index,
+                    "name": element.get("name", ""),
+                    "caption": element.get("caption", ""),
+                    "checked": element.get("value", "").upper() == "CHECKED",
+                    "value": element.get("value", ""),
+                    "_element": element,
+                    "_section": section,
+                }
+            )
+            index += 1
+    return found
+
+
+def list_check_boxes(doc: "HwpxDocument") -> list[dict[str, Any]]:
+    """Return check-box form objects in document order."""
+
+    return [
+        {key: value for key, value in match.items() if not key.startswith("_")}
+        for match in _iter_check_boxes(doc)
+    ]
+
+
+def add_check_box(
+    doc: "HwpxDocument",
+    caption: str,
+    *,
+    checked: bool = False,
+    name: str | None = None,
+    paragraph: Any | None = None,
+    section: Any | None = None,
+    section_index: int | None = None,
+) -> dict[str, Any]:
+    """Create a check-box form object and return its payload.
+
+    The emitted XML follows the check-box contract measured against real
+    Hancom (specs/060): ``value`` selects ☑/□ and the ``<hp:formCharPr>`` child
+    is mandatory — without it Hancom refuses the document. The created object is
+    re-read through the standard :func:`list_check_boxes` reader, so creation
+    fails loudly if the ordinary consumer would not see it.
+    """
+
+    if not str(caption).strip():
+        raise ValueError("check box caption must be a non-empty string")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index, include_run=False,
+        )
+
+    control = paragraph.add_check_box(caption, checked=checked, name=name)
+    _clear_form_field_layout_cache(paragraph.element)
+
+    created_name = control.element.get("name", "")
+    for match in _iter_check_boxes(doc):
+        if match["_element"] is control.element:
+            return {
+                key: value for key, value in match.items() if not key.startswith("_")
+            }
+    raise RuntimeError(
+        f"created check box {created_name!r} was not recognized by the standard reader"
+    )
+
+
+def set_check_box(
+    doc: "HwpxDocument",
+    checked: bool,
+    *,
+    index: int | None = None,
+    name: str | None = None,
+) -> dict[str, Any]:
+    """Set a check box's state, selecting it by ``index`` or ``name``.
+
+    Exactly one selector is required — an ambiguous or missing selector is a
+    typed refusal, never a guess.
+    """
+
+    if (index is None) == (name is None):
+        raise ValueError("provide exactly one of index or name")
+    matches = _iter_check_boxes(doc)
+    if index is not None:
+        chosen = [m for m in matches if m["index"] == index]
+        if not chosen:
+            raise ValueError(f"check box index not found: {index}")
+    else:
+        wanted = str(name).strip()
+        chosen = [m for m in matches if m["name"] == wanted]
+        if not chosen:
+            raise ValueError(f"check box name not found: {wanted}")
+        if len(chosen) > 1:
+            raise ValueError(
+                f"check box name is ambiguous ({len(chosen)} matches): {wanted}"
+            )
+    match = chosen[0]
+    match["_element"].set("value", "CHECKED" if checked else "UNCHECKED")
+    match["_section"].mark_dirty()
+    return {
+        key: value
+        for key, value in {**match, "checked": bool(checked),
+                           "value": "CHECKED" if checked else "UNCHECKED"}.items()
+        if not key.startswith("_")
+    }
+
+
 def _select_form_field(
     doc: "HwpxDocument",
     matches: Sequence[dict[str, Any]],

{python_hwpx-5.6.0 → python_hwpx-5.7.0}/src/hwpx/document.py

@@ -1462,6 +1462,68 @@ class HwpxDocument:
             section_index=section_index,
         )
 
+    def list_check_boxes(self) -> list[dict[str, Any]]:
+        """Return check-box form objects (체크박스) in document order.
+
+        Each entry carries ``index``/``name``/``caption``/``checked``.
+        """
+
+        return _fields.list_check_boxes(self)
+
+    def add_check_box(
+        self,
+        caption: str,
+        *,
+        checked: bool = False,
+        name: str | None = None,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a check-box form object (체크박스). **Experimental contract.**
+
+        Real Hancom draws ☑ when *checked* and □ otherwise, with *caption* beside
+        the box and present in the rendered text layer. The created object is
+        read back through :meth:`list_check_boxes` with no special-casing.
+
+        Note:
+            Korean government forms specify a text ``[ ]`` + √ convention rather
+            than this form object (시행규칙 별표 4 제10호), so this primitive is
+            for forms that genuinely use Hancom check boxes — not for 공문서.
+
+        Args:
+            caption: Label drawn beside the box (non-empty).
+            checked: Initial state.
+            name: Object name; generated when omitted.
+            paragraph: Target paragraph (e.g. a table cell). A new paragraph is
+                appended to *section* when omitted.
+        """
+
+        return _fields.add_check_box(
+            self,
+            caption,
+            checked=checked,
+            name=name,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+        )
+
+    def set_check_box(
+        self,
+        checked: bool,
+        *,
+        index: int | None = None,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        """Set a check box's state, selecting it by ``index`` or ``name``.
+
+        Exactly one selector is required; an ambiguous name is refused rather
+        than guessed.
+        """
+
+        return _fields.set_check_box(self, checked, index=index, name=name)
+
 
     def add_chart(
         self,

{python_hwpx-5.6.0 → python_hwpx-5.7.0}/src/hwpx/oxml/paragraph.py

@@ -1147,6 +1147,91 @@ class HwpxOxmlParagraph:
         self.section.mark_dirty()
         return HwpxOxmlInlineObject(ctrl1, self)
 
+    def add_check_box(
+        self,
+        caption: str,
+        *,
+        checked: bool = False,
+        name: str | None = None,
+        width: int = 9921,
+        height: int = 1984,
+        char_pr_id_ref: str | int | None = None,
+    ) -> HwpxOxmlInlineObject:
+        """Insert a check-box form object (체크박스) at the end of this paragraph.
+
+        Emits the real-Hancom ``<hp:checkBtn>`` shape. Unlike the click-here
+        field this is **not** wrapped in ``<hp:ctrl>`` — it is a direct child of
+        the run, beside the ``<hp:t>`` node.
+
+        Hancom refuses to open a document whose ``checkBtn`` lacks
+        ``<hp:formCharPr>`` (measured: the same file with the element present
+        opens, without it Hancom reports a read error and produces nothing), so
+        the child block is always emitted. ``caption`` is drawn next to the box
+        and appears in the rendered text layer; ``checked`` selects the
+        ``CHECKED``/``UNCHECKED`` value that draws ☑ or □.
+
+        Args:
+            caption: Label drawn beside the box.
+            checked: Initial state.
+            name: Object name. Defaults to a generated ``CheckBox<N>``.
+            width: Box + caption width in HWPUNIT.
+            height: Box height in HWPUNIT.
+        """
+
+        run = self._create_run_for_object(char_pr_id_ref=char_pr_id_ref)
+        check = _append_child(run, f"{_HP}checkBtn", {
+            "caption": _sanitize_text(caption),
+            "value": "CHECKED" if checked else "UNCHECKED",
+            "radioGroupName": "",
+            "triState": "0",
+            "backStyle": "OPAQUE",
+            "name": _sanitize_text(name) if name else f"CheckBox{_object_id()}",
+            "foreColor": "#000000",
+            "backColor": "#FFFFFF",
+            "groupName": "",
+            "tabStop": "1",
+            "editable": "1",
+            "tabOrder": "0",
+            "enabled": "1",
+            "borderTypeIDRef": "0",
+            "drawFrame": "1",
+            "printable": "1",
+            "command": "",
+        })
+        _append_child(check, f"{_HP}formCharPr", {
+            "charPrIDRef": str(char_pr_id_ref if char_pr_id_ref is not None else 0),
+            "followContext": "0",
+            "autoSz": "0",
+            "wordWrap": "0",
+        })
+        _append_child(check, f"{_HP}sz", {
+            "width": str(int(width)),
+            "widthRelTo": "ABSOLUTE",
+            "height": str(int(height)),
+            "heightRelTo": "ABSOLUTE",
+            "protect": "0",
+        })
+        _append_child(check, f"{_HP}pos", {
+            "treatAsChar": "1",
+            "affectLSpacing": "0",
+            "flowWithText": "1",
+            "allowOverlap": "1",
+            "holdAnchorAndSO": "0",
+            "vertRelTo": "PARA",
+            "horzRelTo": "COLUMN",
+            "vertAlign": "TOP",
+            "horzAlign": "LEFT",
+            "vertOffset": "0",
+            "horzOffset": "0",
+        })
+        _append_child(check, f"{_HP}outMargin", {
+            "left": "0", "right": "0", "top": "0", "bottom": "0",
+        })
+        _append_child(run, f"{_HP}t", {})
+
+        self.section.mark_dirty()
+        return HwpxOxmlInlineObject(check, self)
+
     @property
     def bookmarks(self) -> list[str]:
         """Return the names of all bookmarks in this paragraph."""

{python_hwpx-5.6.0 → python_hwpx-5.7.0/src/python_hwpx.egg-info}/PKG-INFO

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

{python_hwpx-5.6.0 → python_hwpx-5.7.0}/src/python_hwpx.egg-info/SOURCES.txt

@@ -133,6 +133,7 @@ tests/test_byte_patch_identity.py
 tests/test_capabilities_surface.py
 tests/test_cell_line_spacing.py
 tests/test_chart_authoring.py
+tests/test_check_box_authoring.py
 tests/test_comment_node_robustness.py
 tests/test_contract_docs_sync.py
 tests/test_corpus_read_fidelity.py

python_hwpx-5.7.0/tests/test_check_box_authoring.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+"""체크박스 양식개체 저작 계약 테스트 (specs/060 P0 실측 계약).
+
+실한컴 실측으로 확정된 불변식을 고정한다:
+- ``value`` 어휘는 ``CHECKED``/``UNCHECKED``(각각 ☑/□로 렌더)
+- **``<hp:formCharPr>``는 필수 자식** — 없으면 한컴이 문서를 거부한다
+  (단일 변인 프로브로 확정). 구조 검증(open-safety/ID 무결성)은 이 결함을
+  잡지 못하므로 방출 형상 자체를 테스트로 고정한다.
+- ``<hp:checkBtn>``은 ``<hp:ctrl>`` 래핑 없이 run 직속 자식(누름틀과 다름)
+"""
+
+from __future__ import annotations
+
+import zipfile
+
+import pytest
+
+from hwpx.document import HwpxDocument
+
+HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+
+
+def _section_xml(path) -> str:
+    with zipfile.ZipFile(path) as archive:
+        return "".join(
+            archive.read(name).decode("utf-8")
+            for name in sorted(archive.namelist())
+            if name.endswith("section0.xml")
+        )
+
+
+def test_add_check_box_emits_the_measured_hancom_shape(tmp_path) -> None:
+    doc = HwpxDocument.new()
+    doc.add_check_box("동의합니다", checked=True, name="Agree")
+    path = tmp_path / "checkbox.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+
+    xml = _section_xml(path)
+    assert '<hp:checkBtn' in xml
+    assert 'value="CHECKED"' in xml
+    assert 'caption="동의합니다"' in xml
+    assert 'name="Agree"' in xml
+    # 필수 자식 3종 — formCharPr 누락은 실한컴 거부 사유다.
+    for child in ("formCharPr", "sz", "pos"):
+        assert f"<hp:{child}" in xml, f"missing mandatory child: {child}"
+    # 누름틀과 달리 ctrl 래핑을 쓰지 않는다.
+    assert "<hp:ctrl><hp:checkBtn" not in xml
+
+
+def test_check_box_children_are_inside_the_element(tmp_path) -> None:
+    doc = HwpxDocument.new()
+    doc.add_check_box("자식 위치", checked=False)
+    path = tmp_path / "children.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+
+    reopened = HwpxDocument.open(path)
+    checks = [
+        element
+        for section in reopened.sections
+        for element in section.element.iter(f"{HP}checkBtn")
+    ]
+    assert len(checks) == 1
+    names = [child.tag.split("}")[-1] for child in checks[0]]
+    assert "formCharPr" in names and "sz" in names and "pos" in names
+    reopened.close()
+
+
+def test_unchecked_is_the_default_and_round_trips(tmp_path) -> None:
+    doc = HwpxDocument.new()
+    doc.add_check_box("기본 상태")
+    path = tmp_path / "default.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+
+    assert 'value="UNCHECKED"' in _section_xml(path)
+    reopened = HwpxDocument.open(path)
+    boxes = reopened.list_check_boxes()
+    assert [b["caption"] for b in boxes] == ["기본 상태"]
+    assert boxes[0]["checked"] is False
+    reopened.close()
+
+
+def test_list_and_set_by_index_and_name(tmp_path) -> None:
+    doc = HwpxDocument.new()
+    doc.add_check_box("첫째", name="First")
+    doc.add_check_box("둘째", checked=True, name="Second")
+
+    listed = doc.list_check_boxes()
+    assert [(b["index"], b["name"], b["checked"]) for b in listed] == [
+        (0, "First", False),
+        (1, "Second", True),
+    ]
+
+    assert doc.set_check_box(True, index=0)["checked"] is True
+    assert doc.set_check_box(False, name="Second")["value"] == "UNCHECKED"
+    assert [b["checked"] for b in doc.list_check_boxes()] == [True, False]
+
+    path = tmp_path / "toggled.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+    reopened = HwpxDocument.open(path)
+    assert [b["checked"] for b in reopened.list_check_boxes()] == [True, False]
+    reopened.close()
+
+
+def test_selector_and_caption_refusals_are_typed() -> None:
+    doc = HwpxDocument.new()
+    doc.add_check_box("하나", name="Dup")
+    doc.add_check_box("둘", name="Dup")
+
+    with pytest.raises(ValueError, match="exactly one of index or name"):
+        doc.set_check_box(True)
+    with pytest.raises(ValueError, match="exactly one of index or name"):
+        doc.set_check_box(True, index=0, name="Dup")
+    with pytest.raises(ValueError, match="ambiguous"):
+        doc.set_check_box(True, name="Dup")
+    with pytest.raises(ValueError, match="not found"):
+        doc.set_check_box(True, name="없는이름")
+    with pytest.raises(ValueError, match="index not found"):
+        doc.set_check_box(True, index=99)
+    with pytest.raises(ValueError, match="non-empty"):
+        doc.add_check_box("   ")
+    doc.close()
+
+
+def test_check_box_inside_a_table_cell(tmp_path) -> None:
+    doc = HwpxDocument.new()
+    table = doc.add_table(2, 2)
+    cell_paragraph = table.rows[0].cells[1].paragraphs[0]
+    cell_paragraph.add_check_box("셀 안", checked=True)
+
+    path = tmp_path / "cell.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+
+    reopened = HwpxDocument.open(path)
+    boxes = reopened.list_check_boxes()
+    assert [(b["caption"], b["checked"]) for b in boxes] == [("셀 안", True)]
+    reopened.close()
+
+
+def test_authored_document_passes_open_safety(tmp_path) -> None:
+    from hwpx.tools.package_validator import validate_editor_open_safety
+
+    doc = HwpxDocument.new()
+    doc.add_check_box("열림 안전", checked=True)
+    path = tmp_path / "safe.hwpx"
+    doc.save_to_path(path)
+    doc.close()
+
+    report = validate_editor_open_safety(path).to_dict()
+    assert report["ok"] is True