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

{python_hwpx-5.6.0 → python_hwpx-5.8.0}/NOTICE

@@ -58,6 +58,14 @@ neolord0/hwpxlib (https://github.com/neolord0/hwpxlib), licensed Apache-2.0.
 Only sample DATA files are vendored; no hwpxlib source code or structure is
 copied (clean-room). Pinned ref is recorded in manifest.json.
 
+## Hancom file-format specification attribution
+
+Parts of this project were developed with reference to the publicly
+released Hancom file-format documentation (HWP 5.0 / HWPML) and the
+public OWPML schema. As required by that documentation:
+
+“본 제품은 한글과컴퓨터의 ᄒᆞᆫ글 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.”
+
 ────────────────────────────────────────
 DISCLAIMER — HWPX Format
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.6.0
+Version: 5.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -158,10 +158,15 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 실측으로 말합니다
 
-만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
-그대로 공개합니다:
+만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
+스택과 날짜를 병기합니다:
 
-- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
+  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
+  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
+  (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
 - **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
 - 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)

{python_hwpx-5.6.0 → python_hwpx-5.8.0}/README.md

@@ -107,10 +107,15 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 실측으로 말합니다
 
-만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
-그대로 공개합니다:
-
-- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
+스택과 날짜를 병기합니다:
+
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
+  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
+  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
+  (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
 - **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
 - 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)

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

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

{python_hwpx-5.6.0 → python_hwpx-5.8.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.8.0}/src/hwpx/capabilities.py

@@ -8,8 +8,17 @@
 1. 여기 등재된 진입점은 전부 실제로 import 가능해야 한다.
 2. ``editPlanOps``는 :data:`hwpx.plan.PLAN_OPS`·실행 디스패치·edit-plan JSON
    Schema enum과 일치해야 한다.
-3. :data:`_CAPABILITY_AREAS`의 매트릭스 행 제목은 ``docs/support-matrix.md``
-   표의 행 제목과 집합 일치해야 한다.
+3. :data:`_CAPABILITY_AREAS`의 ``authoring_methods``는 라이브
+   ``HwpxDocument``의 ``add_*`` 전수와 정확히 일치해야 한다 — **레지스트리를
+   코드에 대조하는 방향**이다.
+4. 매트릭스 행 제목은 ``docs/support-matrix.md`` 표의 행 제목과 집합 일치해야
+   한다.
+
+3번이 있는 이유: 4번만으로는 부족하다. 문서 둘이 서로 맞는다는 사실은 코드에
+대해 아무것도 말해주지 않으므로, **양쪽에 다 없는** 능력은 통과한다. 실제로
+``add_check_box``가 5.7.0에서 실한컴 수용 게이트까지 통과해 출하됐는데
+레지스트리에도 매트릭스에도 없었다 — 이 부류의 드리프트를 "구조적으로
+막는다"고 선언한 바로 다음 릴리스에서다. 코드에 대조해야 잡힌다.
 
 **core는 환경 변수를 읽지 않는다** — 렌더 오라클 가용성은 여기 없다(자기서술은
 ``renderOracle.bundled="none"``으로 그 사실 자체를 말한다). 오라클 탐지·실행은
@@ -39,21 +48,39 @@ _EXTRA_MODULES: dict[str, tuple[str, ...]] = {
 #: 능력 영역 레지스트리. ``matrix_row``는 ``docs/support-matrix.md`` 표 1열
 #: 제목과 **정확히** 일치해야 한다(가드 테스트가 집합 대조). ``entry_points``는
 #: ``"모듈:이름"`` — 전부 import 가능해야 한다(가드 테스트가 해석).
+#: Every ``HwpxDocument.add_*`` method must be claimed by exactly one area.
+#:
+#: ``entry_points`` names modules, which is too coarse to notice a new
+#: authoring method: ten areas all point at ``hwpx.document:HwpxDocument``. So
+#: ``authoring_methods`` names the methods, and the guard in
+#: ``tests/test_capabilities_surface.py`` compares this registry against the
+#: live class.
+#:
+#: Why the guard runs in that direction: the previous guard compared the
+#: registry's row titles against the row titles in ``docs/support-matrix.md``.
+#: Two documents agreeing with each other says nothing about the code, so a
+#: capability missing from *both* passed. ``add_check_box`` shipped in 5.7.0
+#: with a real-Hancom acceptance gate and appeared in neither, one release
+#: after the changelog announced that this class of drift was now structurally
+#: blocked. Comparing against the class is the direction that can catch it.
 _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
     {
         "area": "paragraph-table-authoring",
         "matrix_row": "문단·표 저작/편집",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_paragraph", "add_section"),
     },
     {
         "area": "table-structure",
         "matrix_row": "표 구조 변경(행·열·표 삭제/삽입, 열 오토핏)",
         "entry_points": ("hwpx.table_patch:apply_table_ops",),
+        "authoring_methods": (),
     },
     {
         "area": "table-create",
         "matrix_row": "표 생성(병합·중첩 포함)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_table",),
     },
     {
         "area": "form-fill",
@@ -63,6 +90,7 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
             "hwpx.table_patch:fill_cells",
             "hwpx.body_patch:apply_body_ops",
         ),
+        "authoring_methods": (),
     },
     {
         "area": "edit-plan",
@@ -71,71 +99,91 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
             "hwpx.plan:apply_edit_plan",
             "hwpx.plan:validate_edit_plan",
         ),
