python-hwpx 5.6.0__py3-none-any.whl → 5.7.0__py3-none-any.whl

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]],

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,

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.dist-info → python_hwpx-5.7.0.dist-info}/METADATA

@@ -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.dist-info → python_hwpx-5.7.0.dist-info}/RECORD

@@ -1,7 +1,7 @@
 hwpx/__init__.py,sha256=DqoPNdD-4-oP4b_56P5ADABnyRGcDZiHch__S-urI4s,16642
 hwpx/body_patch.py,sha256=XfwrTMThS9vPLA62PDnEleCGuvYv61URxelbD_LHe8w,25730
 hwpx/capabilities.py,sha256=NZIuzerbKhdS6A4Ls9bpIrLOMQWoJ6JcICD4HrosJxQ,16597
-hwpx/document.py,sha256=XV8T-ucd0F-Uup6XBUe_ZLliSNuImq7MgGhefIwMQD0,67298
+hwpx/document.py,sha256=ylIo6R3k67aRHgPzVDtQrUQF_gt-D2FHpQ3pNPckm9c,69441
 hwpx/errors.py,sha256=l3QK2Izwkpm25ar7QnNQvyg0yosoLfQt7kW5wn5MCG0,3033
 hwpx/experimental.py,sha256=Jvc7WAi3eMFRKYubqwtIWi9oU0OjuqNOfottWkaP2RQ,2113
 hwpx/mutation_report.py,sha256=6hurhDdgGiONeLIeWZJT8lwLtWJZ1VHp1l6G0zy0mQo,19409
@@ -12,7 +12,7 @@ hwpx/table_patch.py,sha256=nl7UT-Qf5-KV25Wdxm4ve9ZxX6FfijibymPXZcJJIjQ,83729
 hwpx/templates.py,sha256=28bYqeJVeDb1Cq8G9NZG9Mhnu4K2GamAKC4QhxvUZyA,1187
 hwpx/_document/__init__.py,sha256=REiNqMbuk_TS4NVC27FIo1rUt3Z8nhJrTBGOgNtxBRg,90
 hwpx/_document/_units.py,sha256=qyC8YtnvV2VlSGltJntDaIMF_sHy_XJZCwwe-g080TQ,386
-hwpx/_document/fields.py,sha256=6VB7FV69cWcHLONj_Bn_DUGH5k9IMn94SRhRCia6wvI,22935
+hwpx/_document/fields.py,sha256=xOpTKXedTlpSg82G2_zPVQ0I6N6d6PQSAyQvZMtHF5A,26935
 hwpx/_document/layout.py,sha256=_fNHVqI2zFUn6L1-JsdyO8Z4UShmIi9G29Y5YJtQtKw,23553
 hwpx/_document/media.py,sha256=kamsFJZ4K9aoKhjyztMHC64MVFR_ZQ50rDVgouZqxFA,11592
 hwpx/_document/memos.py,sha256=_tscEhNfPe9-iAkcEtJGjwHTN42_lx4stFoPrgJxk3o,7481
@@ -61,7 +61,7 @@ hwpx/oxml/memo.py,sha256=jTtZIrR7LwWn_vvFN6Fr9yX2eSJfMPh8WnNW1DhD2Rs,10283
 hwpx/oxml/namespaces.py,sha256=c7JfdOdJbzrhyHvjbxoeeeloRE3xPuoB7v3YI8SmKDk,6524
 hwpx/oxml/numbering.py,sha256=9a0ARGW1DkKsTF7mEEXM4FA5loQmzIBuqE4APA8UFIQ,669
 hwpx/oxml/objects.py,sha256=8ErDXWvkjLm3FTsx0Z_IovUXbiv2uc-j0B5Y2-OtihA,20864
-hwpx/oxml/paragraph.py,sha256=btJlX6WScB9gjKRu2uAs1qAdEQYar2BuKdSwNfdRm9U,53408
+hwpx/oxml/paragraph.py,sha256=q7uxcMMTSslRR3WpaEK5waFV8boGOMZA2Hx2uU87_cU,56601
 hwpx/oxml/parser.py,sha256=pIfyNdW3WdFkCcE8JFY7hn1fobRbMngzfhVZICvWeVs,2937
 hwpx/oxml/run.py,sha256=F939J1W6zQjr-JQ1Z8-nKh2s7NQ_0Okov4QJAEyw_5M,15503
 hwpx/oxml/schema.py,sha256=ElR3_IIhhPPZEqJtNKMNCHA-VFVLdhL454W_4spuvlc,1284
@@ -114,10 +114,10 @@ hwpx/tools/toc_fidelity.py,sha256=rvoKH8QJ65WNVrxS0d-i2AtODvBy-4O8NRudfQ244v4,19
 hwpx/tools/validator.py,sha256=U856izL9NcJZOiKDYoCpwOSaFNQ2Un8Jn4pzL20A96Q,7100
 hwpx/tools/_schemas/header.xsd,sha256=mJXuFMuHGT1JnFFaluUpYUglwjMCNlfbFCRVM26eHXE,664
 hwpx/tools/_schemas/section.xsd,sha256=MgvavVHG05RDfUnVPxVU10H4FQOja5ON04_m9Uk_m7E,522
-python_hwpx-5.6.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-5.6.0.dist-info/licenses/NOTICE,sha256=auRgKYGdrOgWrj4kZfAuXQnqgDnx5myI9TI17IztIzQ,3466
-python_hwpx-5.6.0.dist-info/METADATA,sha256=t4MwjQ7lPJtRM5DNDihCB4NO7PVFb820vQBllRPte18,13162
-python_hwpx-5.6.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-python_hwpx-5.6.0.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
-python_hwpx-5.6.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-5.6.0.dist-info/RECORD,,
+python_hwpx-5.7.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-5.7.0.dist-info/licenses/NOTICE,sha256=auRgKYGdrOgWrj4kZfAuXQnqgDnx5myI9TI17IztIzQ,3466
+python_hwpx-5.7.0.dist-info/METADATA,sha256=L4W3jUCNCTx15HU552LRUGTpIK5CuIFJegAlB6MEGCg,13162
+python_hwpx-5.7.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+python_hwpx-5.7.0.dist-info/entry_points.txt,sha256=JUKRxbly9UaeHV7YzOea23y8IiqSTcrhUlooP3fS_Zc,405
+python_hwpx-5.7.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-5.7.0.dist-info/RECORD,,