python-hwpx 6.3.0__tar.gz → 6.4.0__tar.gz

{python_hwpx-6.3.0/src/python_hwpx.egg-info → python_hwpx-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 6.3.0
+Version: 6.4.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -68,24 +68,26 @@ Dynamic: license-file
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
-곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
-형태로 만들어집니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
 </p>
 <p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
+**ChatGPT에서 그대로 따라 하기** — ChatGPT 채팅의 파이썬 환경은 PyPI 접근이
+막혀 있으므로 [최신 Release](https://github.com/airmang/python-hwpx/releases/latest)에서
+`python_hwpx-*.whl` 하나를 받아 문서와 **함께 올리고** 이렇게 부탁합니다:
 
 ```text
+첨부한 python_hwpx-*.whl 을 pip 로 설치한 다음(pip install /mnt/data/python_hwpx-*.whl),
 이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
-(pip install python-hwpx 로 설치하면 돼)
 양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
 ```
 
 설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+자세한 절차와 에이전트용 지시문은 [AI 채팅 환경에서 쓰기](docs/ai-assistants.md)에,
 AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
 
 | | 저장소 | 역할 |
@@ -136,25 +138,32 @@ doc.save_to_path("계획.hwpx")
 
 ```python
 doc = HwpxDocument.open("신청서.hwpx")
-result = doc.fill_by_path({
+values = {
     "성명 > right": "홍길동",
     "소속 > right": "플랫폼팀",
-})
-doc.save_to_path("신청서-작성완료.hwpx")
+}
+result = doc.tables.fill_by_path(values)
+if result["failed_count"] or result["applied_count"] != len(values):
+    raise ValueError(result["failed"])
+report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback="error", return_report=True)
 ```
 
-라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+중복·누락 라벨은 실패로 확인하고 저장을 중단합니다. patch는 미수정 ZIP 파트의
+바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
+필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
 ### 저장에는 영수증이 따라옵니다
 
 ```python
 report = doc.save_to_path("결과.hwpx", return_report=True)
-print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.actual_mode)        # "patch" 또는 "rebuild" — 실제 저장 등급
 print(report.preservation.untouched_part_payloads.to_dict())
                                  # {"verified": 17, "changed": 0}
 ```
 
-요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
+기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
+검증 완료를 뜻하지 않습니다.
 전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
 
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
@@ -190,17 +199,20 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 | 환경 | 무엇을 하면 되나 |
 |---|---|
-| 일반 ChatGPT 대화 | `.hwpx`를 올리고 `pip install python-hwpx` 후 파이썬으로 편집해 되받기 |
+| 일반 ChatGPT 대화 | `.hwpx`와 [Release wheel](https://github.com/airmang/python-hwpx/releases/latest)을 함께 올리고 오프라인 설치 후 편집해 되받기 — [안내](docs/ai-assistants.md) |
 | 로컬·서버 파이썬 | `pip install python-hwpx` — 스크립트·배치·CI |
 | 파이썬 자동화 (MCP 없이) | `pip install python-hwpx-automation` — 저작·양식 채움·검증 워크플로를 그냥 파이썬으로 |
 | ChatGPT MCP 앱 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)의 MCP adapter를 커넥터로 등록 |
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
-편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
-플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
-오프라인 설치로 같은 여정이 됩니다.
+ChatGPT 채팅의 파이썬 환경은 현재 PyPI 접근이 막혀 있습니다. 매 릴리스의
+GitHub Release에 첨부되는 `py3-none-any` wheel을 문서와 함께 올리면 오프라인
+설치로 같은 여정이 됩니다. wheel의 유일한 의존성은 `lxml`이며, 실행 환경에
+없으면 lxml wheel도 함께 올립니다. 같은 wheel을 GitHub Actions artifact
+`python-hwpx-wheel`로도 유지하므로, artifact를 가져올 수 있는 에이전트는 첨부
+없이 설치할 수 있습니다(실험 경로, [안내](docs/ai-assistants.md)). 파이썬 실행
+가능 여부와 업로드 경로는 플랜·설정에 따라 다릅니다.
 
 ## 비교
 

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/README.md

@@ -17,24 +17,26 @@
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
-곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
-형태로 만들어집니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
 </p>
 <p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
+**ChatGPT에서 그대로 따라 하기** — ChatGPT 채팅의 파이썬 환경은 PyPI 접근이
+막혀 있으므로 [최신 Release](https://github.com/airmang/python-hwpx/releases/latest)에서
+`python_hwpx-*.whl` 하나를 받아 문서와 **함께 올리고** 이렇게 부탁합니다:
 
 ```text
+첨부한 python_hwpx-*.whl 을 pip 로 설치한 다음(pip install /mnt/data/python_hwpx-*.whl),
 이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
-(pip install python-hwpx 로 설치하면 돼)
 양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
 ```
 
 설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+자세한 절차와 에이전트용 지시문은 [AI 채팅 환경에서 쓰기](docs/ai-assistants.md)에,
 AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
 
 | | 저장소 | 역할 |
@@ -85,25 +87,32 @@ doc.save_to_path("계획.hwpx")
 
 ```python
 doc = HwpxDocument.open("신청서.hwpx")
-result = doc.fill_by_path({
+values = {
     "성명 > right": "홍길동",
     "소속 > right": "플랫폼팀",
-})
-doc.save_to_path("신청서-작성완료.hwpx")
+}
+result = doc.tables.fill_by_path(values)
+if result["failed_count"] or result["applied_count"] != len(values):
+    raise ValueError(result["failed"])
+report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback="error", return_report=True)
 ```
 
-라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+중복·누락 라벨은 실패로 확인하고 저장을 중단합니다. patch는 미수정 ZIP 파트의
+바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
+필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
 ### 저장에는 영수증이 따라옵니다
 
 ```python
 report = doc.save_to_path("결과.hwpx", return_report=True)
-print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.actual_mode)        # "patch" 또는 "rebuild" — 실제 저장 등급
 print(report.preservation.untouched_part_payloads.to_dict())
                                  # {"verified": 17, "changed": 0}
 ```
 
-요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
+기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
+검증 완료를 뜻하지 않습니다.
 전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
 
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
@@ -139,17 +148,20 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 | 환경 | 무엇을 하면 되나 |
 |---|---|
-| 일반 ChatGPT 대화 | `.hwpx`를 올리고 `pip install python-hwpx` 후 파이썬으로 편집해 되받기 |
+| 일반 ChatGPT 대화 | `.hwpx`와 [Release wheel](https://github.com/airmang/python-hwpx/releases/latest)을 함께 올리고 오프라인 설치 후 편집해 되받기 — [안내](docs/ai-assistants.md) |
 | 로컬·서버 파이썬 | `pip install python-hwpx` — 스크립트·배치·CI |
 | 파이썬 자동화 (MCP 없이) | `pip install python-hwpx-automation` — 저작·양식 채움·검증 워크플로를 그냥 파이썬으로 |
 | ChatGPT MCP 앱 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)의 MCP adapter를 커넥터로 등록 |
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
-편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
-플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
-오프라인 설치로 같은 여정이 됩니다.
+ChatGPT 채팅의 파이썬 환경은 현재 PyPI 접근이 막혀 있습니다. 매 릴리스의
+GitHub Release에 첨부되는 `py3-none-any` wheel을 문서와 함께 올리면 오프라인
+설치로 같은 여정이 됩니다. wheel의 유일한 의존성은 `lxml`이며, 실행 환경에
+없으면 lxml wheel도 함께 올립니다. 같은 wheel을 GitHub Actions artifact
+`python-hwpx-wheel`로도 유지하므로, artifact를 가져올 수 있는 에이전트는 첨부
+없이 설치할 수 있습니다(실험 경로, [안내](docs/ai-assistants.md)). 파이썬 실행
+가능 여부와 업로드 경로는 플랜·설정에 따라 다릅니다.
 
 ## 비교
 

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "6.3.0"
+version = "6.4.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -217,6 +217,7 @@ files = [
     "src/hwpx/oxml/numbering.py",
     "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
+    "src/hwpx/opc/xml_utils.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",
@@ -383,6 +384,7 @@ include = [
     "src/hwpx/oxml/numbering.py",
     "src/hwpx/oxml/objects.py",
     "src/hwpx/opc/package.py",
+    "src/hwpx/opc/xml_utils.py",
     "src/hwpx/opc/relationships.py",
     "src/hwpx/oxml/paragraph.py",
     "src/hwpx/oxml/run.py",

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/_document/fields.py

@@ -689,20 +689,15 @@ def _insert_form_field_text_run(
     match: dict[str, Any],
     value: str,
 ) -> None:
-    paragraph = match["_paragraph"]
+    # A field may begin and end within one run. A run index is not a
+    # paragraph-child insertion point, and inserting before the end run can
+    # put the value before fieldBegin. Insert the text immediately after the
+    # actual begin control, retaining its surrounding run and character style.
     runs: list[Any] = match["_runs"]
-    begin_run_index = int(match["_begin_run_index"])
-    end_run_index = match.get("_end_run_index")
-    begin_run = runs[begin_run_index]
-    char_ref = begin_run.get("charPrIDRef") or paragraph.char_pr_id_ref or "0"
-    run = paragraph.element.makeelement(f"{_HP}run", {"charPrIDRef": str(char_ref)})
-    text_node = run.makeelement(f"{_HP}t", {})
+    begin_run = runs[int(match["_begin_run_index"])]
+    text_node = begin_run.makeelement(f"{_HP}t", {})
     text_node.text = _sanitize_field_text(value)
-    run.append(text_node)
-    if end_run_index is None:
-        paragraph.element.insert(begin_run_index + 1, run)
-    else:
-        paragraph.element.insert(int(end_run_index), run)
+    begin_run.insert(int(match["_begin_child_index"]) + 1, text_node)
 
 
 def fill_form_field(

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/capabilities.py

@@ -74,7 +74,7 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
         "area": "paragraph-table-authoring",
         "namespace": None,
         "matrix_row": "문단·표 저작/편집",
-        "entry_points": ("hwpx.document:HwpxDocument",),
+        "entry_points": ("hwpx.document:HwpxDocument", "hwpx.model:Table"),
         "authoring_methods": ("add_heading", "add_paragraph", "add_section"),
     },
     {
@@ -116,7 +116,7 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
         "area": "shape-authoring",
         "namespace": "doc.shapes",
         "matrix_row": "도형 저작(선·사각형·타원)",
-        "entry_points": ("hwpx.document:HwpxDocument",),
+        "entry_points": ("hwpx.document:HwpxDocument", "hwpx.model:Shape"),
         "authoring_methods": ("add_line", "add_rectangle", "add_ellipse"),
     },
     {

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/data/contract_docs/mutation-semantics.md

@@ -14,12 +14,12 @@ stable 편집 표면의 계약을 한 곳에 모았다. 아래 표의 실패 모
 | 호출 | 반환 | 대표 실패 모드 | 다시 실행하면 |
 |---|---|---|---|
 | `add_paragraph(text)` | `HwpxOxmlParagraph` | 사실상 없음 | 문단이 하나 더 추가된다(append, 비멱등) |
-| `remove_paragraph(p)` | `None` | 섹션의 마지막 단락 삭제 시 `ValueError` | 이미 제거된 문단이면 조용히 무시된다(무해) |
+| `paragraph.remove()` | `None` | 섹션의 마지막 단락 삭제 시 `ValueError` | 이미 제거된 문단이면 조용히 무시된다(무해) |
 | `add_table(rows, cols)` | `HwpxOxmlTable` | 사실상 없음 | 표가 하나 더 추가된다(비멱등) |
 | `table.set_cell_text(r, c, text)` | `FitResult \| None` | 범위 밖 좌표는 `IndexError` (`exceed table bounds`) | 같은 값이면 결과 동일(수렴) |
-| `replace_text_in_runs(search, repl)` | `int` (치환 수) | 빈 `search`는 `ValueError` | 치환할 것이 없으면 `0` — 1회차 후 수렴 |
-| `add_memo_with_anchor(...)` | `(memo, paragraph, field_id)` 튜플 | 아래 캐비앗 참고 | 메모가 하나 더 붙는다(비멱등) |
-| `add_footnote(text, paragraph)` | `HwpxOxmlNote` | 사실상 없음 | 각주가 하나 더 붙는다(비멱등) |
+| `document.text.replace(search, repl)` | `int` (치환 수) | 빈 `search`는 `ValueError` | 치환할 것이 없으면 `0` — 1회차 후 수렴 |
+| `document.notes.add_memo(..., anchor=p)` | `Memo` (`paragraph`, `field_id` 속성) | 아래 캐비앗 참고 | 메모가 하나 더 붙는다(비멱등) |
+| `document.notes.add_footnote(text, paragraph)` | `HwpxOxmlNote` | 사실상 없음 | 각주가 하나 더 붙는다(비멱등) |
 
 "사실상 없음"은 정상 인자에서 실패 경로가 없다는 뜻이다 — 타입이 어긋난
 인자는 여느 파이썬 API처럼 `TypeError` 계열로 즉시 드러난다.
@@ -35,19 +35,25 @@ print(report.actual_mode)
   안전 검증을 통과한 결과만 대상 경로를 교체한다.
 - 요청한 보존 등급(`mode="patch"` 등)을 지킬 수 없으면
   `PreservationDowngradeError`로 실패하고 **아무것도 쓰지 않는다**
-  (fail-closed). 자동 다운그레이드는 없다.
+  (`mode="patch", fallback="error"`). 기본 `auto`는 달성 가능한 등급을 선택하며,
+  명시한 `fallback="rebuild"`는 강등을 허용한다.
 - `return_report=True`는 `MutationReport`를 돌려준다 — 실제 저장 모드,
   손대지 않은 파트의 바이트 보존 검증 결과까지. 스키마와 전체 규칙은
   [안전한 쓰기 계약](safe-write-contract.md).
+- `report.ok`는 요청 내용 반영을 검사하지 않는다. 요청 건수와 출력 값을 별도로
+  확인하고 `verification.visual="not_performed"`를 시각 통과로 읽지 않는다.
 - **직렬화는 결정론적이다**: 같은 문서 상태에서 `to_bytes()`를 두 번 부르면
   바이트가 동일하다(실측). diff·해시 기반 파이프라인에 안전하다.
 
 ## 알아둘 캐비앗 (정직 고지)
 
-- `add_memo_with_anchor(memo_shape_id_ref=...)`는 참조가 실재하는 메모
+- `document.notes.add_memo(memo_shape_id_ref=...)`는 참조가 실재하는 메모
   모양인지 **검증하지 않고 조용히 수용한다**. 존재하지 않는 ID를 넣으면
-  저장은 되지만 편집기 표시가 어긋날 수 있다. `document.memo_shapes`로
+  저장은 되지만 편집기 표시가 어긋날 수 있다. `document.styles.memo_shapes`로
   실재 ID를 확인하고 쓰는 것을 권장한다.
+- `document.text.replace`는 본문 문단의 개별 런 안에서 치환한다. 여러 런에
+  걸친 검색어와 중첩 셀 문단은 이 경로의 대상이 아니다. `0`을 반환하면 저장
+  성공 여부와 관계없이 요청이 반영되지 않은 것이다.
 - `add_*` 계열은 전부 append 의미론이다. "없으면 추가"가 필요하면 먼저
   {doc}`recipes-traversal`의 순회로 존재 여부를 확인하라.
 - 편집은 저장 전까지 메모리에만 있다. 저장 경로가 곧 커밋이다.

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/data/contract_docs/recipes-traversal.md

@@ -79,34 +79,41 @@ print("셀 수:", len(cells))
 
 ## 런 단위로 서식과 함께 순회하기
 
-굵기·색 같은 서식은 런(run)에 붙는다. 문서 전체 런을 순회하거나, 특정
+굵기·색 같은 서식은 런(run)에 붙는다. 본문 문단의 런을 순회하거나, 특정
 서식의 런만 골라낼 수 있다.
 
 ```python
 from hwpx import HwpxDocument
 
 document = HwpxDocument.open("input.hwpx")
-for run in document.iter_runs():
+for run in document.text.runs():
     print(repr(run.text), "charPr:", run.char_pr_id_ref)
 
-red_runs = document.find_runs_by_style(text_color="#FF0000")
+red_runs = document.text.find_runs(text_color="#FF0000")
 print("빨간 런:", len(red_runs))
 ```
 
+## 병합 셀의 라벨 찾기
+
+라벨 기반 표 탐색에는 `document.tables.find_cell_by_label(label)`을 쓴다.
+병합 셀 하나는 라벨 한 건으로 세며, 오른쪽/아래쪽 이동은 그 병합 범위 밖의
+인접 셀로 간다. 서로 다른 셀에 같은 라벨이 있으면 여러 결과를 돌려준다.
+논리 좌표 여러 개가 같은 병합 셀을 가리키는 경우와 실제 중복 라벨은 구분한다.
+
 ## 메모와 누름틀(필드) 나열하기
 
 ```python
 from hwpx import HwpxDocument
 
 document = HwpxDocument.open("input.hwpx")
-for memo in document.memos:
+for memo in document.notes.memos:
     print("메모:", memo.id)
 
-for field in document.list_form_fields():
+for field in document.fields.all:
     print("누름틀:", field)
 ```
 
-문서에 해당 요소가 없으면 빈 리스트가 나온다 — 예외가 아니다.
+문서에 해당 요소가 없으면 빈 컬렉션이 나온다 — 예외가 아니다.
 
 ## 다음 단계
 

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/data/contract_docs/support-matrix.md

@@ -21,12 +21,12 @@
 
 | 능력 영역 | 상태 | 증거 |
 |---|---|---|
-| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | corpus-metrics「오픈 수용률」476/476, 「저작 품질 게이트」실저작 58/58, 「렌더 검증」416건. **6.5+**: `paragraph.add_run(text, expand_special_characters=True)`가 `hp:lineBreak`(줄바꿈)·`hp:nbSpace`(비분리공백)·`hp:fwSpace`(전각공백)를 저작한다 — 실코퍼스 3파일(`error__20230818__test.hwpx`/`error__20251107__test.hwpx`/`error__20250808__...hwpx`) 리버스로 셋 다 **단일 hp:t 안의 mixed content**임을 확인(`hp:tab`이 쓰는 "hp:run 형제" 형태와 다름 — 스키마는 둘 다 허용하나 실 산출물은 이 셋에 대해 전자만 씀). 같은 리버스 과정에서 텍스트 추출기(`TextExtractor`)가 이 세 원자(+`hp:hyphen`)를 `hp:t` 중첩 위치에서 못 읽던 결함도 함께 수리 — 수리 전엔 원자가 조용히 사라지며 앞뒤 텍스트가 구분자 없이 붙어 읽혔다(줄바꿈이 있었다는 사실 자체가 유실). 실한컴 렌더 검증: `docs/openrate/report-v9.json` authored-inlineatoms 스트라텀(3원자의 0공백 순서조합 15종 전량), macOS Hancom GUI 오라클 15/15 render_checked·0 render_failed(2026-08-07 측정). **6.12 트레인㊸ 갭④**: `doc.styles.apply_paragraph_format(column_break=...)`가 `hp:p`의 `columnBreak` 속성(문단 인스턴스별 강제 단 나눔)을 저작한다 — `page_break_before`가 다루는 `hh:breakSetting`(paraPr 공유 스타일)과는 다른 메커니즘이라 대상 paraPr을 새로 안 만들고 문단에 직접 적용된다. 실코퍼스 67파일 전수(14266문단) 측정: 자매 속성 `pageBreak`는 73건 실사용 확인(항상 "0"/"1" 리터럴, "true"/"false" 0건)되지만 `columnBreak`는 0건 — 그래도 같은 요소·같은 리터럴 규약을 재사용하는 것뿐이라 구조적 추측 위험은 없다. 실한컴 렌더 검증: `docs/openrate/report-v16.json` authored-column-break 스트라텀(5문단 문서에서 대상 문단 위치를 0~4로 로테이션, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-10 측정). 옛 5.x 표면(`doc.set_paragraph_format`)에는 의도적으로 안 얹었다 — 그 shim은 5.x 시그니처 그대로 얼려두는 게 계약이라(7.0 제거 예정), 신규 옵션은 `doc.styles.apply_paragraph_format`에만 산다 |
+| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | `Table.set_cell_borders`는 네 변 색/종류만 수정하며 기존 선 두께·배경·대각선과 공유 스타일을 보존한다. 전체 스타일 교체용 `set_cell_border_fill`과 구분한다. corpus-metrics「오픈 수용률」476/476, 「저작 품질 게이트」실저작 58/58, 「렌더 검증」416건. **6.5+**: `paragraph.add_run(text, expand_special_characters=True)`가 `hp:lineBreak`(줄바꿈)·`hp:nbSpace`(비분리공백)·`hp:fwSpace`(전각공백)를 저작한다 — 실코퍼스 3파일(`error__20230818__test.hwpx`/`error__20251107__test.hwpx`/`error__20250808__...hwpx`) 리버스로 셋 다 **단일 hp:t 안의 mixed content**임을 확인(`hp:tab`이 쓰는 "hp:run 형제" 형태와 다름 — 스키마는 둘 다 허용하나 실 산출물은 이 셋에 대해 전자만 씀). 같은 리버스 과정에서 텍스트 추출기(`TextExtractor`)가 이 세 원자(+`hp:hyphen`)를 `hp:t` 중첩 위치에서 못 읽던 결함도 함께 수리 — 수리 전엔 원자가 조용히 사라지며 앞뒤 텍스트가 구분자 없이 붙어 읽혔다(줄바꿈이 있었다는 사실 자체가 유실). 실한컴 렌더 검증: `docs/openrate/report-v9.json` authored-inlineatoms 스트라텀(3원자의 0공백 순서조합 15종 전량), macOS Hancom GUI 오라클 15/15 render_checked·0 render_failed(2026-08-07 측정). **6.12 트레인㊸ 갭④**: `doc.styles.apply_paragraph_format(column_break=...)`가 `hp:p`의 `columnBreak` 속성(문단 인스턴스별 강제 단 나눔)을 저작한다 — `page_break_before`가 다루는 `hh:breakSetting`(paraPr 공유 스타일)과는 다른 메커니즘이라 대상 paraPr을 새로 안 만들고 문단에 직접 적용된다. 실코퍼스 67파일 전수(14266문단) 측정: 자매 속성 `pageBreak`는 73건 실사용 확인(항상 "0"/"1" 리터럴, "true"/"false" 0건)되지만 `columnBreak`는 0건 — 그래도 같은 요소·같은 리터럴 규약을 재사용하는 것뿐이라 구조적 추측 위험은 없다. 실한컴 렌더 검증: `docs/openrate/report-v16.json` authored-column-break 스트라텀(5문단 문서에서 대상 문단 위치를 0~4로 로테이션, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-10 측정). 옛 5.x 표면(`doc.set_paragraph_format`)에는 의도적으로 안 얹었다 — 그 shim은 5.x 시그니처 그대로 얼려두는 게 계약이라(7.0 제거 예정), 신규 옵션은 `doc.styles.apply_paragraph_format`에만 산다 |
 | 표 구조 변경(행·열·표 삭제/삽입, 열 오토핏) | Preserve·Edit·Render-verified | `hwpx.table_patch.apply_table_ops`; corpus-metrics「바이트 보존」497/497(patch 경로). 실한컴 렌더 검증: `docs/openrate/report-v14.json` authored-tablestructure 스트라텀(delete_column/delete_row/insert_row_by_clone/set_column_widths/autofit_columns 각 1건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정). **원장(coverage-ledger) 라우팅은 없음** — `apply_table_ops`가 건드리는 `hp:tbl`/`tr`/`tc`/`cellAddr`/`cellSpan`/`cellSz`/`cellMargin`은 전부 "문단·표 저작/편집"(대형 혼합 영역)에 이미 등록돼 있어, 여기 추가하면 이 스트라텀이 실제로 검증한 적 없는 이웃 요소까지 openrate 근거를 얻는 위양성이 생긴다(v8 polygon/arc 전례와 동일 판단) — 등급 갱신은 이 산문과 report-v14.json 직접 인용으로만. **6.12 트레인㊸ 갭⑤**가 `split_table`(표 나누기)·`merge_table`(표 붙이기) 두 op를 추가했다 — 스키마에 표 나누기/붙이기 전용 어휘는 없다(`hp:tbl`/`TableType`은 `pageBreak`/`repeatHeader`/`rowCnt`/`colCnt`뿐, `ParaList XML schema.xml:2008`), 순수 구조 편집이라 `_insert_block_by_clone`과 같은 fail-closed 원칙(병합 셀이 경계를 걸치면 거부)을 그대로 따른다. `split_table`은 `split_row` 물리 행 인덱스에서 표를 둘로 나눠(윗칸은 원래 표 id·아랫칸은 새 래핑 문단+새 표 id) 병합 셀이 경계를 걸치면 거부한다(실코퍼스 `public_official_table.hwpx`로 clean·crossing 양쪽 검증). `merge_table`은 그 역연산 — 바로 다음 표와 합치되 `colCnt` 불일치나 두 표 사이 실텍스트 존재 시 거부(내용 무음 소실 방지). **"표 뒤집기"는 이번 트레인에서 의도적으로 보류**: 행/열 순서 반전은 병합 셀·중첩표에서 정의가 흐려지고(예: rowSpan 셀을 반전하면 어느 칸이 내용을 갖는가?) 실코퍼스에 근거로 삼을 예시가 전혀 없다(스키마조차 이런 연산의 존재를 암시하지 않는다) — curve·connectLine과 같은 원칙으로 근거 없는 알고리즘을 추측하지 않는다. 실한컴 렌더 검증: `docs/openrate/report-v16.json` authored-table-split-merge 스트라텀(분할 3종[3/4/5행 표를 각기 다른 위치에서 분할]·병합 1건[2+2행 표 결합]·분할 후 재병합 왕복 1건, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-10 측정, 기존 v14의 15/15은 split/merge를 겨냥하지 않았었다) |
 | 표 생성(병합·중첩 포함) | Create·Render-verified | `add_table`·`merge_cells`(피복 셀 제거+cellSpan — 실한컴 병합 의미론과 동형, 3종 병합 렌더 픽셀 확인)·셀 문단 `add_table`(중첩). 기본값은 5.4.0에서 실한컴에 맞췄다: 셀 안여백 510/510/141/141, 기본 표 폭은 본문 폭, 중첩 표는 부모 셀 사용 폭. **남은 갭**: 선 종류는 raw 전용. **6.7+**: `table.label`/`.set_label()`/`.remove_label()`(`hp:label`, Avery형 라벨시트/명패 인쇄 레이아웃) — 사설 코퍼스 75건·436건 리버스(DEV-023, 스키마와 완전 일치), 항상 표의 마지막 자식으로 배치. **Render-verified(6.8, 트레인㉘)**: openrate v11 실한컴 배치(macOS GUI 오라클) 15/15 render-checked·음성대조 3/3 — 관측 2클러스터(2×9 소형시트·1×2 대형 정사각 명패)와 관측 밖 조합(3×6 미관측 그리드·landscape=NARROWLY·partial 속성) 전부 수용, 수용 경계가 관측 분포보다 넓다. **6.13 트레인㊻**: `equalize_column_widths()`/`equalize_row_heights()`(`HwpxOxmlTable`) — 편집기 메뉴 표면 역매핑(트레인㊷·㊺)이 찾은 부분 대응(균등화 "전용" 헬퍼 부재)을 닫는다. 신규 XML 어휘는 전혀 없음: 전자는 기존 `set_column_widths([1]*column_count)`를 전용 이름으로 노출할 뿐이고, 후자는 그 행 대응(같은 `iter_grid`/rowSpan 로직·`_distribute_size` 재사용, 병합 셀은 자신이 덮는 행/열들의 새 크기 합을 받는다 — `cellSz`만 갱신). 실한컴 렌더 검증: `docs/openrate/report-v17.json` authored-cell-equalize 스트라텀(열만/행만/양축/양축+병합 셀 1개 로테이션, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-11 측정) — 기존 `set_column_widths` 자체는 v14의 authored-tablestructure에서 1건 확인됐을 뿐 이 두 신규 편의 메서드 자체는 이번이 첫 독립 검증 |
 | 양식 채움(byte-splice) | Preserve·Edit·Render-verified | `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 부류는 측정 인공물로 판명·판정기 교정. **6.11 사이클(트레인㊳ 판정, ㊵ 이후 정리 트레인 생성)**: 이 영역 자체의 render-verified 갭(v14 소탕 대상에서 빠뜨림으로 판정)을 v15로 메움 — `docs/openrate/report-v15.json` authored-formfill 스트라텀(합성 2열 양식 → `table_patch.fill_cells`로 빈 값 셀 byte-splice 채움, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정). **원장 라우팅은 없음** — `fill_cells`가 건드리는 `hp:t`는 기존 요소 텍스트 치환일 뿐 새 요소를 안 만든다(find-replace·document-merge와 같은 이유) — 등급 갱신은 이 산문과 report-v15.json 직접 인용으로만 |
 | 편집 계획 실행(edit plan) | Preserve·Edit·Render-verified | `hwpx.plan.apply_edit_plan`(experimental, 5.6.0+): 바이트-스플라이스 op 7종을 계획 1파일로 합성 — 정적 선검증→전 체인 인메모리 실행→최종 open-safety 검증→단 1회 원자 쓰기. 중간 실패 시 output·source 바이트 불변(테스트가 바이트 비교로 증명), step별+원본→최종 `hwpx.mutation-report/v1` 실측 사영. 실한컴 렌더 검증: `docs/openrate/report-v14.json` authored-editplan 스트라텀(paragraph_patch/fill_cells/apply_table_ops(중첩)/recolor_runs_by_color/strip_runs_by_color 각 1건 — v3/v4의 옛 `edit-plan` 버킷이 이미 다룬 paragraph_patch+fill_cells 조합 이외의 3개 op가 이번 신규 실증분), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정). **원장 라우팅은 없음** — 이 모듈은 기존 op를 체이닝만 할 뿐 대응하는 단일 capabilityArea가 없다(formfield류 저수준 공유 요소와 같은 이유) — 등급 갱신은 이 산문과 report-v14.json 직접 인용으로만 |
-| 도형 저작(선·사각형·타원) | 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 반영까지 확인 |
+| 도형 저작(선·사각형·타원) | Parse·Preserve·Edit·Create·Render-verified | 전용 `add_line`·`add_rectangle`·`add_ellipse`. 기존 floating 도형은 `Shape.set_position`으로 오프셋만 편집 가능(글자처럼 취급·위치 요소 없음은 typed 거부; 아래 기존 렌더 실적이 새 이동 경로의 검증을 뜻하지 않음). 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`은 여전히 하나뿐이지만(휘발성 — 호출 스택에만 남고 파일엔 안 남음), **6.6 트레인㉒**부터 `validate_package`·`validate_editor_open_safety`가 이 위험을 저장 이후에도 검증 결과에 명시적 `warning`으로 남긴다(fail-closed 아님 — `ok`는 그대로 `True`, 정직한 신호만 추가). `hp:container` 부재는 오탐 안 됨(부재는 이 5종을 원래 안 가짐, DEV-016). 도형은 위의 전용 헬퍼를 쓸 것(전용 헬퍼는 경고하지 않는다) |
 | arc·polygon·curve·connectLine | Parse·Preserve·Create(arc·polygon, experimental)·Render-verified(arc·polygon만)·Unsupported-but-preserved(curve·connectLine) | **6.11 트레인㊳ 재발견**: `docs/openrate/report-v8.json`의 authored-polygon/authored-arc 스트라텀(각 15/15 render_checked·0 render_failed)이 애초부터 실재했고 원장(coverage-ledger)에도 `hp:polygon`/`hp:arc`로 이미 정확히 반영돼 있었다 — 하지만 이 행의 등급 문자열에 "Render-verified"가 한 번도 반영되지 않아 편집기 표면 인벤토리가 이 항목을 계속 "미실측"으로 잘못 보고해 왔다(순수 매트릭스 산문 갱신 누락, "차트" 행과 같은 종류의 결함, 이번 트레인에서 함께 바로잡음). curve·connectLine은 아래 서술대로 여전히 정직 보류(저작 API 자체가 없음, Render-verified 대상 아님). 전용 `add_polygon`(6.4+, `doc.shapes`): 실코퍼스(`hwpxlib_corpus/reader_writer__SimplePolygon.hwpx`) 리버스 — 꼭짓점은 `hc:pt`(core 네임스페이스, rect/ellipse와 같은 기하 네임스페이스 계약: 5.0.0 도형 네임스페이스 결함 수리와 동일 축), 자기 bbox 좌상단 원점 로컬 좌표계(정점 목록이 그 자기 `orgSz`와 정확히 일치, 실측). `resize()`는 이미 범용(`pt` 로컬명 스캔)이라 변경 없이 다각형에도 적용된다. 전용 `add_arc`(6.4+, `doc.shapes`): 실코퍼스(`SimpleArc.hwpx`) 리버스 — 스키마상 `hp:arc`는 좌표 3점(`center`/`ax1`/`ax2`)뿐 각도 필드가 아예 없다. 유일한 실 예시는 center가 자기 bbox 모서리에 앉고 ax1이 그 바로 아래, ax2가 그 바로 오른쪽인 사분원 하나뿐이라 그 한 배치만 점 단위로 실측 검증됐고, 나머지 세 모서리는 다른 모든 도형이 이미 쓰는 `hp:flip` 미러링으로 얻는다(새 점 계산 없음 — `corner` 인자, `TOP_LEFT`만 실측·나머지 3개는 유도). `arc_type`(NORMAL/PIE/CHORD)은 스키마 열거값 그대로 통과. **curve는 이번 사이클 정직 보류**: 유일한 실 예시(`SimpleCurve.hwpx`)에서 곡선의 `orgSz`가 꼭짓점(`hp:seg` 앵커점) bbox보다 뚜렷이 크다(폭 16636 vs 앵커점 bbox 15225·높이 21360 vs 20500) — 스플라인이 자기 앵커점 밖으로 부풀어 오르는 실측이며, 한컴의 정확한 곡선 적합 알고리즘 근거 없이 bbox를 추정하면 침묵 오류가 된다. **connectLine도 정직 보류**: 유일한 "Simple" 정본 예시(`SimpleConnectLine.hwpx`)는 자유선이 아니라 `subjectIDRef`로 다른 두 도형(rect·ellipse)을 잇는 "스마트 연결선"이고, `offset`이 음수(부호 없는 32비트로 직렬화된 것을 실측 확인)·`curSz`가 `orgSz`와 다르며·`scaMatrix`가 평행이동까지 얹은 비항등 행렬이라 그 관계식 근거가 없다. 다른 예시(`error__20230818__test.hwpx`, 미부착 `subjectIDRef=0`)는 파일명이 스스로 결함 사례임을 밝히고 `scaMatrix`가 e1=0인 퇴화 행렬이라 정본으로 못 쓴다. `startPt`/`endPt`가 `hp:connectLine`에서는 `hp:` 네임스페이스(`hp:line`의 `hc:startPt`와 다름, 실측 확인)라는 점만 확정 — 도형마다 기하 네임스페이스를 개별 검증해야 한다는 교훈 재확인 |
 | 그룹 개체(컨테이너) | Parse·Create(experimental)·Render-verified | 전용 `add_container`(6.5+, `doc.shapes`): 실코퍼스(`hwpxlib_corpus/reader_writer__SimpleContainer.hwpx` 3부재 + 실문서 2종 71개 컨테이너, 총 74개 표본) 리버스 — 부재는 독립 도형과 완전히 같은 구조(offset/orgSz/curSz/flip/rotationInfo/renderingInfo + 도형별 기하)를 유지하되 `AbstractShapeObjectType` 꼬리(sz/pos/outMargin/shapeComment — 그룹만 가짐)는 없고 `groupLevel="1"`(그룹 자신은 `"0"`), `renderingInfo`의 `transMatrix` 이동성분이 자기 `offset`과 일치, `numberingType="PICTURE"` 전량 관측. `ContainerMember.rect`/`.ellipse`/`.polygon`으로 부재를 그룹 로컬 좌표에 배치 — **`pic`/`arc`/`line`/`connectLine`/중첩 `container` 부재와 이미 배치된 도형의 재그룹은 이번 사이클 범위 밖**(전자는 같은 패턴으로 자연 확장 가능, `pic`은 media 배선이 추가로 필요). **알려진 한계**: `resize()`는 컨테이너 자신의 크기만 갱신하고 부재를 비례 재배치하지 않는다(직속 자식 스캔이 부재 도형 전체를 보지, 그 안의 점 좌표를 안 봄) — 부재별로 개별 `resize()`를 부를 것. 실한컴 렌더 검증: `docs/openrate/report-v9.json` authored-container 스트라텀(2~4부재·rect/ellipse/polygon 슬롯별 회전), macOS Hancom GUI 오라클 15/15 render_checked·0 render_failed(2026-08-07 측정) |

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/form_fit/measure.py

@@ -386,6 +386,27 @@ def _cell_margin_vertical(cell_element: object) -> tuple[int, int]:
     return (0, 0)
 
 
+def _effective_cell_margins(cell: object) -> tuple[int, int, int, int]:
+    """Respect explicit table-margin inheritance instead of inactive cell zeros."""
+    element = getattr(cell, "element", None)
+    if element is None:
+        return (0, 0, 0, 0)
+    if element.get("hasMargin") in {"0", "false", "False"}:
+        table_element = getattr(getattr(cell, "table", None), "element", None)
+        if table_element is not None:
+            for child in table_element:
+                if _local_name(child.tag) == "inMargin":
+                    return (
+                        int(child.get("left", "0") or 0),
+                        int(child.get("right", "0") or 0),
+                        int(child.get("top", "0") or 0),
+                        int(child.get("bottom", "0") or 0),
+                    )
+    left, right = _cell_margin(element)
+    top, bottom = _cell_margin_vertical(element)
+    return left, right, top, bottom
+
+
 def _first_para_line_spacing_ratio(cell: object, document: object) -> float | None:
     """Per-line em multiple from the cell's first paragraph line spacing (PERCENT).
 
@@ -478,7 +499,7 @@ def resolve_slot_metrics(
 
     raw_width = float(getattr(cell, "width", 0) or 0)
     element = getattr(cell, "element", None)
-    left, right = _cell_margin(element) if element is not None else (0, 0)
+    left, right, top, bottom = _effective_cell_margins(cell)
     inner = max(raw_width - left - right, 0.0) * safety
     inline_width, inline_count = (
         _inline_object_width(element) if element is not None else (0.0, 0)
@@ -495,7 +516,6 @@ def resolve_slot_metrics(
         row_span = int(getattr(cell, "span", (1, 1))[0])
     except Exception:  # pragma: no cover - defensive
         row_span = 1
-    top, bottom = _cell_margin_vertical(element) if element is not None else (0, 0)
     inner_h = max(raw_height - top - bottom, 0.0) * safety if raw_height > 0 else 0.0
     # A cell authored shorter than one line at the tightest pitch is an auto-grow
     # floor, not a ceiling (Hancom grows the row past it); a merged row-span's

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/opc/xml_utils.py

@@ -4,9 +4,10 @@
 from __future__ import annotations
 
 from io import BytesIO
+import re
 from typing import Mapping
 
-from lxml import etree
+import lxml.etree as etree
 
 from .security import guard_xml_bytes, guard_xml_depth
 
@@ -25,19 +26,36 @@ _HWPML_2016_TO_2011: tuple[tuple[bytes, bytes], ...] = (
 )
 
 
+_XML_MARKUP = re.compile(
+    rb"<!--.*?-->|<!\[CDATA\[.*?\]\]>|<\?.*?\?>|<[^!?](?:[^>\"']|\"[^\"]*\"|'[^']*')*>",
+    re.S,
+)
+_XML_ATTRIBUTE = re.compile(rb"([\w:.-]+)(\s*=\s*)([\"'])(.*?)\3", re.S)
+
+
 def normalize_hwpml_namespaces(data: bytes) -> bytes:
-    """Replace 2016 HWPML namespace URIs with their 2011 equivalents.
+    """Normalize namespace declarations, preserving ordinary URI-valued data.
 
-    This is a byte-level transformation applied **before** XML parsing so that
-    all downstream code can rely on a single, consistent set of namespace
-    constants (the 2011 family).  The replacement is harmless for documents
-    that already use 2011 namespaces because the 2016 byte sequences simply
-    won't appear.
+    In particular, hp:case/@hp:required-namespace is a feature-selection value,
+    not a namespace declaration. Rewriting it can select the wrong switch case.
+    Comments, CDATA, processing instructions and quoted non-xmlns values stay
+    byte-identical. The parser still uses the canonical 2011 namespace family.
     """
-    for old, new in _HWPML_2016_TO_2011:
-        if old in data:
-            data = data.replace(old, new)
-    return data
+    mapping = dict(_HWPML_2016_TO_2011)
+
+    def attribute(match: re.Match[bytes]) -> bytes:
+        name, equals, quote, value = match.groups()
+        if name == b"xmlns" or name.startswith(b"xmlns:"):
+            value = mapping.get(value, value)
+        return name + equals + quote + value + quote
+
+    def markup(match: re.Match[bytes]) -> bytes:
+        tag = match.group()
+        if tag.startswith((b"<!", b"<?")):
+            return tag
+        return _XML_ATTRIBUTE.sub(attribute, tag)
+
+    return _XML_MARKUP.sub(markup, data)
 
 
 def parse_xml(data: bytes) -> etree._Element:

{python_hwpx-6.3.0 → python_hwpx-6.4.0}/src/hwpx/oxml/objects.py

@@ -1303,6 +1303,33 @@ class HwpxOxmlShape:
 
     # --- size access -------------------------------------------------------
 
+    def set_position(self, *, horizontal_offset: int, vertical_offset: int) -> None:
+        """Set an existing floating shape's offsets, in HWP units.
+
+        The existing reference frames, alignment, anchor, geometry and size
+        are preserved. Inline shapes and missing positioning metadata refuse
+        before mutation: changing their offsets would not move the drawing.
+        """
+        from ..errors import HwpxValueError
+
+        for value in (horizontal_offset, vertical_offset):
+            if isinstance(value, bool) or not isinstance(value, int) or not -(2**31) <= value < 2**31:
+                raise HwpxValueError(
+                    "shape offsets must be signed 32-bit integer HWP units",
+                    code="shape-position-value",
+                    suggestion="Pass integer offsets in the shape's existing reference frame.",
+                )
+        position = self.element.find(f"{_HP}pos")
+        if position is None or position.get("treatAsChar") not in {"0", "false", "False"}:
+            raise HwpxValueError(
+                "position editing requires an existing floating shape",
+                code="shape-position-unsupported",
+                suggestion="Inspect the anchor; inline placement is controlled by paragraph flow.",
+            )
+        position.set("horzOffset", str(horizontal_offset))
+        position.set("vertOffset", str(vertical_offset))
+        self.paragraph.section.mark_dirty()
+
     @property
     def width(self) -> int:
         sz = self.element.find(f"{_HP}sz")