+        "authoring_methods": (),
     },
     {
         "area": "shape-authoring",
         "matrix_row": "도형 저작(선·사각형·타원)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_line", "add_rectangle", "add_ellipse"),
     },
     {
         "area": "shape-escape-hatch",
         "matrix_row": "저수준 도형·컨트롤 탈출구",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_shape", "add_control"),
     },
     {
         "area": "curve-objects",
         "matrix_row": "arc·polygon·curve·connectLine",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "picture",
         "matrix_row": "그림 삽입/치환",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_picture", "add_image"),
     },
     {
         "area": "chart",
         "matrix_row": "차트",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_chart",),
     },
     {
         "area": "equation",
         "matrix_row": "수식",
         "entry_points": ("hwpx.equation.authoring:latex_to_eqedit",),
+        "authoring_methods": ("add_equation",),
     },
     {
         "area": "redline",
         "matrix_row": "변경추적(redline)",
         "entry_points": ("hwpx.tools.redline:verify_redline",),
+        "authoring_methods": ("add_track_change", "add_tracked_insert", "add_tracked_delete", "add_tracked_replace"),
     },
     {
         "area": "memo",
         "matrix_row": "메모(코멘트)",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_memo", "add_memo_with_anchor"),
     },
     {
         "area": "footnote-endnote",
         "matrix_row": "각주/미주",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_footnote", "add_endnote"),
     },
     {
         "area": "toc-crossref",
         "matrix_row": "네이티브 목차(TOC)/상호참조",
         "entry_points": ("hwpx.tools.toc_author:add_native_toc",),
+        "authoring_methods": ("add_bookmark", "add_hyperlink"),
     },
     {
         "area": "encrypted-hwpx",
         "matrix_row": "암호화 HWPX",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "hwp5-binary",
         "matrix_row": "HWP 5.x 바이너리",
         "entry_points": (),
+        "authoring_methods": (),
     },
     {
         "area": "form-field-create",
         "matrix_row": "누름틀(form field) 생성",
         "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_form_field",),
+    },
+    {
+        "area": "check-box",
+        "matrix_row": "체크박스 양식개체",
+        "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": ("add_check_box",),
     },
 )
 
@@ -458,9 +506,110 @@ def contract_json_schema(name: str) -> dict[str, Any]:
     return builder()
 
 
