python-hwpx 1.7__tar.gz → 1.9__tar.gz

{python_hwpx-1.7/src/python_hwpx.egg-info → python_hwpx-1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 1.7
+Version: 1.9
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -126,7 +126,7 @@ document.save("output/example.hwpx")
 
 `HwpxDocument.add_table()`은 문서에 정의된 테두리 채우기가 없으면 헤더 참조 목록에 "기본 실선" `borderFill`을 만들어 표와 모든 셀에 참조를 연결합니다.
 
-표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다.
+표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다. 병합된 표 구조를 다뤄야 한다면 `table.iter_grid()` 또는 `table.get_cell_map()`으로 논리 격자와 실제 셀의 매핑을 확인하고, `set_cell_text(..., logical=True, split_merged=True)`로 논리 좌표 기반 편집과 자동 병합 해제를 동시에 처리할 수 있습니다.
 
 더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
 

{python_hwpx-1.7 → python_hwpx-1.9}/README.md

@@ -63,7 +63,7 @@ document.save("output/example.hwpx")
 
 `HwpxDocument.add_table()`은 문서에 정의된 테두리 채우기가 없으면 헤더 참조 목록에 "기본 실선" `borderFill`을 만들어 표와 모든 셀에 참조를 연결합니다.
 
-표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다.
+표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다. 병합된 표 구조를 다뤄야 한다면 `table.iter_grid()` 또는 `table.get_cell_map()`으로 논리 격자와 실제 셀의 매핑을 확인하고, `set_cell_text(..., logical=True, split_merged=True)`로 논리 좌표 기반 편집과 자동 병합 해제를 동시에 처리할 수 있습니다.
 
 더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
 

{python_hwpx-1.7 → python_hwpx-1.9}/pyproject.toml

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

{python_hwpx-1.7 → python_hwpx-1.9}/src/hwpx/oxml/__init__.py

@@ -31,6 +31,7 @@ from .document import (
     HwpxOxmlSectionProperties,
     HwpxOxmlTable,
     HwpxOxmlTableCell,
+    HwpxTableGridPosition,
     HwpxOxmlTableRow,
     HwpxOxmlVersion,
     PageMargins,
@@ -141,6 +142,7 @@ __all__ = [
     "HwpxOxmlSectionProperties",
     "HwpxOxmlTable",
     "HwpxOxmlTableCell",
+    "HwpxTableGridPosition",
     "HwpxOxmlTableRow",
     "HwpxOxmlVersion",
     "KeyDerivation",

{python_hwpx-1.7 → python_hwpx-1.9}/src/hwpx/oxml/document.py

@@ -119,14 +119,14 @@ def _create_paragraph_element(
     return paragraph
 
 
-_LAYOUT_CACHE_ELEMENT_NAMES = {"lineSegArray"}
+_LAYOUT_CACHE_ELEMENT_NAMES = {"linesegarray"}
 
 
 def _clear_paragraph_layout_cache(paragraph: ET.Element) -> None:
     """Remove cached layout metadata such as ``<hp:lineSegArray>``."""
 
     for child in list(paragraph):
-        if _element_local_name(child) in _LAYOUT_CACHE_ELEMENT_NAMES:
+        if _element_local_name(child).lower() in _LAYOUT_CACHE_ELEMENT_NAMES:
             paragraph.remove(child)
 
 
@@ -1572,6 +1572,7 @@ class HwpxOxmlTableCell:
     def text(self, value: str) -> None:
         text_element = self._ensure_text_element()
         text_element.text = value
+        self.element.set("dirty", "1")
         self.table.mark_dirty()
 
     def remove(self) -> None:
@@ -1579,6 +1580,29 @@ class HwpxOxmlTableCell:
         self.table.mark_dirty()
 
 
+@dataclass(frozen=True)
+class HwpxTableGridPosition:
+    """Mapping between a logical table position and a physical cell."""
+
+    row: int
+    column: int
+    cell: HwpxOxmlTableCell
+    anchor: Tuple[int, int]
+    span: Tuple[int, int]
+
+    @property
+    def is_anchor(self) -> bool:
+        return (self.row, self.column) == self.anchor
+
+    @property
+    def row_span(self) -> int:
+        return self.span[0]
+
+    @property
+    def col_span(self) -> int:
+        return self.span[1]
+
+
 class HwpxOxmlTableRow:
     """Represents a table row."""
 
@@ -1721,26 +1745,266 @@ class HwpxOxmlTable:
     def rows(self) -> List[HwpxOxmlTableRow]:
         return [HwpxOxmlTableRow(row, self) for row in self.element.findall(f"{_HP}tr")]
 
-    def cell(self, row_index: int, col_index: int) -> HwpxOxmlTableCell:
-        if row_index < 0 or col_index < 0:
-            raise IndexError("row_index and col_index must be non-negative")
-
+    def _build_cell_grid(self) -> dict[Tuple[int, int], HwpxTableGridPosition]:
+        mapping: dict[Tuple[int, int], HwpxTableGridPosition] = {}
         for row in self.element.findall(f"{_HP}tr"):
-            for cell in row.findall(f"{_HP}tc"):
-                wrapper = HwpxOxmlTableCell(cell, self, row)
+            for cell_element in row.findall(f"{_HP}tc"):
+                wrapper = HwpxOxmlTableCell(cell_element, self, row)
                 start_row, start_col = wrapper.address
                 span_row, span_col = wrapper.span
-                if (
-                    start_row <= row_index < start_row + span_row
-                    and start_col <= col_index < start_col + span_col
-                ):
-                    return wrapper
-        raise IndexError("cell coordinates out of range")
+                for logical_row in range(start_row, start_row + span_row):
+                    for logical_col in range(start_col, start_col + span_col):
+                        key = (logical_row, logical_col)
+                        existing = mapping.get(key)
+                        entry = HwpxTableGridPosition(
+                            row=logical_row,
+                            column=logical_col,
+                            cell=wrapper,
+                            anchor=(start_row, start_col),
+                            span=(span_row, span_col),
+                        )
+                        if (
+                            existing is not None
+                            and existing.cell.element is not wrapper.element
+                        ):
+                            raise ValueError(
+                                "table grid contains overlapping cell spans"
+                            )
+                        mapping[key] = entry
+        return mapping
 
-    def set_cell_text(self, row_index: int, col_index: int, text: str) -> None:
-        cell = self.cell(row_index, col_index)
+    def _grid_entry(self, row_index: int, col_index: int) -> HwpxTableGridPosition:
+        if row_index < 0 or col_index < 0:
+            raise IndexError("row_index and col_index must be non-negative")
+
+        row_count = self.row_count
+        col_count = self.column_count
+        if row_index >= row_count or col_index >= col_count:
+            raise IndexError(
+                "cell coordinates (%d, %d) exceed table bounds %dx%d"
+                % (row_index, col_index, row_count, col_count)
+            )
+
+        entry = self._build_cell_grid().get((row_index, col_index))
+        if entry is None:
+            raise IndexError(
+                "cell coordinates (%d, %d) are covered by a merged cell"
+                " without an accessible anchor; inspect iter_grid() for details"
+                % (row_index, col_index)
+            )
+        return entry
+
+    def iter_grid(self) -> Iterator[HwpxTableGridPosition]:
+        """Yield grid-aware mappings for every logical table position."""
+
+        mapping = self._build_cell_grid()
+        row_count = self.row_count
+        col_count = self.column_count
+        for row_index in range(row_count):
+            for col_index in range(col_count):
+                entry = mapping.get((row_index, col_index))
+                if entry is None:
+                    raise IndexError(
+                        "cell coordinates (%d, %d) do not resolve to a physical cell"
+                        % (row_index, col_index)
+                    )
+                yield entry
+
+    def get_cell_map(self) -> List[List[HwpxTableGridPosition]]:
+        """Return a 2D list mapping logical positions to physical cells."""
+
+        row_count = self.row_count
+        col_count = self.column_count
+        grid: List[List[HwpxTableGridPosition | None]] = [
+            [None for _ in range(col_count)] for _ in range(row_count)
+        ]
+        for entry in self.iter_grid():
+            grid[entry.row][entry.column] = entry
+
+        for row_index in range(row_count):
+            for col_index in range(col_count):
+                if grid[row_index][col_index] is None:
+                    raise IndexError(
+                        "cell coordinates (%d, %d) do not resolve to a physical cell"
+                        % (row_index, col_index)
+                    )
+
+        return [
+            [grid[row_index][col_index] for col_index in range(col_count)]
+            for row_index in range(row_count)
+        ]
+
+    def cell(self, row_index: int, col_index: int) -> HwpxOxmlTableCell:
+        entry = self._grid_entry(row_index, col_index)
+        return entry.cell
+
+    def set_cell_text(
+        self,
+        row_index: int,
+        col_index: int,
+        text: str,
+        *,
+        logical: bool = False,
+        split_merged: bool = False,
+    ) -> None:
+        if logical:
+            entry = self._grid_entry(row_index, col_index)
+            if split_merged and not entry.is_anchor:
+                cell = self.split_merged_cell(row_index, col_index)
+            else:
+                cell = entry.cell
+        else:
+            cell = self.cell(row_index, col_index)
         cell.text = text
 
+    def split_merged_cell(
+        self, row_index: int, col_index: int
+    ) -> HwpxOxmlTableCell:
+        entry = self._grid_entry(row_index, col_index)
+        cell = entry.cell
+        start_row, start_col = entry.anchor
+        span_row, span_col = entry.span
+
+        if span_row == 1 and span_col == 1:
+            return cell
+
+        row_elements = self.element.findall(f"{_HP}tr")
+        if len(row_elements) < start_row + span_row:
+            raise IndexError(
+                "table rows missing while splitting merged cell covering"
+                f" ({start_row}, {start_col})"
+            )
+
+        width_segments = _distribute_size(cell.width, span_col)
+        height_segments = _distribute_size(cell.height, span_row)
+        if not width_segments:
+            width_segments = [cell.width] + [0] * (span_col - 1)
+        if not height_segments:
+            height_segments = [cell.height] + [0] * (span_row - 1)
+
+        template_attrs = {key: value for key, value in cell.element.attrib.items()}
+        preserved_children = [
+            deepcopy(child)
+            for child in cell.element
+            if _element_local_name(child)
+            not in {"subList", "cellAddr", "cellSpan", "cellSz", "cellMargin"}
+        ]
+        template_sublist = cell.element.find(f"{_HP}subList")
+        template_margin = cell.element.find(f"{_HP}cellMargin")
+
+        for row_offset in range(span_row):
+            logical_row = start_row + row_offset
+            row_element = row_elements[logical_row]
+            row_height = height_segments[row_offset] if row_offset < len(height_segments) else cell.height
+            for col_offset in range(span_col):
+                logical_col = start_col + col_offset
+                col_width = width_segments[col_offset] if col_offset < len(width_segments) else cell.width
+
+                if row_offset == 0 and col_offset == 0:
+                    addr = cell._addr_element()
+                    if addr is None:
+                        addr = ET.SubElement(cell.element, f"{_HP}cellAddr")
+                    addr.set("rowAddr", str(start_row))
+                    addr.set("colAddr", str(start_col))
+                    span_element = cell._span_element()
+                    span_element.set("rowSpan", "1")
+                    span_element.set("colSpan", "1")
+                    size_element = cell._size_element()
+                    size_element.set("width", str(col_width))
+                    size_element.set("height", str(row_height))
+                    continue
+
+                existing_target: HwpxOxmlTableCell | None = None
+                for existing in row_element.findall(f"{_HP}tc"):
+                    wrapper = HwpxOxmlTableCell(existing, self, row_element)
+                    existing_row, existing_col = wrapper.address
+                    span_r, span_c = wrapper.span
+                    if existing_row == logical_row and existing_col == logical_col:
+                        existing_target = wrapper
+                        break
+                    if (
+                        existing_row <= logical_row < existing_row + span_r
+                        and existing_col <= logical_col < existing_col + span_c
+                    ):
+                        if wrapper.element is cell.element:
+                            continue
+                        raise ValueError(
+                            "Cannot split merged cell covering (%d, %d) because"
+                            " position (%d, %d) overlaps another merged cell"
+                            % (start_row, start_col, logical_row, logical_col)
+                        )
+
+                if existing_target is not None:
+                    existing_target.set_span(1, 1)
+                    existing_target.set_size(col_width, row_height)
+                    continue
+
+                new_cell_element = ET.Element(f"{_HP}tc", dict(template_attrs))
+                for child in preserved_children:
+                    new_cell_element.append(deepcopy(child))
+
+                sublist_attrs = _default_sublist_attributes()
+                template_para = None
+                if template_sublist is not None:
+                    for key, value in template_sublist.attrib.items():
+                        if key == "id":
+                            continue
+                        sublist_attrs.setdefault(key, value)
+                    template_para = template_sublist.find(f"{_HP}p")
+
+                sublist = ET.SubElement(new_cell_element, f"{_HP}subList", sublist_attrs)
+                paragraph_attrs = _default_cell_paragraph_attributes()
+                run_attrs = {"charPrIDRef": "0"}
+                if template_para is not None:
+                    for key, value in template_para.attrib.items():
+                        if key == "id":
+                            continue
+                        paragraph_attrs.setdefault(key, value)
+                    template_run = template_para.find(f"{_HP}run")
+                    if template_run is not None:
+                        run_attrs = dict(template_run.attrib)
+                        if "charPrIDRef" not in run_attrs:
+                            run_attrs["charPrIDRef"] = "0"
+                paragraph = ET.SubElement(sublist, f"{_HP}p", paragraph_attrs)
+                run = ET.SubElement(paragraph, f"{_HP}run", run_attrs)
+                ET.SubElement(run, f"{_HP}t")
+
+                ET.SubElement(
+                    new_cell_element,
+                    f"{_HP}cellAddr",
+                    {"rowAddr": str(logical_row), "colAddr": str(logical_col)},
+                )
+                ET.SubElement(
+                    new_cell_element,
+                    f"{_HP}cellSpan",
+                    {"rowSpan": "1", "colSpan": "1"},
+                )
+                ET.SubElement(
+                    new_cell_element,
+                    f"{_HP}cellSz",
+                    {"width": str(col_width), "height": str(row_height)},
+                )
+                if template_margin is not None:
+                    new_cell_element.append(deepcopy(template_margin))
+                else:
+                    ET.SubElement(
+                        new_cell_element,
+                        f"{_HP}cellMargin",
+                        _default_cell_margin_attributes(),
+                    )
+
+                existing_cells = list(row_element.findall(f"{_HP}tc"))
+                insert_index = len(existing_cells)
+                for idx, existing in enumerate(existing_cells):
+                    wrapper = HwpxOxmlTableCell(existing, self, row_element)
+                    if wrapper.address[1] > logical_col:
+                        insert_index = idx
+                        break
+                row_element.insert(insert_index, new_cell_element)
+
+        self.mark_dirty()
+        return self.cell(row_index, col_index)
+
     def merge_cells(
         self,
         start_row: int,

{python_hwpx-1.7 → python_hwpx-1.9/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 1.7
+Version: 1.9
 Summary: Hancom HWPX 패키지를 로드하고 편집하기 위한 Python 유틸리티 모음
 Author: python-hwpx Maintainers
 License: Non-Commercial License
@@ -126,7 +126,7 @@ document.save("output/example.hwpx")
 
 `HwpxDocument.add_table()`은 문서에 정의된 테두리 채우기가 없으면 헤더 참조 목록에 "기본 실선" `borderFill`을 만들어 표와 모든 셀에 참조를 연결합니다.
 
-표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다.
+표 셀 텍스트를 편집하는 `table.set_cell_text()`는 기존 단락에 남아 있는 `lineSegArray`와 같은 줄 배치 캐시를 제거하여 한/글이 문서를 다시 열 때 줄바꿈을 새로 계산하도록 합니다. 병합된 표 구조를 다뤄야 한다면 `table.iter_grid()` 또는 `table.get_cell_map()`으로 논리 격자와 실제 셀의 매핑을 확인하고, `set_cell_text(..., logical=True, split_merged=True)`로 논리 좌표 기반 편집과 자동 병합 해제를 동시에 처리할 수 있습니다.
 
 더 많은 실전 패턴은 [빠른 시작](docs/quickstart.md)과 [사용 가이드](docs/usage.md)의 "빠른 예제 모음"에서 확인할 수 있습니다.
 

{python_hwpx-1.7 → python_hwpx-1.9}/tests/test_document_formatting.py

@@ -309,7 +309,9 @@ def test_table_set_cell_text_removes_layout_cache() -> None:
     paragraph = sublist.find(f"{HP}p")
     assert paragraph is not None
     ET.SubElement(paragraph, f"{HP}lineSegArray")
+    ET.SubElement(paragraph, f"{HP}linesegarray")
     assert paragraph.find(f"{HP}lineSegArray") is not None
+    assert paragraph.find(f"{HP}linesegarray") is not None
     text_element = paragraph.find(f".//{HP}t")
     assert text_element is not None
     text_element.text = "Cached"
@@ -318,6 +320,29 @@ def test_table_set_cell_text_removes_layout_cache() -> None:
 
     assert table.cell(0, 0).text == "Updated"
     assert paragraph.find(f"{HP}lineSegArray") is None
+    assert paragraph.find(f"{HP}linesegarray") is None
+
+
+def test_table_cell_text_marks_cell_dirty_attribute() -> None:
+    section_element = ET.Element(f"{HS}sec")
+    section = HwpxOxmlSection("section0.xml", section_element)
+    manifest = ET.Element("manifest")
+    root = HwpxOxmlDocument(manifest, [section], [])
+    document = HwpxDocument(cast(HwpxPackage, object()), root)
+
+    table = document.add_table(1, 1, section=section)
+    cell = table.cell(0, 0)
+    assert cell.element.get("dirty") == "0"
+
+    cell.text = "Updated"
+
+    assert cell.element.get("dirty") == "1"
+
+    cell.element.set("dirty", "0")
+
+    table.set_cell_text(0, 0, "Again")
+
+    assert table.cell(0, 0).element.get("dirty") == "1"
 
 
 def test_table_merge_cells_updates_spans_and_structure() -> None:
@@ -358,6 +383,74 @@ def test_table_merge_cells_rejects_partial_overlap() -> None:
         table.merge_cells(0, 1, 1, 1)
 
 
+def test_table_iter_grid_reports_merged_cells() -> None:
+    section_element = ET.Element(f"{HS}sec")
+    section = HwpxOxmlSection("section0.xml", section_element)
+    manifest = ET.Element("manifest")
+    root = HwpxOxmlDocument(manifest, [section], [])
+    document = HwpxDocument(cast(HwpxPackage, object()), root)
+
+    table = document.add_table(2, 2, section=section)
+    table.merge_cells(0, 0, 0, 1)
+
+    entries = list(table.iter_grid())
+    assert len(entries) == 4
+    mapping = {(entry.row, entry.column): entry for entry in entries}
+    top_left = mapping[(0, 0)]
+    right = mapping[(0, 1)]
+
+    assert top_left.is_anchor is True
+    assert top_left.row_span == 1
+    assert top_left.col_span == 2
+    assert right.is_anchor is False
+    assert right.cell.element is top_left.cell.element
+    assert right.row_span == top_left.row_span
+    assert right.col_span == top_left.col_span
+
+    cell_map = table.get_cell_map()
+    assert cell_map[0][1].cell.element is top_left.cell.element
+
+
+def test_table_logical_editing_can_split_merged_cells() -> None:
+    section_element = ET.Element(f"{HS}sec")
+    section = HwpxOxmlSection("section0.xml", section_element)
+    manifest = ET.Element("manifest")
+    root = HwpxOxmlDocument(manifest, [section], [])
+    document = HwpxDocument(cast(HwpxPackage, object()), root)
+
+    table = document.add_table(2, 2, section=section)
+    table.merge_cells(0, 0, 0, 1)
+
+    table.set_cell_text(0, 1, "Shared", logical=True)
+    assert table.cell(0, 0).text == "Shared"
+    assert table.cell(0, 1).element is table.cell(0, 0).element
+
+    table.set_cell_text(0, 1, "Right", logical=True, split_merged=True)
+
+    left_cell = table.cell(0, 0)
+    right_cell = table.cell(0, 1)
+
+    assert left_cell.element is not right_cell.element
+    assert left_cell.text == "Shared"
+    assert right_cell.text == "Right"
+    assert right_cell.span == (1, 1)
+
+
+def test_table_cell_out_of_bounds_error_mentions_bounds() -> None:
+    section_element = ET.Element(f"{HS}sec")
+    section = HwpxOxmlSection("section0.xml", section_element)
+    manifest = ET.Element("manifest")
+    root = HwpxOxmlDocument(manifest, [section], [])
+    document = HwpxDocument(cast(HwpxPackage, object()), root)
+
+    table = document.add_table(1, 1, section=section)
+
+    with pytest.raises(IndexError) as excinfo:
+        table.cell(5, 0)
+
+    assert "exceed table bounds" in str(excinfo.value)
+
+
 def test_paragraph_tables_property_returns_wrappers() -> None:
     section, paragraph = _build_section_with_paragraph()