licos-dev-sdk 0.3.9__tar.gz → 0.4.0__tar.gz

{licos_dev_sdk-0.3.9 → licos_dev_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.3.9
+Version: 0.4.0
 Summary: LICOS Dev SDK - file generation and model capability clients
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12
@@ -8,7 +8,6 @@ Requires-Dist: docxtpl>=0.16
 Requires-Dist: graphviz>=0.20
 Requires-Dist: jinja2>=3.1
 Requires-Dist: licos-platform-sdk>=0.3.2
-Requires-Dist: licos-ppt-master-assets==0.0.1
 Requires-Dist: matplotlib>=3.9
 Requires-Dist: mistune>=3.0
 Requires-Dist: openpyxl>=3.1
@@ -23,3 +22,5 @@ Requires-Dist: skia-pathops>=0.9.2
 Requires-Dist: uharfbuzz>=0.50.0
 Requires-Dist: weasyprint>=62.0
 Requires-Dist: xlsxwriter>=3.2
+Provides-Extra: ppt-master
+Requires-Dist: licos-ppt-master-assets==0.0.1; extra == 'ppt-master'

{licos_dev_sdk-0.3.9 → licos_dev_sdk-0.4.0}/pyproject.toml

@@ -4,11 +4,10 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.3.9"
+version = "0.4.0"
 description = "LICOS Dev SDK - file generation and model capability clients"
 requires-python = ">=3.10"
 dependencies = [
-    "licos-ppt-master-assets==0.0.1",
     "licos-platform-sdk>=0.3.2",
     "weasyprint>=62.0",
     "python-docx>=1.1",
@@ -30,5 +29,10 @@ dependencies = [
     "PyYAML>=6.0",
 ]
 
+[project.optional-dependencies]
+ppt-master = [
+    "licos-ppt-master-assets==0.0.1",
+]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/licos_dev_sdk"]

{licos_dev_sdk-0.3.9 → licos_dev_sdk-0.4.0}/src/licos_dev_sdk/__init__.py

@@ -28,13 +28,17 @@ def __getattr__(name: str):
         "inspect_pdf": ("pdf_inspect", "inspect_pdf"),
         "create_docx": ("document", "create_docx"),
         "create_docx_from_template": ("document", "create_docx_from_template"),
+        "edit_docx": ("document", "edit_docx"),
         "read_pdf": ("document_read", "read_pdf"),
         "read_docx": ("document_read", "read_docx"),
         "read_xlsx": ("document_read", "read_xlsx"),
         "read_pptx": ("document_read", "read_pptx"),
         # spreadsheet
         "create_xlsx": ("spreadsheet", "create_xlsx"),
+        "create_xlsx_from_docx": ("spreadsheet", "create_xlsx_from_docx"),
+        "create_xlsx_from_html": ("spreadsheet", "create_xlsx_from_html"),
         "create_xlsx_workbook": ("spreadsheet", "create_xlsx_workbook"),
+        "edit_xlsx": ("spreadsheet", "edit_xlsx"),
         "create_csv": ("spreadsheet", "create_csv"),
         "inspect_xlsx": ("spreadsheet_inspect", "inspect_xlsx"),
         # chart
@@ -100,9 +104,9 @@ __all__ = [
     "create_zip", "create_tar_gz",
     "create_qrcode", "create_barcode", "create_watermark",
     "create_html", "create_markdown", "markdown_to_html",
-    "create_pdf", "inspect_pdf", "create_docx", "create_docx_from_template",
+    "create_pdf", "inspect_pdf", "create_docx", "create_docx_from_template", "edit_docx",
     "read_pdf", "read_docx", "read_xlsx", "read_pptx",
-    "create_xlsx", "create_xlsx_workbook", "create_csv", "inspect_xlsx",
+    "create_xlsx", "create_xlsx_from_docx", "create_xlsx_from_html", "create_xlsx_workbook", "edit_xlsx", "create_csv", "inspect_xlsx",
     "create_chart",
     "create_diagram",
     "create_pptx", "create_pptx_deck", "inspect_pptx",

{licos_dev_sdk-0.3.9 → licos_dev_sdk-0.4.0}/src/licos_dev_sdk/document.py

@@ -72,3 +72,18 @@ def create_docx_from_template(template_path: str, data: dict[str, Any], filename
     doc.render(data)
     doc.save(str(path))
     return str(path.resolve())
+
+
+def edit_docx(
+    source_path: str,
+    operations: list[dict[str, Any]],
+    filename: str,
+    *,
+    output_dir: str | None = None,
+) -> str:
+    """Apply explicit table edits to an existing DOCX file."""
+
+    from .document_docx_edit import edit_docx_tables
+
+    path = resolve_output_path(filename, ".docx", output_dir)
+    return edit_docx_tables(source_path, path, operations)

licos_dev_sdk-0.4.0/src/licos_dev_sdk/document_docx_edit.py

@@ -0,0 +1,561 @@
+"""Targeted edits for native DOCX tables while preserving the package."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+import os
+import re
+import tempfile
+from typing import Any
+from zipfile import ZIP_DEFLATED, ZipFile
+
+from docx.oxml.ns import qn
+from lxml import etree
+
+from .document_docx_table import TableCell, TableModel, parse_table
+
+
+_DOCUMENT_XML = "word/document.xml"
+_HEX_COLOR = re.compile(r"^[0-9A-Fa-f]{6}$")
+
+
+def edit_docx_tables(
+    source: str | Path,
+    output: str | Path,
+    operations: list[dict[str, Any]],
+) -> str:
+    """Apply explicit table operations to a DOCX package."""
+
+    source_path = Path(source).expanduser().resolve()
+    output_path = Path(output).expanduser().resolve()
+    if not source_path.is_file():
+        raise FileNotFoundError(f"document not found: {source_path}")
+    if source_path.suffix.lower() != ".docx":
+        raise ValueError(f"expected a .docx file, got {source_path.suffix.lower() or '<none>'}")
+    if not isinstance(operations, list) or not operations:
+        raise ValueError("operations must be a non-empty array")
+    if not all(isinstance(operation, dict) for operation in operations):
+        raise TypeError("every DOCX edit operation must be an object")
+
+    with ZipFile(source_path, "r") as archive:
+        if _DOCUMENT_XML not in archive.namelist():
+            raise ValueError("DOCX package does not contain word/document.xml")
+        root = etree.fromstring(archive.read(_DOCUMENT_XML))
+        for operation_number, operation in enumerate(operations, start=1):
+            try:
+                _apply_operation(root, operation)
+            except (KeyError, TypeError, ValueError) as exc:
+                name = operation.get("op", "<missing>")
+                raise ValueError(
+                    f"DOCX operation {operation_number} ({name}) failed: {exc}"
+                ) from exc
+
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        handle, temporary_name = tempfile.mkstemp(
+            prefix=f".{output_path.stem}-",
+            suffix=".docx",
+            dir=output_path.parent,
+        )
+        os.close(handle)
+        temporary_path = Path(temporary_name)
+        try:
+            with ZipFile(temporary_path, "w", ZIP_DEFLATED) as destination:
+                for info in archive.infolist():
+                    payload = archive.read(info.filename)
+                    if info.filename == _DOCUMENT_XML:
+                        payload = etree.tostring(
+                            root,
+                            xml_declaration=True,
+                            encoding="UTF-8",
+                            standalone=True,
+                        )
+                    destination.writestr(info, payload)
+            os.replace(temporary_path, output_path)
+        finally:
+            temporary_path.unlink(missing_ok=True)
+    return str(output_path)
+
+
+def _apply_operation(root: Any, operation: dict[str, Any]) -> None:
+    name = str(_required(operation, "op")).strip().lower()
+    table_element = _table(root, _positive(operation, "table"))
+    model = parse_table(table_element, include_nested=False)
+
+    if name == "set_cell":
+        cell = _cell(model, operation)
+        _set_cell_content(cell.element, operation)
+    elif name == "set_cell_style":
+        _apply_cell_style(_cell(model, operation).element, _style(operation))
+    elif name == "set_row_style":
+        row = _row(model, _positive(operation, "row"))
+        _apply_row_style(row.element, _style(operation))
+    elif name == "set_column_width":
+        _set_column_width(
+            table_element,
+            model,
+            _positive(operation, "column"),
+            _positive(operation, "width_twips"),
+        )
+    elif name == "merge_cells":
+        _merge_cells(table_element, model, operation)
+    elif name == "unmerge_cells":
+        _unmerge_cells(table_element, model, operation)
+    elif name == "insert_rows":
+        _insert_rows(table_element, model, operation)
+    elif name == "delete_rows":
+        _delete_rows(table_element, model, operation)
+    elif name == "insert_columns":
+        _insert_columns(table_element, model, operation)
+    elif name == "delete_columns":
+        _delete_columns(table_element, model, operation)
+    else:
+        raise ValueError(f"unsupported operation: {name!r}")
+
+
+def _table(root: Any, table_number: int) -> Any:
+    body = root.find(qn("w:body"))
+    tables = list(body.iterchildren(tag=qn("w:tbl"))) if body is not None else []
+    if table_number > len(tables):
+        raise ValueError(f"table {table_number} not found; document has {len(tables)} top-level tables")
+    return tables[table_number - 1]
+
+
+def _cell(model: TableModel, operation: dict[str, Any]) -> TableCell:
+    row = _positive(operation, "row")
+    column = _positive(operation, "column")
+    cell = model.cell_at(row, column)
+    if cell is None:
+        raise ValueError(f"cell at row {row}, column {column} does not exist")
+    return cell
+
+
+def _row(model: TableModel, number: int):
+    if number > len(model.rows):
+        raise ValueError(f"row {number} not found; table has {len(model.rows)} rows")
+    return model.rows[number - 1]
+
+
+def _set_cell_content(cell_element: Any, operation: dict[str, Any]) -> None:
+    raw_paragraphs = operation.get("paragraphs")
+    if raw_paragraphs is None:
+        text = operation.get("value", operation.get("text"))
+        if text is None:
+            raise ValueError("set_cell requires value, text, or paragraphs")
+        raw_paragraphs = str(text).splitlines() or [""]
+    if not isinstance(raw_paragraphs, list):
+        raise TypeError("paragraphs must be an array")
+
+    existing_paragraph = cell_element.find(qn("w:p"))
+    paragraph_properties = None
+    run_properties = None
+    if existing_paragraph is not None:
+        p_pr = existing_paragraph.find(qn("w:pPr"))
+        paragraph_properties = deepcopy(p_pr) if p_pr is not None else None
+        existing_run = existing_paragraph.find(qn("w:r"))
+        if existing_run is not None:
+            r_pr = existing_run.find(qn("w:rPr"))
+            run_properties = deepcopy(r_pr) if r_pr is not None else None
+
+    for child in list(cell_element):
+        if child.tag != qn("w:tcPr"):
+            cell_element.remove(child)
+    for raw in raw_paragraphs or [""]:
+        paragraph_spec = raw if isinstance(raw, dict) else {"text": str(raw)}
+        paragraph = etree.Element(qn("w:p"))
+        if paragraph_properties is not None:
+            paragraph.append(deepcopy(paragraph_properties))
+        run = etree.SubElement(paragraph, qn("w:r"))
+        if run_properties is not None:
+            run.append(deepcopy(run_properties))
+        _append_text(run, str(paragraph_spec.get("text", "")))
+        cell_element.append(paragraph)
+    if isinstance(operation.get("style"), dict):
+        _apply_cell_style(cell_element, operation["style"])
+
+
+def _append_text(run: Any, text: str) -> None:
+    segments = text.split("\n")
+    for index, segment in enumerate(segments):
+        if index:
+            etree.SubElement(run, qn("w:br"))
+        text_element = etree.SubElement(run, qn("w:t"))
+        if segment[:1].isspace() or segment[-1:].isspace():
+            text_element.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+        text_element.text = segment
+
+
+def _apply_cell_style(cell_element: Any, style: dict[str, Any]) -> None:
+    properties = _ensure_first(cell_element, "tcPr")
+    if "fill" in style:
+        fill = _color(style["fill"])
+        shading = _ensure(properties, "shd")
+        shading.set(qn("w:fill"), fill)
+        shading.set(qn("w:val"), "clear")
+    if "vertical_alignment" in style:
+        value = str(style["vertical_alignment"]).lower()
+        if value not in {"top", "center", "bottom"}:
+            raise ValueError("vertical_alignment must be top, center, or bottom")
+        _ensure(properties, "vAlign").set(qn("w:val"), value)
+    if "text_direction" in style:
+        _ensure(properties, "textDirection").set(qn("w:val"), str(style["text_direction"]))
+    if "width_twips" in style:
+        width = _positive_value(style["width_twips"], "width_twips")
+        target = _ensure(properties, "tcW")
+        target.set(qn("w:w"), str(width))
+        target.set(qn("w:type"), "dxa")
+    if "margins" in style:
+        margins = style["margins"]
+        if not isinstance(margins, dict):
+            raise TypeError("margins must be an object")
+        container = _ensure(properties, "tcMar")
+        for side, raw in margins.items():
+            if side not in {"top", "left", "bottom", "right", "start", "end"}:
+                raise ValueError(f"unsupported cell margin side: {side}")
+            target = _ensure(container, side)
+            target.set(qn("w:w"), str(_non_negative(raw, f"margins.{side}")))
+            target.set(qn("w:type"), "dxa")
+    if "borders" in style:
+        borders = style["borders"]
+        if not isinstance(borders, dict):
+            raise TypeError("borders must be an object")
+        container = _ensure(properties, "tcBorders")
+        for side, spec in borders.items():
+            if side not in {"top", "left", "bottom", "right", "insideH", "insideV"}:
+                raise ValueError(f"unsupported border side: {side}")
+            if not isinstance(spec, dict):
+                raise TypeError(f"border {side} must be an object")
+            target = _ensure(container, side)
+            target.set(qn("w:val"), str(spec.get("style", "single")))
+            if "size" in spec:
+                target.set(qn("w:sz"), str(_positive_value(spec["size"], f"borders.{side}.size")))
+            if "color" in spec:
+                target.set(qn("w:color"), _color(spec["color"]))
+
+
+def _apply_row_style(row_element: Any, style: dict[str, Any]) -> None:
+    properties = _ensure_first(row_element, "trPr")
+    for key, tag in (("repeat_header", "tblHeader"), ("cant_split", "cantSplit")):
+        if key in style:
+            _toggle(properties, tag, bool(style[key]))
+    if "height_twips" in style:
+        height = _ensure(properties, "trHeight")
+        height.set(qn("w:val"), str(_positive_value(style["height_twips"], "height_twips")))
+        rule = str(style.get("height_rule", "atLeast"))
+        if rule not in {"atLeast", "exact", "auto"}:
+            raise ValueError("height_rule must be atLeast, exact, or auto")
+        height.set(qn("w:hRule"), rule)
+
+
+def _set_column_width(table: Any, model: TableModel, column: int, width: int) -> None:
+    if column > model.column_count:
+        raise ValueError(f"column {column} exceeds table width {model.column_count}")
+    grid = table.find(qn("w:tblGrid"))
+    columns = list(grid.iterchildren(tag=qn("w:gridCol"))) if grid is not None else []
+    if len(columns) < model.column_count:
+        raise ValueError("table does not contain a complete tblGrid; column width cannot be edited safely")
+    columns[column - 1].set(qn("w:w"), str(width))
+    seen: set[int] = set()
+    for row in model.rows:
+        cell = model.cell_at(row.number, column)
+        if cell is None or id(cell.element) in seen or cell.col_span != 1:
+            continue
+        seen.add(id(cell.element))
+        properties = _ensure_first(cell.element, "tcPr")
+        target = _ensure(properties, "tcW")
+        target.set(qn("w:w"), str(width))
+        target.set(qn("w:type"), "dxa")
+
+
+def _merge_cells(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    first_row, first_col, last_row, last_col = _range(operation, model)
+    selected: dict[tuple[int, int], TableCell] = {}
+    for row in range(first_row, last_row + 1):
+        for column in range(first_col, last_col + 1):
+            cell = model.cell_at(row, column)
+            if cell is None or cell.row_span != 1 or cell.col_span != 1:
+                raise ValueError("merge_cells requires existing unmerged cells across the complete range")
+            selected[(row, column)] = cell
+
+    width = last_col - first_col + 1
+    for row in range(first_row, last_row + 1):
+        left = selected[(row, first_col)].element
+        properties = _ensure_first(left, "tcPr")
+        if width > 1:
+            _ensure(properties, "gridSpan").set(qn("w:val"), str(width))
+        if last_row > first_row:
+            _ensure(properties, "vMerge").set(
+                qn("w:val"), "restart" if row == first_row else "continue"
+            )
+        if row > first_row:
+            _set_cell_content(left, {"text": ""})
+        row_element = selected[(row, first_col)].element.getparent()
+        for column in range(first_col + 1, last_col + 1):
+            row_element.remove(selected[(row, column)].element)
+
+
+def _unmerge_cells(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    anchor = _cell(model, operation)
+    if anchor.row_span == 1 and anchor.col_span == 1:
+        raise ValueError("target cell is not merged")
+    width = anchor.col_span
+    for row_number in range(anchor.row, anchor.row + anchor.row_span):
+        physical = _physical_cell_at(_row(model, row_number).element, anchor.column)
+        if physical is None:
+            raise ValueError(f"cannot locate merged cell continuation at row {row_number}")
+        cell_element, _, _ = physical
+        properties = _ensure_first(cell_element, "tcPr")
+        _remove(properties, "gridSpan")
+        _remove(properties, "vMerge")
+        if row_number > anchor.row:
+            _set_cell_content(cell_element, {"text": ""})
+        insertion_index = cell_element.getparent().index(cell_element) + 1
+        for _ in range(width - 1):
+            cell_element.getparent().insert(insertion_index, _blank_cell())
+            insertion_index += 1
+
+
+def _insert_rows(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    before = _positive(operation, "before")
+    count = _positive(operation, "count", default=1)
+    if before > len(model.rows) + 1:
+        raise ValueError(f"before must be between 1 and {len(model.rows) + 1}")
+    for row in model.rows:
+        for cell in row.cells:
+            if cell.row < before < cell.row + cell.row_span:
+                raise ValueError("cannot insert a row through an existing vertical merge")
+    values = operation.get("rows", [])
+    if values and (not isinstance(values, list) or len(values) != count):
+        raise ValueError("rows must contain exactly count row arrays")
+    reference = model.rows[before - 1].element if before <= len(model.rows) else None
+    for index in range(count):
+        row_values = values[index] if values else []
+        if not isinstance(row_values, list):
+            raise TypeError("each inserted row must be an array")
+        row_element = _blank_row(model.column_count, row_values)
+        if reference is None:
+            table.append(row_element)
+        else:
+            table.insert(table.index(reference), row_element)
+
+
+def _delete_rows(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    start = _positive(operation, "row")
+    count = _positive(operation, "count", default=1)
+    end = start + count - 1
+    if end > len(model.rows):
+        raise ValueError(f"row range {start}:{end} exceeds table height {len(model.rows)}")
+    for row in model.rows:
+        for cell in row.cells:
+            cell_end = cell.row + cell.row_span - 1
+            overlaps = cell.row <= end and cell_end >= start
+            contained = cell.row >= start and cell_end <= end
+            if overlaps and not contained:
+                raise ValueError("cannot partially delete an existing vertical merge")
+    for number in range(end, start - 1, -1):
+        table.remove(model.rows[number - 1].element)
+
+
+def _insert_columns(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    before = _positive(operation, "before")
+    count = _positive(operation, "count", default=1)
+    if before > model.column_count + 1:
+        raise ValueError(f"before must be between 1 and {model.column_count + 1}")
+    _require_regular_row_offsets(model)
+    for row in model.rows:
+        for cell in row.cells:
+            if cell.column < before < cell.column + cell.col_span:
+                raise ValueError("cannot insert a column through an existing horizontal merge")
+    grid = _complete_grid(table, model)
+    reference_width = grid[min(before - 1, len(grid) - 1)].get(qn("w:w")) or "2400"
+    grid_parent = grid[0].getparent()
+    grid_index = grid_parent.index(grid[before - 1]) if before <= len(grid) else len(grid_parent)
+    for _ in range(count):
+        column = etree.Element(qn("w:gridCol"))
+        column.set(qn("w:w"), reference_width)
+        grid_parent.insert(grid_index, column)
+        grid_index += 1
+    for row in model.rows:
+        entries = _physical_cells(row.element)
+        insertion_index = len(row.element)
+        for cell_element, start, _ in entries:
+            if start >= before:
+                insertion_index = row.element.index(cell_element)
+                break
+        for _ in range(count):
+            row.element.insert(insertion_index, _blank_cell(reference_width))
+            insertion_index += 1
+
+
+def _delete_columns(table: Any, model: TableModel, operation: dict[str, Any]) -> None:
+    start = _positive(operation, "column")
+    count = _positive(operation, "count", default=1)
+    end = start + count - 1
+    if end > model.column_count:
+        raise ValueError(f"column range {start}:{end} exceeds table width {model.column_count}")
+    _require_regular_row_offsets(model)
+    for row in model.rows:
+        for cell in row.cells:
+            cell_end = cell.column + cell.col_span - 1
+            overlaps = cell.column <= end and cell_end >= start
+            contained = cell.column >= start and cell_end <= end
+            if overlaps and not contained:
+                raise ValueError("cannot partially delete an existing horizontal merge")
+    for row in model.rows:
+        for cell_element, column, span in reversed(_physical_cells(row.element)):
+            if column >= start and column + span - 1 <= end:
+                row.element.remove(cell_element)
+    grid = _complete_grid(table, model)
+    parent = grid[0].getparent()
+    for column in reversed(grid[start - 1 : end]):
+        parent.remove(column)
+
+
+def _range(operation: dict[str, Any], model: TableModel) -> tuple[int, int, int, int]:
+    first_row = _positive(operation, "start_row")
+    first_col = _positive(operation, "start_column")
+    last_row = _positive(operation, "end_row")
+    last_col = _positive(operation, "end_column")
+    if first_row > last_row or first_col > last_col:
+        raise ValueError("range start must be above and to the left of range end")
+    if last_row > len(model.rows) or last_col > model.column_count:
+        raise ValueError("range exceeds table bounds")
+    return first_row, first_col, last_row, last_col
+
+
+def _physical_cells(row_element: Any) -> list[tuple[Any, int, int]]:
+    properties = row_element.find(qn("w:trPr"))
+    column = _integer_child(properties, "gridBefore", 0) + 1
+    result = []
+    for cell in row_element.iterchildren(tag=qn("w:tc")):
+        span = max(_integer_child(cell.find(qn("w:tcPr")), "gridSpan", 1), 1)
+        result.append((cell, column, span))
+        column += span
+    return result
+
+
+def _physical_cell_at(row_element: Any, column: int) -> tuple[Any, int, int] | None:
+    for entry in _physical_cells(row_element):
+        if entry[1] <= column < entry[1] + entry[2]:
+            return entry
+    return None
+
+
+def _blank_row(columns: int, values: list[Any]) -> Any:
+    row = etree.Element(qn("w:tr"))
+    for column in range(columns):
+        cell = _blank_cell()
+        _set_cell_content(cell, {"value": values[column] if column < len(values) else ""})
+        row.append(cell)
+    return row
+
+
+def _blank_cell(width: str | None = None) -> Any:
+    cell = etree.Element(qn("w:tc"))
+    properties = etree.SubElement(cell, qn("w:tcPr"))
+    if width:
+        target = etree.SubElement(properties, qn("w:tcW"))
+        target.set(qn("w:w"), str(width))
+        target.set(qn("w:type"), "dxa")
+    paragraph = etree.SubElement(cell, qn("w:p"))
+    etree.SubElement(paragraph, qn("w:r"))
+    return cell
+
+
+def _complete_grid(table: Any, model: TableModel) -> list[Any]:
+    grid = table.find(qn("w:tblGrid"))
+    columns = list(grid.iterchildren(tag=qn("w:gridCol"))) if grid is not None else []
+    if len(columns) != model.column_count:
+        raise ValueError("column operation requires a complete tblGrid")
+    return columns
+
+
+def _require_regular_row_offsets(model: TableModel) -> None:
+    for row in model.rows:
+        properties = row.element.find(qn("w:trPr"))
+        if _integer_child(properties, "gridBefore", 0) or _integer_child(properties, "gridAfter", 0):
+            raise ValueError("column operation is not supported on rows with gridBefore/gridAfter")
+
+
+def _integer_child(parent: Any, name: str, default: int) -> int:
+    child = parent.find(qn(f"w:{name}")) if parent is not None else None
+    try:
+        return int(child.get(qn("w:val"))) if child is not None else default
+    except (TypeError, ValueError):
+        return default
+
+
+def _ensure_first(parent: Any, name: str) -> Any:
+    child = parent.find(qn(f"w:{name}"))
+    if child is None:
+        child = etree.Element(qn(f"w:{name}"))
+        parent.insert(0, child)
+    return child
+
+
+def _ensure(parent: Any, name: str) -> Any:
+    child = parent.find(qn(f"w:{name}"))
+    if child is None:
+        child = etree.SubElement(parent, qn(f"w:{name}"))
+    return child
+
+
+def _remove(parent: Any, name: str) -> None:
+    child = parent.find(qn(f"w:{name}"))
+    if child is not None:
+        parent.remove(child)
+
+
+def _toggle(parent: Any, name: str, enabled: bool) -> None:
+    child = parent.find(qn(f"w:{name}"))
+    if enabled and child is None:
+        etree.SubElement(parent, qn(f"w:{name}"))
+    elif not enabled and child is not None:
+        parent.remove(child)
+
+
+def _style(operation: dict[str, Any]) -> dict[str, Any]:
+    style = operation.get("style")
+    if not isinstance(style, dict):
+        raise TypeError("style must be an object")
+    return style
+
+
+def _required(value: dict[str, Any], key: str) -> Any:
+    if key not in value:
+        raise ValueError(f"{key} is required")
+    return value[key]
+
+
+def _positive(value: dict[str, Any], key: str, *, default: int | None = None) -> int:
+    raw = value.get(key, default)
+    if raw is None:
+        raise ValueError(f"{key} is required")
+    return _positive_value(raw, key)
+
+
+def _positive_value(raw: Any, key: str) -> int:
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{key} must be an integer") from exc
+    if value < 1:
+        raise ValueError(f"{key} must be at least 1")
+    return value
+
+
+def _non_negative(raw: Any, key: str) -> int:
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as exc:
+        raise TypeError(f"{key} must be an integer") from exc
+    if value < 0:
+        raise ValueError(f"{key} must not be negative")
+    return value
+
+
+def _color(raw: Any) -> str:
+    value = str(raw).lstrip("#")
+    if not _HEX_COLOR.fullmatch(value):
+        raise ValueError(f"invalid RGB color: {raw!r}")
+    return value.upper()