+def verify_self_description() -> list[str]:
+    """설치된 휠에서 자기서술이 실표면과 맞는지 직접 검사한다.
+
+    왜 라이브러리 안에 있나: 5.6.0의 CHANGELOG는 이 부류의 드리프트를 "이제
+    구조적으로 막습니다"라고 **선언**했고, 바로 다음 릴리스에서 같은 드리프트를
+    냈다. 두 번째 선언은 신뢰받을 이유가 없다. 그래서 선언 대신 **누구나 자기
+    설치본에서 돌려 볼 수 있는 검사**를 동봉한다 —
+    ``python -m hwpx.capabilities --verify``.
+
+    저장소의 테스트가 아니라 설치된 패키지에서 도는 것이 요점이다. 사용자가
+    받은 휠이 실제로 무엇을 할 수 있는지 그 휠 자신에게 물어볼 수 있다.
+
+    Returns:
+        위반 목록. 빈 리스트면 자기서술이 실표면과 일치한다.
+    """
+
+    from .document import HwpxDocument
+
+    problems: list[str] = []
+
+    live = {name for name in dir(HwpxDocument) if name.startswith("add_")}
+    registered: dict[str, str] = {}
+    for row in _CAPABILITY_AREAS:
+        for method in row.get("authoring_methods", ()):
+            if method in registered:
+                problems.append(
+                    f"authoring method {method!r} is claimed by both "
+                    f"{registered[method]!r} and {row['area']!r}"
+                )
+            registered[method] = row["area"]
+
+    for method in sorted(live - set(registered)):
+        problems.append(
+            f"HwpxDocument.{method} exists but no capability area claims it; "
+            "the self-description understates what this install can do"
+        )
+    for method in sorted(set(registered) - live):
+        problems.append(
+            f"capability registry claims HwpxDocument.{method}, which this "
+            "install does not have; the self-description overstates it"
+        )
+
+    matrix_rows = {row["matrix_row"] for row in _CAPABILITY_AREAS}
+    try:
+        text = contract_document("support-matrix")
+    except HwpxError as exc:  # pragma: no cover - only when the doc is absent
+        problems.append(f"bundled support matrix is unreadable: {exc}")
+    else:
+        documented = {
+            line.split("|")[1].strip()
+            for line in text.splitlines()
+            if line.startswith("|")
+        }
+        for row in sorted(matrix_rows - documented):
+            problems.append(f"capability area {row!r} has no support-matrix row")
+
+    return problems
+
+
+def _verify_main(argv: list[str] | None = None) -> int:
+    import argparse
+    import json as _json
+    import sys
+
+    parser = argparse.ArgumentParser(
+        prog="python -m hwpx.capabilities",
+        description="Report or verify this install's machine-readable self-description.",
+    )
+    parser.add_argument(
+        "--verify",
+        action="store_true",
+        help="check the self-description against the installed surface",
+    )
+    args = parser.parse_args(argv)
+
+    if not args.verify:
+        print(_json.dumps(describe_capabilities(), ensure_ascii=False, indent=2))
+        return 0
+
+    problems = verify_self_description()
+    for problem in problems:
+        print(f"self-description error: {problem}", file=sys.stderr)
+    if problems:
+        print(
+            f"{len(problems)} self-description problem(s) found in "
+            f"python-hwpx {_package_version()}",
+            file=sys.stderr,
+        )
+        return 1
+    print(
+        f"python-hwpx {_package_version()}: self-description matches the "
+        f"installed surface ({len(_CAPABILITY_AREAS)} capability areas)"
+    )
+    return 0
+
+
 __all__ = [
     "CAPABILITIES_SCHEMA",
     "describe_capabilities",
     "contract_document",
     "contract_json_schema",
+    "verify_self_description",
 ]
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(_verify_main())

{python_hwpx-5.6.0 → python_hwpx-5.8.0}/src/hwpx/data/contract_docs/support-matrix.md

@@ -23,14 +23,14 @@
 |---|---|---|
 | 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | corpus-metrics「오픈 수용률」476/476, 「저작 품질 게이트」실저작 58/58, 「렌더 검증」416건 |
 | 표 구조 변경(행·열·표 삭제/삽입, 열 오토핏) | Preserve·Edit | `hwpx.table_patch`; corpus-metrics「바이트 보존」497/497(patch 경로) |
