python-hwpx 2.8.3__tar.gz → 2.9.0__tar.gz

{python_hwpx-2.8.3/src/python_hwpx.egg-info → python_hwpx-2.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.8.3
+Version: 2.9.0
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License-Expression: LicenseRef-python-hwpx-NonCommercial
@@ -121,6 +121,7 @@ doc.save_to_path("결과물.hwpx")
 | 📝 **단락** | 추가/삭제/편집/서식 | 텍스트 설정, 단락 삭제(`remove_paragraph`), 스타일 참조 |
 | ✏️ **Run** | 텍스트 조각 | 추가, 교체, 볼드/이탤릭/밑줄/색상 서식 |
 | 📊 **표(Table)** | 생성/편집/병합 | N×M 표 생성, 셀 텍스트, 셀 병합/분할, 중첩 테이블 |
+| 🧭 **표 자동화** | 탐색/채우기 | 테이블 맵, 라벨 기반 셀 탐색, 경로 기반 배치 채우기 |
 | 📑 **섹션** | 추가/삭제 | `add_section(after=)`, `remove_section()`, manifest 자동 관리 |
 | 🖼️ **이미지** | 임베드/삭제 | 바이너리 데이터 관리, manifest 자동 등록 |
 | ✏️ **도형** | 선/사각형/타원 | OWPML 명세 준수 도형 삽입 |
@@ -161,6 +162,17 @@ doc.set_footer_text("1 / 10", page_type="BOTH")
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
 table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
+
+# 양식형 표 자동 채우기
+form = doc.add_table(2, 2)
+form.cell(0, 0).text = "성명:"
+form.cell(1, 0).text = "소속"
+
+doc.find_cell_by_label("성명")    # {"matches": [...], "count": 1}
+doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
 ```
 
 ### 🔍 텍스트 추출 & 검색

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/README.md

@@ -86,6 +86,7 @@ doc.save_to_path("결과물.hwpx")
 | 📝 **단락** | 추가/삭제/편집/서식 | 텍스트 설정, 단락 삭제(`remove_paragraph`), 스타일 참조 |
 | ✏️ **Run** | 텍스트 조각 | 추가, 교체, 볼드/이탤릭/밑줄/색상 서식 |
 | 📊 **표(Table)** | 생성/편집/병합 | N×M 표 생성, 셀 텍스트, 셀 병합/분할, 중첩 테이블 |
+| 🧭 **표 자동화** | 탐색/채우기 | 테이블 맵, 라벨 기반 셀 탐색, 경로 기반 배치 채우기 |
 | 📑 **섹션** | 추가/삭제 | `add_section(after=)`, `remove_section()`, manifest 자동 관리 |
 | 🖼️ **이미지** | 임베드/삭제 | 바이너리 데이터 관리, manifest 자동 등록 |
 | ✏️ **도형** | 선/사각형/타원 | OWPML 명세 준수 도형 삽입 |
@@ -126,6 +127,17 @@ doc.set_footer_text("1 / 10", page_type="BOTH")
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
 table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
+
+# 양식형 표 자동 채우기
+form = doc.add_table(2, 2)
+form.cell(0, 0).text = "성명:"
+form.cell(1, 0).text = "소속"
+
+doc.find_cell_by_label("성명")    # {"matches": [...], "count": 1}
+doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
 ```
 
 ### 🔍 텍스트 추출 & 검색

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "2.8.3"
+version = "2.9.0"
 description = "Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "LicenseRef-python-hwpx-NonCommercial"

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/src/hwpx/__init__.py

@@ -10,8 +10,12 @@ def _resolve_version() -> str:
     except PackageNotFoundError:
         return "0+unknown"
 
+def __getattr__(name: str) -> object:
+    """Resolve dynamic module attributes."""
 
-__version__ = _resolve_version()
+    if name == "__version__":
+        return _resolve_version()
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
 from .tools.text_extractor import (
     DEFAULT_NAMESPACES,

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/src/hwpx/document.py

@@ -10,7 +10,7 @@ import logging
 import uuid
 
 from os import PathLike
-from typing import Any, BinaryIO, Iterator, Sequence, overload
+from typing import TYPE_CHECKING, Any, BinaryIO, Iterator, Mapping, Sequence, overload
 
 from lxml import etree
 
@@ -53,6 +53,9 @@ _HH = f"{{{_HH_NS}}}"
 
 logger = logging.getLogger(__name__)
 
+if TYPE_CHECKING:
+    from .tools.table_navigation import TableFillResult, TableLabelSearchResult, TableMapResult
+
 
 def _append_element(
     parent: Any,
@@ -741,6 +744,34 @@ class HwpxDocument:
             char_pr_id_ref=char_pr_id_ref,
         )
 
+    def get_table_map(self) -> TableMapResult:
+        """Return compact metadata for every table in document order."""
+
+        from .tools.table_navigation import get_table_map
+
+        return get_table_map(self)
+
+    def find_cell_by_label(
+        self,
+        label_text: str,
+        direction: str = "right",
+    ) -> TableLabelSearchResult:
+        """Return every label/target cell pair that matches *label_text*."""
+
+        from .tools.table_navigation import find_cell_by_label
+
+        return find_cell_by_label(self, label_text, direction=direction)
+
+    def fill_by_path(
+        self,
+        mappings: Mapping[str, str],
+    ) -> TableFillResult:
+        """Fill table cells using ``label > direction > ...`` navigation paths."""
+
+        from .tools.table_navigation import fill_by_path
+
+        return fill_by_path(self, mappings)
+
     def add_shape(
         self,
         shape_type: str,

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/src/hwpx/tools/__init__.py

@@ -25,6 +25,19 @@ from .text_extractor import (
     describe_element_path,
     strip_namespace,
 )
+from .table_navigation import (
+    TableCellReference,
+    TableFillApplied,
+    TableFillFailed,
+    TableFillResult,
+    TableLabelMatch,
+    TableLabelSearchResult,
+    TableMapEntry,
+    TableMapResult,
+    fill_by_path,
+    find_cell_by_label,
+    get_table_map,
+)
 from .validator import (
     DocumentSchemas,
     ValidationIssue,
@@ -41,6 +54,17 @@ __all__ = [
     "build_parent_map",
     "describe_element_path",
     "strip_namespace",
+    "TableCellReference",
+    "TableFillApplied",
+    "TableFillFailed",
+    "TableFillResult",
+    "TableLabelMatch",
+    "TableLabelSearchResult",
+    "TableMapEntry",
+    "TableMapResult",
+    "fill_by_path",
+    "find_cell_by_label",
+    "get_table_map",
     "FoundElement",
     "ObjectFinder",
     "PackageValidationIssue",

python_hwpx-2.9.0/src/hwpx/tools/table_navigation.py

@@ -0,0 +1,457 @@
+"""Reusable helpers for HWPX table discovery and form-like navigation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import TYPE_CHECKING, Literal, Mapping, TypedDict
+
+from ..oxml import HwpxOxmlParagraph, HwpxOxmlTable
+
+if TYPE_CHECKING:
+    from ..document import HwpxDocument
+
+__all__ = [
+    "SearchDirection",
+    "PathDirection",
+    "TableCellReference",
+    "TableFillApplied",
+    "TableFillFailed",
+    "TableFillResult",
+    "TableLabelMatch",
+    "TableLabelSearchResult",
+    "TableMapEntry",
+    "TableMapResult",
+    "fill_by_path",
+    "find_cell_by_label",
+    "get_table_map",
+]
+
+_HP_NS = "http://www.hancom.co.kr/hwpml/2011/paragraph"
+_HP = f"{{{_HP_NS}}}"
+_WHITESPACE_RE = re.compile(r"\s+")
+
+SearchDirection = Literal["right", "down"]
+PathDirection = Literal["left", "right", "up", "down"]
+
+
+class TableMapEntry(TypedDict):
+    """Compact metadata describing a table in document order."""
+
+    table_index: int
+    paragraph_index: int
+    rows: int
+    cols: int
+    header_text: str
+    first_row_preview: list[str]
+    is_empty: bool
+
+
+class TableMapResult(TypedDict):
+    """Collection of table metadata entries."""
+
+    tables: list[TableMapEntry]
+
+
+class TableCellReference(TypedDict):
+    """A logical table cell position and its current text."""
+
+    row: int
+    col: int
+    text: str
+
+
+class TableLabelMatch(TypedDict):
+    """A label cell and the cell reached from it."""
+
+    table_index: int
+    label_cell: TableCellReference
+    target_cell: TableCellReference
+
+
+class TableLabelSearchResult(TypedDict):
+    """Result payload returned by :func:`find_cell_by_label`."""
+
+    matches: list[TableLabelMatch]
+    count: int
+
+
+class TableFillApplied(TypedDict):
+    """A successfully applied path-based fill operation."""
+
+    path: str
+    table_index: int
+    row: int
+    col: int
+    value: str
+
+
+class TableFillFailed(TypedDict):
+    """A failed path-based fill operation and its reason."""
+
+    path: str
+    reason: str
+
+
+class TableFillResult(TypedDict):
+    """Batch fill summary for :func:`fill_by_path`."""
+
+    applied: list[TableFillApplied]
+    failed: list[TableFillFailed]
+    applied_count: int
+    failed_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class _AnchoredTable:
+    table: HwpxOxmlTable
+    paragraph_index: int
+    header_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class _IndexedTable:
+    table_index: int
+    table: HwpxOxmlTable
+    paragraph_index: int
+    header_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class _LabelCandidate:
+    table_index: int
+    table: HwpxOxmlTable
+    row: int
+    col: int
+    text: str
+
+
+def _collapse_whitespace(value: str) -> str:
+    return _WHITESPACE_RE.sub(" ", value).strip()
+
+
+def _normalize_label_text(value: str) -> str:
+    normalized = _collapse_whitespace(value).casefold()
+    while normalized.endswith((":", "：")):
+        normalized = normalized[:-1].rstrip()
+    return normalized
+
+
+def _direct_paragraph_text(paragraph: HwpxOxmlParagraph) -> str:
+    parts: list[str] = []
+    for run in paragraph.element.findall(f"{_HP}run"):
+        for child in run:
+            if child.tag == f"{_HP}t" and child.text:
+                parts.append(child.text)
+    return _collapse_whitespace("".join(parts))
+
+
+def _collect_tables_from_table(
+    table: HwpxOxmlTable,
+    *,
+    anchor_paragraph_index: int,
+    inherited_header_text: str,
+    sink: list[_AnchoredTable],
+) -> str:
+    last_header_text = inherited_header_text
+    for row in table.rows:
+        for cell in row.cells:
+            for paragraph in cell.paragraphs:
+                last_header_text = _collect_tables_from_paragraph(
+                    paragraph,
+                    anchor_paragraph_index=anchor_paragraph_index,
+                    inherited_header_text=last_header_text,
+                    sink=sink,
+                )
+    return last_header_text
+
+
+def _collect_tables_from_paragraph(
+    paragraph: HwpxOxmlParagraph,
+    *,
+    anchor_paragraph_index: int,
+    inherited_header_text: str,
+    sink: list[_AnchoredTable],
+) -> str:
+    paragraph_text_parts: list[str] = []
+    last_header_text = inherited_header_text
+
+    for run in paragraph.element.findall(f"{_HP}run"):
+        for child in run:
+            if child.tag == f"{_HP}t":
+                if child.text:
+                    paragraph_text_parts.append(child.text)
+                continue
+            if child.tag != f"{_HP}tbl":
+                continue
+
+            paragraph_prefix_text = _collapse_whitespace("".join(paragraph_text_parts))
+            header_text = paragraph_prefix_text or last_header_text
+            table = HwpxOxmlTable(child, paragraph)
+            sink.append(
+                _AnchoredTable(
+                    table=table,
+                    paragraph_index=anchor_paragraph_index,
+                    header_text=header_text,
+                )
+            )
+            last_header_text = _collect_tables_from_table(
+                table,
+                anchor_paragraph_index=anchor_paragraph_index,
+                inherited_header_text=header_text,
+                sink=sink,
+            )
+
+    paragraph_text = _collapse_whitespace("".join(paragraph_text_parts))
+    return paragraph_text or last_header_text
+
+
+def _collect_document_tables(document: HwpxDocument) -> list[_IndexedTable]:
+    anchored_tables: list[_AnchoredTable] = []
+    last_top_level_text = ""
+
+    for paragraph_index, paragraph in enumerate(document.paragraphs):
+        _collect_tables_from_paragraph(
+            paragraph,
+            anchor_paragraph_index=paragraph_index,
+            inherited_header_text=last_top_level_text,
+            sink=anchored_tables,
+        )
+        paragraph_text = _direct_paragraph_text(paragraph)
+        if paragraph_text:
+            last_top_level_text = paragraph_text
+
+    return [
+        _IndexedTable(
+            table_index=table_index,
+            table=item.table,
+            paragraph_index=item.paragraph_index,
+            header_text=item.header_text,
+        )
+        for table_index, item in enumerate(anchored_tables)
+    ]
+
+
+def _cell_text(table: HwpxOxmlTable, row_index: int, col_index: int) -> str:
+    return table.cell(row_index, col_index).text
+
+
+def _table_is_empty(table: HwpxOxmlTable) -> bool:
+    for row_index in range(table.row_count):
+        for col_index in range(table.column_count):
+            if _cell_text(table, row_index, col_index).strip():
+                return False
+    return True
+
+
+def _first_row_preview(table: HwpxOxmlTable) -> list[str]:
+    if table.row_count == 0:
+        return []
+    return [_cell_text(table, 0, col_index) for col_index in range(table.column_count)]
+
+
+def _direction_delta(direction: PathDirection) -> tuple[int, int]:
+    if direction == "right":
+        return (0, 1)
+    if direction == "left":
+        return (0, -1)
+    if direction == "down":
+        return (1, 0)
+    return (-1, 0)
+
+
+def _move(
+    table: HwpxOxmlTable,
+    row_index: int,
+    col_index: int,
+    direction: PathDirection,
+) -> tuple[int, int] | None:
+    row_delta, col_delta = _direction_delta(direction)
+    target_row = row_index + row_delta
+    target_col = col_index + col_delta
+    if target_row < 0 or target_col < 0:
+        return None
+    if target_row >= table.row_count or target_col >= table.column_count:
+        return None
+    return (target_row, target_col)
+
+
+def _find_label_candidates(
+    tables: list[_IndexedTable],
+    label_text: str,
+) -> list[_LabelCandidate]:
+    normalized_label = _normalize_label_text(label_text)
+    if not normalized_label:
+        raise ValueError("label_text must contain at least one non-whitespace character")
+
+    candidates: list[_LabelCandidate] = []
+    for table_ref in tables:
+        for row_index in range(table_ref.table.row_count):
+            for col_index in range(table_ref.table.column_count):
+                cell_text = _cell_text(table_ref.table, row_index, col_index)
+                if _normalize_label_text(cell_text) != normalized_label:
+                    continue
+                candidates.append(
+                    _LabelCandidate(
+                        table_index=table_ref.table_index,
+                        table=table_ref.table,
+                        row=row_index,
+                        col=col_index,
+                        text=cell_text,
+                    )
+                )
+    return candidates
+
+
+def _cell_reference(
+    table: HwpxOxmlTable,
+    row_index: int,
+    col_index: int,
+) -> TableCellReference:
+    return {
+        "row": row_index,
+        "col": col_index,
+        "text": _cell_text(table, row_index, col_index),
+    }
+
+
+def _parse_path(path: str) -> tuple[str | None, list[str], str | None]:
+    tokens = [token.strip() for token in path.split(">")]
+    if not tokens or not tokens[0]:
+        return (None, [], "path must start with a label")
+
+    label_text = tokens[0]
+    raw_directions = [token for token in tokens[1:] if token]
+    if not raw_directions:
+        return (label_text, [], "path must include at least one direction")
+    return (label_text, raw_directions, None)
+
+
+def get_table_map(document: HwpxDocument) -> TableMapResult:
+    """Return compact metadata for every table in document order."""
+
+    tables: list[TableMapEntry] = []
+    for table_ref in _collect_document_tables(document):
+        tables.append(
+            {
+                "table_index": table_ref.table_index,
+                "paragraph_index": table_ref.paragraph_index,
+                "rows": table_ref.table.row_count,
+                "cols": table_ref.table.column_count,
+                "header_text": table_ref.header_text,
+                "first_row_preview": _first_row_preview(table_ref.table),
+                "is_empty": _table_is_empty(table_ref.table),
+            }
+        )
+    return {"tables": tables}
+
+
+def find_cell_by_label(
+    document: HwpxDocument,
+    label_text: str,
+    direction: SearchDirection = "right",
+) -> TableLabelSearchResult:
+    """Find label cells and return the adjacent target cells that remain in bounds."""
+
+    if direction not in {"right", "down"}:
+        raise ValueError("direction must be one of: right, down")
+
+    matches: list[TableLabelMatch] = []
+    for candidate in _find_label_candidates(_collect_document_tables(document), label_text):
+        target = _move(candidate.table, candidate.row, candidate.col, direction)
+        if target is None:
+            continue
+        target_row, target_col = target
+        matches.append(
+            {
+                "table_index": candidate.table_index,
+                "label_cell": {
+                    "row": candidate.row,
+                    "col": candidate.col,
+                    "text": candidate.text,
+                },
+                "target_cell": _cell_reference(candidate.table, target_row, target_col),
+            }
+        )
+
+    return {
+        "matches": matches,
+        "count": len(matches),
+    }
+
+
+def fill_by_path(
+    document: HwpxDocument,
+    mappings: Mapping[str, str],
+) -> TableFillResult:
+    """Fill multiple table cells using label-based navigation paths."""
+
+    indexed_tables = _collect_document_tables(document)
+    applied: list[TableFillApplied] = []
+    failed: list[TableFillFailed] = []
+
+    for path, value in mappings.items():
+        label_text, raw_directions, path_error = _parse_path(path)
+        if path_error is not None or label_text is None:
+            failed.append({"path": path, "reason": path_error or "invalid path"})
+            continue
+
+        try:
+            candidates = _find_label_candidates(indexed_tables, label_text)
+        except ValueError as exc:
+            failed.append({"path": path, "reason": str(exc)})
+            continue
+
+        if not candidates:
+            failed.append({"path": path, "reason": "label not found"})
+            continue
+        if len(candidates) > 1:
+            failed.append({"path": path, "reason": "ambiguous label"})
+            continue
+
+        candidate = candidates[0]
+        current_row = candidate.row
+        current_col = candidate.col
+        navigation_failed = False
+
+        for raw_direction in raw_directions:
+            direction = raw_direction.casefold()
+            if direction not in {"left", "right", "up", "down"}:
+                failed.append(
+                    {
+                        "path": path,
+                        "reason": f"unsupported direction: {raw_direction}",
+                    }
+                )
+                navigation_failed = True
+                break
+
+            next_position = _move(candidate.table, current_row, current_col, direction)
+            if next_position is None:
+                failed.append({"path": path, "reason": "navigation out of bounds"})
+                navigation_failed = True
+                break
+
+            current_row, current_col = next_position
+
+        if navigation_failed:
+            continue
+
+        text_value = str(value)
+        candidate.table.set_cell_text(current_row, current_col, text_value, logical=True)
+        applied.append(
+            {
+                "path": path,
+                "table_index": candidate.table_index,
+                "row": current_row,
+                "col": current_col,
+                "value": text_value,
+            }
+        )
+
+    return {
+        "applied": applied,
+        "failed": failed,
+        "applied_count": len(applied),
+        "failed_count": len(failed),
+    }

{python_hwpx-2.8.3 → python_hwpx-2.9.0/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 2.8.3
+Version: 2.9.0
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License-Expression: LicenseRef-python-hwpx-NonCommercial
@@ -121,6 +121,7 @@ doc.save_to_path("결과물.hwpx")
 | 📝 **단락** | 추가/삭제/편집/서식 | 텍스트 설정, 단락 삭제(`remove_paragraph`), 스타일 참조 |
 | ✏️ **Run** | 텍스트 조각 | 추가, 교체, 볼드/이탤릭/밑줄/색상 서식 |
 | 📊 **표(Table)** | 생성/편집/병합 | N×M 표 생성, 셀 텍스트, 셀 병합/분할, 중첩 테이블 |
+| 🧭 **표 자동화** | 탐색/채우기 | 테이블 맵, 라벨 기반 셀 탐색, 경로 기반 배치 채우기 |
 | 📑 **섹션** | 추가/삭제 | `add_section(after=)`, `remove_section()`, manifest 자동 관리 |
 | 🖼️ **이미지** | 임베드/삭제 | 바이너리 데이터 관리, manifest 자동 등록 |
 | ✏️ **도형** | 선/사각형/타원 | OWPML 명세 준수 도형 삽입 |
@@ -161,6 +162,17 @@ doc.set_footer_text("1 / 10", page_type="BOTH")
 # 표 셀 병합·분할
 table.merge_cells(0, 0, 1, 1)   # (0,0)~(1,1) 병합
 table.set_cell_text(0, 0, "병합된 셀", logical=True, split_merged=True)
+
+# 양식형 표 자동 채우기
+form = doc.add_table(2, 2)
+form.cell(0, 0).text = "성명:"
+form.cell(1, 0).text = "소속"
+
+doc.find_cell_by_label("성명")    # {"matches": [...], "count": 1}
+doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
 ```
 
 ### 🔍 텍스트 추출 & 검색

{python_hwpx-2.8.3 → python_hwpx-2.9.0}/src/python_hwpx.egg-info/SOURCES.txt

@@ -30,6 +30,7 @@ src/hwpx/tools/exporter.py
 src/hwpx/tools/object_finder.py
 src/hwpx/tools/package_validator.py
 src/hwpx/tools/page_guard.py
+src/hwpx/tools/table_navigation.py
 src/hwpx/tools/template_analyzer.py
 src/hwpx/tools/text_extract_cli.py
 src/hwpx/tools/text_extractor.py
@@ -60,6 +61,7 @@ tests/test_paragraph_section_management.py
 tests/test_repr_snapshots.py
 tests/test_section_headers.py
 tests/test_split_merged_cell.py
+tests/test_table_navigation.py
 tests/test_tables_default_border.py
 tests/test_text_extractor_annotations.py
 tests/test_version_metadata.py

python_hwpx-2.9.0/tests/test_table_navigation.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+from hwpx import HwpxDocument
+
+
+def _paragraph_index(document: HwpxDocument, target) -> int:
+    for index, paragraph in enumerate(document.paragraphs):
+        if paragraph.element is target.element:
+            return index
+    raise AssertionError("target paragraph was not found in document order")
+
+
+def test_fill_by_path_handles_unique_labels_in_a_single_table() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("1. 기본 현황")
+    table = document.add_table(2, 2)
+    table.cell(0, 0).text = "성명:"
+    table.cell(1, 0).text = "소속"
+
+    result = document.fill_by_path(
+        {
+            "성명 > right": "홍길동",
+            "소속 > right": "플랫폼팀",
+        }
+    )
+
+    assert result["applied_count"] == 2
+    assert result["failed_count"] == 0
+    assert table.cell(0, 1).text == "홍길동"
+    assert table.cell(1, 1).text == "플랫폼팀"
+
+
+def test_find_cell_by_label_normalizes_trailing_colons() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("기본 정보")
+    table = document.add_table(1, 2)
+    table.cell(0, 0).text = "성명:"
+
+    result = document.find_cell_by_label("성명")
+
+    assert result["count"] == 1
+    assert result["matches"][0]["table_index"] == 0
+    assert result["matches"][0]["label_cell"] == {
+        "row": 0,
+        "col": 0,
+        "text": "성명:",
+    }
+    assert result["matches"][0]["target_cell"] == {
+        "row": 0,
+        "col": 1,
+        "text": "",
+    }
+
+
+def test_multiple_tables_with_the_same_label_return_all_matches_and_make_fill_ambiguous() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("1. 신청인")
+    first = document.add_table(1, 2)
+    first.cell(0, 0).text = "성명"
+
+    document.add_paragraph("2. 보호자")
+    second = document.add_table(1, 2)
+    second.cell(0, 0).text = "성명"
+
+    matches = document.find_cell_by_label("성명")
+    fill_result = document.fill_by_path({"성명 > right": "홍길동"})
+
+    assert matches["count"] == 2
+    assert [match["table_index"] for match in matches["matches"]] == [0, 1]
+    assert fill_result["applied_count"] == 0
+    assert fill_result["failed_count"] == 1
+    assert fill_result["failed"][0] == {
+        "path": "성명 > right",
+        "reason": "ambiguous label",
+    }
+    assert first.cell(0, 1).text == ""
+    assert second.cell(0, 1).text == ""
+
+
+def test_out_of_bounds_candidates_are_skipped_and_reported_for_batch_fill() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("경계 값")
+    table = document.add_table(2, 2)
+    table.cell(0, 1).text = "마지막열"
+    table.cell(1, 0).text = "마지막행"
+
+    right_matches = document.find_cell_by_label("마지막열", direction="right")
+    down_matches = document.find_cell_by_label("마지막행", direction="down")
+    fill_result = document.fill_by_path(
+        {
+            "마지막열 > right": "실패",
+            "마지막행 > down": "실패",
+        }
+    )
+
+    assert right_matches["count"] == 0
+    assert down_matches["count"] == 0
+    assert fill_result["applied_count"] == 0
+    assert fill_result["failed_count"] == 2
+    assert fill_result["failed"] == [
+        {"path": "마지막열 > right", "reason": "navigation out of bounds"},
+        {"path": "마지막행 > down", "reason": "navigation out of bounds"},
+    ]
+
+
+def test_fill_by_path_supports_multi_step_navigation() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("정산표")
+    table = document.add_table(3, 2)
+    table.cell(0, 0).text = "합계"
+
+    result = document.fill_by_path({"합계 > down > right": "100"})
+
+    assert result["applied"] == [
+        {
+            "path": "합계 > down > right",
+            "table_index": 0,
+            "row": 1,
+            "col": 1,
+            "value": "100",
+        }
+    ]
+    assert result["failed"] == []
+    assert table.cell(1, 1).text == "100"
+
+
+def test_get_table_map_reports_stable_order_shape_and_header_text() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("1. 기본 현황")
+    first = document.add_table(2, 4)
+    first.cell(0, 0).text = "성명"
+    first.cell(0, 1).text = "소속"
+    first.cell(0, 2).text = "직위"
+    first.cell(0, 3).text = "연락처"
+    first.cell(1, 0).text = "홍길동"
+
+    document.add_paragraph("2. 비고")
+    second = document.add_table(1, 2)
+    second.cell(0, 0).text = "항목"
+    second.cell(0, 1).text = "값"
+
+    result = document.get_table_map()
+
+    assert result["tables"] == [
+        {
+            "table_index": 0,
+            "paragraph_index": _paragraph_index(document, first.paragraph),
+            "rows": 2,
+            "cols": 4,
+            "header_text": "1. 기본 현황",
+            "first_row_preview": ["성명", "소속", "직위", "연락처"],
+            "is_empty": False,
+        },
+        {
+            "table_index": 1,
+            "paragraph_index": _paragraph_index(document, second.paragraph),
+            "rows": 1,
+            "cols": 2,
+            "header_text": "2. 비고",
+            "first_row_preview": ["항목", "값"],
+            "is_empty": False,
+        },
+    ]
+
+
+def test_get_table_map_marks_tables_with_only_empty_strings_as_empty() -> None:
+    document = HwpxDocument.new()
+    document.add_paragraph("빈 표")
+    table = document.add_table(2, 2)
+
+    result = document.get_table_map()
+
+    assert result["tables"] == [
+        {
+            "table_index": 0,
+            "paragraph_index": _paragraph_index(document, table.paragraph),
+            "rows": 2,
+            "cols": 2,
+            "header_text": "빈 표",
+            "first_row_preview": ["", ""],
+            "is_empty": True,
+        }
+    ]