-| 표 생성(병합·중첩 포함) | Create·Render-verified | `add_table`·`merge_cells`(피복 셀 제거+cellSpan — 실한컴 병합 의미론과 동형, 3종 병합 렌더 픽셀 확인)·셀 문단 `add_table`(중첩). **알려진 기본값 갭**: 셀 여백 0(한컴 510/141)·기본 폭 고정·중첩 기본 폭이 부모 셀 초과 시 렌더 소실 가능(폭 명시 권장)·선 종류는 raw 전용 — 수리 예정 |
+| 표 생성(병합·중첩 포함) | Create·Render-verified | `add_table`·`merge_cells`(피복 셀 제거+cellSpan — 실한컴 병합 의미론과 동형, 3종 병합 렌더 픽셀 확인)·셀 문단 `add_table`(중첩). 기본값은 5.4.0에서 실한컴에 맞췄다: 셀 안여백 510/510/141/141, 기본 표 폭은 본문 폭, 중첩 표는 부모 셀 사용 폭. **남은 갭**: 선 종류는 raw 전용 |
 | 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch`; corpus-metrics「바이트 보존」497/497. wild 공개 양식의 서식 충실은 2차 실측 후 **산출분 pass 82.1%(23/28)·산출+fail 7.6%(5/66)** — 불가능 타깃은 typed 거부 35건(전수 감별 과잉거부 0). 잔존은 페이지 리플 5건(4건 typed 경고 동반·완전 무음 1건, 「구조결함 2차 실측」절), 표 shape 부류는 측정 인공물로 판명·판정기 교정 |
 | 편집 계획 실행(edit plan) | Preserve·Edit | `hwpx.plan.apply_edit_plan`(experimental, 5.6.0+): 바이트-스플라이스 op 7종을 계획 1파일로 합성 — 정적 선검증→전 체인 인메모리 실행→최종 open-safety 검증→단 1회 원자 쓰기. 중간 실패 시 output·source 바이트 불변(테스트가 바이트 비교로 증명), step별+원본→최종 `hwpx.mutation-report/v1` 실측 사영 |
 | 도형 저작(선·사각형·타원) | Parse·Preserve·Edit·Create·Render-verified | 전용 `add_line`·`add_rectangle`·`add_ellipse`. 5.0.0에서 기하 네임스페이스(`hc:`)·선 bounding box·`resize()`의 기하 반영을 수정한 뒤 실한컴 12.30.0(build 6446)에서 **개봉 7/7**(선 수평·대각·수직, 사각형, 타원, resize 후 혼합, 그림). 렌더로 사각형 144×72pt+`#CCE5FF`, 타원 100×60pt+`#FFD9CC`, 대각선이 요청 박스를 실제 span, `resize(14400,7200)` 후 새 크기·DASH 반영까지 확인 |
 | 저수준 도형·컨트롤 탈출구 | Edit | `add_shape`·`add_control`은 건네받은 요소와 속성만 쓰고 OWPML 필수 하위 요소(`offset`·`orgSz`·`curSz`·`sz`·`pos`·유형별 기하)는 만들지 않는다. 그대로 저장한 문서는 실한컴 12.30.0이 **거부**한다(음성 대조로 확인). 신호는 생성 시점의 `UserWarning` **하나뿐**이다 — 저장을 막지 않고 `validate_package`·`validate_editor_open_safety`도 통과시킨다(실측 `ok=True`). 도형은 위의 전용 헬퍼를 쓸 것(전용 헬퍼는 경고하지 않는다) |
 | arc·polygon·curve·connectLine | Parse·Unsupported-but-preserved | 열거·읽기는 되지만 저작 API 없음. 기존 개체는 patch 저장에서 바이트 동일 왕복 |
 | 그림 삽입/치환 | Edit·Create | `add_picture`·`add_image`·`replace_picture`. 단순 그림 개체 자동 생성은 지원하며 실한컴 개봉을 확인했다(실한컴 코퍼스와 자식 요소 단위 대조). 그룹·효과 등 복잡 개체 생성은 미지원 |
-| 차트 | Unsupported-but-preserved | 차트 생성 API 없음(kordoc 흡수 갭). 기존 차트 part는 patch 저장 시 바이트 보존(497/497) |
+| 차트 | Create(experimental)·Preserve | `add_chart`(5.3.0+): 데이터·계열·축 레이블에서 차트 개체를 생성한다. 기존 차트 part는 patch 저장 시 바이트 보존(497/497). 생성 어휘 밖의 차트 종류·서식은 미지원이며 기존 개체 보존으로만 다룬다 |
 | 수식 | Parse·Create(experimental)·Render-verified | `add_equation`(EqEdit script 삽입, 5.2.0+)과 `hwpx.equation.latex_to_eqedit`(렌더 검증 토큰셋만 변환, 밖은 `UnsupportedLatexError`로 typed 거부). 저작 어휘 전 토큰을 실한컴 렌더 오라클 픽셀 실측(60수식 배터리)으로 확정했고, 기존 수식 개체는 파싱·patch 보존됨(미리보기 MathML 렌더는 뷰어/플러그인 계층) |
 | 변경추적(redline) | Edit·Create | `add_tracked_insert`·`add_tracked_delete`·`add_tracked_replace`; 실 Windows 한컴 COM `IsTrackChange=1`·검토 리본 수락/거부 스파이크. **렌더 주의**: 한컴이 변경추적 문서의 PDF export 자체를 거부 → corpus-metrics「렌더 검증」에서 `render_unavailable`로 정직 집계(결함 아님, 한컴 제약) |
 | 메모(코멘트) | Edit·Create·Render-verified | `add_memo`·`add_memo_with_anchor`; subList 코멘트 텍스트 + `MemoShapeIDRef` 버그 수정을 실 Windows 한컴에서 검증(CHANGELOG) |
@@ -39,6 +39,7 @@
 | 암호화 HWPX | Unsupported-and-rejected | 복호화 API 없음. 암호화된 content part는 파싱 단계에서 예외(`XMLSyntaxError`)로 거부 — 무음으로 잘못된 문서를 만들지 않음(fail-closed) |
 | HWP 5.x 바이너리 | Unsupported-and-rejected | HWP v5는 ZIP이 아니므로 열기 시 `BadZipFile` 예외. OLE2/CFBF 시그니처를 확인하면 예외 메시지가 HWPX 변환을 안내한다(예외 타입은 그대로) |
 | 누름틀(form field) 생성 | Parse·Edit·Create(experimental) | `list_form_fields`·`fill_form_field`로 조회·서식 보존 채움에 더해, `add_form_field`(5.1.0+)가 실한컴 CLICKHERE 계약 그대로 신규 누름틀을 생성한다(표 셀 배치 포함). 만든 필드는 기존 list/fill과 실제 한컴이 특수분기 없이 소비 |
+| 체크박스 양식개체 | Create·Render-verified | `add_check_box`·`list_check_boxes`·`set_check_box`(5.7.0+). 실한컴 실측 계약: `value` CHECKED=☑ / UNCHECKED=□, `<hp:formCharPr>`는 **필수 자식**(없으면 한컴이 문서를 거부하는데 우리 open-safety·ID 무결성은 통과한다 — 실한컴이 유일한 판정자다). 라디오(`hp:radioBtn`)·명령단추(`hp:btn`)는 읽기·보존만 하고 저작 API 없음 |
 
 ## 상태 판정 근거 요약
 

{python_hwpx-5.6.0 → python_hwpx-5.8.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.8.0}/src/hwpx/layout/report.py

@@ -104,10 +104,19 @@ class LayoutLintReport:
 
         from hwpx.quality.report import LayoutReport
 
+        warnings = [str(f) for f in self.warnings]
+        errors = [str(f) for f in self.errors]
+        if errors:
+            status = "failed"
+        elif warnings:
+            status = "warned"
+        else:
+            status = "passed"
         return LayoutReport(
             ok=self.ok,
-            warnings=[str(f) for f in self.warnings],
-            errors=[str(f) for f in self.errors],
+            warnings=warnings,
+            errors=errors,
+            status=status,
         )
 
     def to_dict(self) -> dict[str, Any]: