licos-dev-sdk 0.4.2__tar.gz → 0.4.3__tar.gz

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/DOCX.md

@@ -1,20 +1,22 @@
-# Word SDK / CLI 0.4.2
+# Word SDK / CLI 0.4.3
 
 Cloud document execution stays in `licos-dev-sdk` and `licos-dev`. CLI commands
 only parse arguments and call the SDK; no additional Agent-native Word tools are
 registered. Existing `docx`, `docx-template`, `docx-read`, `docx-edit` commands and
 their Python APIs retain their invocation contracts.
 
+Use `licos-dev --version` to query the installed document CLI version.
+
 | CLI command | SDK function | Input |
 | --- | --- | --- |
-| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs, page |
+| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs/tables, page |
 | `docx-target` | `read_docx_target` | File, exact target, text cursor |
 | `docx-replace` | `replace_docx_text` | Source/output, revision, target, search/replacement |
 | `docx-delete-blocks` | `delete_docx_blocks` | Source/output, revision, inclusive block range |
 | `docx-edit-structure` | `edit_docx_structure` | Source/output, revision, small operations array |
 | `docx-table-set` | `set_docx_cell` | Source/output, revision, table/row/column, text |
 | `docx-table-insert-rows` | `insert_docx_rows` | Source/output, revision, table, insertion point, template row, rows |
-| `docx-verify` | `verify_docx` | File, optional positional assertions |
+| `docx-verify` | `verify_docx` | File, optional positional assertions and original document |
 
 ## Contract
 
@@ -28,7 +30,7 @@ their Python APIs retain their invocation contracts.
   next batch uses the output and its returned revision.
 - Batch structure operations contain only `replace_text` with `target/search/replace`
   or `delete_blocks` with `from/to`. All targets refer to the input snapshot.
-  Invalid, missing, duplicate or removed targets fail before publishing output.
+  Invalid, missing or removed targets and ambiguous matches fail before publishing output.
 - `docx-replace` expects one exact match within one paragraph in the selected
   target. It supports text split across runs and preserves surrounding formatting.
   `--replace-file` carries long replacement text; simple replacements need no JSON.
@@ -36,6 +38,9 @@ their Python APIs retain their invocation contracts.
   `[["pump","set",2],["valve",null,3]]`. Row count is derived; each merged physical
   cell is filled once. Row/cell/paragraph/run styles come from `--template-row`.
   Templates that intersect vertical merges are rejected explicitly.
+  Choose exactly one of `--before N` (`before=N`) or `--append` (`append=True`).
+  Explicit append uses the current revision's row count. Table structure items
+  include `table`, `row_count`, `column_count` and a usable body block target.
 - New editing commands default to refusing an existing output, including the
   source itself. `--overwrite` explicitly allows replacement. Body edits are
   atomic and keep all other ZIP part payloads unchanged. Existing `docx-edit`
@@ -43,9 +48,17 @@ their Python APIs retain their invocation contracts.
 - Structure previews set `content_truncated`; `docx-target` retrieves exact text
   without stripping whitespace and provides `next_text_offset` until `has_more=false`.
   No partial JSON repair or automatic argument completion is performed.
-- Verification without assertions checks structure only: `content_verified=false`.
+- Verification without assertions does not certify content: `content_verified=false`.
   Positional assertions use `equals`, `contains` or `absent`. A mismatch produces
   `verified=false` and CLI exit code 2. Layout and page breaks require visual review.
+  One CLI assertion can use a target with `--text` or `--text-file` and optional
+  `--mode`; use `--input` for multiple assertions, never both input forms.
+- `verify_docx(..., original=...)` / `docx-verify --original` compares every ZIP
+  part payload except `word/document.xml`, plus ordered section settings in the
+  body. It reports changed/added/missing parts and `preservation_verified`; a
+  failed comparison also sets `verified=false` / exit 2. The original must be a
+  separate unmodified file. This does not certify all body run formatting or
+  rendered layout, and does not substitute for positional content assertions.
 
 ## Verification
 

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.4.2
+Version: 0.4.3
 Summary: LICOS Dev SDK - file generation and model capability clients
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.4.2"
+version = "0.4.3"
 description = "LICOS Dev SDK - file generation and model capability clients"
 requires-python = ">=3.10"
 dependencies = [

licos_dev_sdk-0.4.3/src/licos_dev_sdk/document_docx_preservation.py

@@ -0,0 +1,27 @@
+"""Compare untouched DOCX parts and section settings against an original file."""
+
+from docx.oxml.ns import qn
+from lxml import etree
+
+from .document_docx_package import DOCUMENT_XML, DocxPackage
+
+
+def compare_docx_preservation(current: DocxPackage, original: DocxPackage) -> dict:
+    if current.path.samefile(original.path):
+        raise ValueError("original must be a separate, unmodified document")
+    before = {info.filename: data for info, data in original.parts if info.filename != DOCUMENT_XML}
+    after = {info.filename: data for info, data in current.parts if info.filename != DOCUMENT_XML}
+    missing = sorted(before.keys() - after.keys())
+    added = sorted(after.keys() - before.keys())
+    changed = sorted(name for name in before.keys() & after.keys() if before[name] != after[name])
+
+    def sections(package):
+        return [etree.tostring(node, method="c14n", exclusive=True)
+                for node in package.root.iter(qn("w:sectPr"))]
+
+    sections_unchanged = sections(current) == sections(original)
+    return {"original": str(original.path), "compared_parts": len(before),
+            "excluded_parts": [DOCUMENT_XML], "missing_parts": missing,
+            "added_parts": added, "changed_parts": changed,
+            "section_properties_unchanged": sections_unchanged,
+            "verified": not (missing or added or changed) and sections_unchanged}

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/src/licos_dev_sdk/document_docx_structure.py

@@ -10,6 +10,7 @@ from docx.oxml.ns import qn
 from lxml import etree
 
 from .document_docx_package import DocxPackage
+from .document_docx_preservation import compare_docx_preservation
 from .document_docx_table import parse_table
 
 TEXT_TAGS = {qn("w:t"): None, qn("w:tab"): "\t", qn("w:br"): "\n", qn("w:cr"): "\n"}
@@ -69,16 +70,23 @@ def read_docx_structure(source: str | Path, *, scope: str = "blocks", offset: in
     _index(offset, "offset")
     _index(limit, "limit")
     _index(max_chars, "max_chars")
-    if scope not in {"blocks", "paragraphs"}:
-        raise ValueError("scope must be blocks or paragraphs")
+    if scope not in {"blocks", "paragraphs", "tables"}:
+        raise ValueError("scope must be blocks, paragraphs or tables")
     package = DocxPackage(source)
     structure = _Structure(package.root)
-    elements = structure.blocks if scope == "blocks" else structure.paragraphs
+    elements = {"blocks": structure.blocks, "paragraphs": structure.paragraphs, "tables": structure.tables}[scope]
     items = []
     for number, element in enumerate(elements[offset - 1:offset - 1 + limit], offset):
         text = _text(element)
-        items.append({"target": {scope[:-1]: number}, "type": etree.QName(element).localname,
-                      "text": text[:max_chars], "content_truncated": len(text) > max_chars})
+        item = {"target": {"paragraph" if scope == "paragraphs" else "block":
+                           number if scope != "tables" else structure.blocks.index(element) + 1},
+                "type": etree.QName(element).localname,
+                "text": text[:max_chars], "content_truncated": len(text) > max_chars}
+        if element.tag == qn("w:tbl"):
+            model = parse_table(element, include_nested=False)
+            item.update(table=structure.tables.index(element) + 1, row_count=len(model.rows),
+                        column_count=model.column_count)
+        items.append(item)
     next_offset = offset + len(items)
     return {"path": str(package.path), "revision": package.revision, "scope": scope,
             "coordinate_systems": {"block": "top-level body blocks; a table is one block",
@@ -193,7 +201,8 @@ def delete_docx_blocks(source: str | Path, output: str | Path, *, revision: str,
                                operations=[{"op": "delete_blocks", "from": first, "to": last}])
 
 
-def verify_docx(source: str | Path, *, expectations: list[dict] | None = None) -> dict:
+def verify_docx(source: str | Path, *, expectations: list[dict] | None = None,
+                original: str | Path | None = None) -> dict:
     """Check package structure and exact positions; absent assertions do not certify content."""
     package = DocxPackage(source)
     structure = _Structure(package.root)
@@ -214,6 +223,10 @@ def verify_docx(source: str | Path, *, expectations: list[dict] | None = None) -
         if not passed:
             mismatches.append({"index": index, "target": expectation["target"], "mode": mode, "expected": expected,
                                "actual": actual[:1000], "actual_truncated": len(actual) > 1000})
+    preservation = compare_docx_preservation(package, DocxPackage(original)) if original is not None else None
     return {"path": str(package.path), "revision": package.revision, "structure_verified": True,
-            "content_verified": bool(expectations) and not mismatches, "verified": not mismatches,
+            "content_verified": bool(expectations) and not mismatches,
+            "preservation_verified": preservation is not None and preservation["verified"],
+            "preservation": preservation,
+            "verified": not mismatches and (preservation is None or preservation["verified"]),
             "expectation_count": len(expectations), "mismatches": mismatches}

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/src/licos_dev_sdk/document_docx_table_actions.py

@@ -5,6 +5,7 @@ from pathlib import Path
 from .document_docx_edit import _apply_operation
 from .document_docx_package import DocxPackage
 from .document_docx_structure import _Structure, _index
+from .document_docx_table import parse_table
 
 
 def set_docx_cell(source: str | Path, output: str | Path, *, revision: str,
@@ -19,15 +20,27 @@ def set_docx_cell(source: str | Path, output: str | Path, *, revision: str,
 
 
 def insert_docx_rows(source: str | Path, output: str | Path, *, revision: str,
-                     table: int, before: int, rows: list[list], template_row: int,
+                     table: int, rows: list[list], template_row: int,
+                     before: int | None = None, append: bool = False,
                      overwrite: bool = False) -> dict:
-    """Clone a template row for each row of scalar values; count is derived from rows."""
-    for name, value in (("table", table), ("before", before), ("template_row", template_row)):
+    """Clone styled rows at an explicit position or append to the current table."""
+    if type(append) is not bool:
+        raise TypeError("append must be a boolean")
+    if (before is not None) == append:
+        raise ValueError("provide exactly one of before and append=True")
+    for name, value in (("table", table), ("template_row", template_row)):
         _index(value, name)
+    if before is not None:
+        _index(before, "before")
     if not isinstance(rows, list) or not 1 <= len(rows) <= 200:
         raise ValueError("rows must contain 1-200 row arrays")
     package = DocxPackage(source)
     package.require_revision(revision)
+    if append:
+        tables = _Structure(package.root).tables
+        if table > len(tables):
+            raise ValueError(f"table {table} does not exist")
+        before = len(parse_table(tables[table - 1], include_nested=False).rows) + 1
     _apply_operation(package.root, {"op": "insert_rows", "table": table, "before": before,
                                    "template_row": template_row, "count": len(rows), "rows": rows})
     return {**package.save(output, overwrite=overwrite), "inserted_rows": len(rows)}

{licos_dev_sdk-0.4.2 → licos_dev_sdk-0.4.3}/tests/test_docx_structure.py

@@ -202,3 +202,87 @@ def test_simple_cell_set_uses_revision_and_preserves_style(source, tmp_path):
     set_docx_cell(source, output, revision=rev(source), table=1, row=2, column=1, text="新值")
     assert Document(output).tables[0].cell(1, 0).text == "新值"
     assert Document(output).tables[0].cell(1, 0).paragraphs[0].runs[0].bold
+
+
+def test_table_discovery_returns_body_target_and_current_dimensions(source, tmp_path):
+    doc = Document(source)
+    doc.add_table(rows=3, cols=2)
+    doc.save(source)
+    first = read_docx_structure(source, scope="tables", limit=1)
+    item = first["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 3}, 1, 2, 3)
+    assert read_docx_structure(source)["items"][2] == item
+    second = read_docx_structure(source, scope="tables", offset=first["next_offset"], limit=1)
+    item = second["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 6}, 2, 3, 2)
+    assert not second["has_more"]
+    assert read_docx_target(source, item["target"])["text"] == item["text"]
+
+
+def test_explicit_append_uses_current_revision_and_preserves_merged_template(source, tmp_path):
+    first, second = tmp_path / "first.docx", tmp_path / "second.docx"
+    insert_docx_rows(source, first, revision=rev(source), table=1, append=True, template_row=2, rows=[["泵", "台", 2]])
+    insert_docx_rows(first, second, revision=rev(first), table=1, append=True, template_row=1, rows=[["合并尾行", 9]])
+    table = Document(second).tables[0]
+    assert len(table.rows) == 4
+    assert table.cell(2, 0).text == "泵" and table.cell(2, 0).paragraphs[0].runs[0].bold
+    assert table.cell(3, 0).text == table.cell(3, 1).text == "合并尾行"
+    assert_parts_preserved(source, second)
+    with pytest.raises(ValueError, match="revision"):
+        insert_docx_rows(first, tmp_path / "stale.docx", revision=rev(source), table=1, append=True, template_row=2, rows=[["a", "b", 1]])
+    assert not (tmp_path / "stale.docx").exists()
+
+
+@pytest.mark.parametrize("position", [{}, {"before": 3, "append": True}, {"before": True}, {"append": 1}])
+def test_insert_requires_one_explicit_position(source, tmp_path, position):
+    output = tmp_path / "bad.docx"
+    with pytest.raises((ValueError, TypeError)):
+        insert_docx_rows(source, output, revision=rev(source), table=1, template_row=2, rows=[["a", "b", 1]], **position)
+    assert not output.exists()
+
+
+def test_original_comparison_certifies_parts_and_sections_but_requires_content_assertions(source, tmp_path):
+    output = tmp_path / "edited.docx"
+    replace_docx_text(source, output, revision=rev(source), target={"block": 2}, search="123456", replacement="新账号")
+    report = verify_docx(output, original=source)
+    assert report["verified"] and report["preservation_verified"]
+    assert report["preservation"]["section_properties_unchanged"]
+    assert not report["content_verified"]
+    assert not verify_docx(output, original=source, expectations=[{"target": {"block": 2}, "text": "错误"}])["verified"]
+    with pytest.raises(ValueError, match="separate"):
+        verify_docx(output, original=output)
+
+
+@pytest.mark.parametrize("mutation,part,field", [
+    ("change", "word/header1.xml", "changed_parts"),
+    ("change", "word/styles.xml", "changed_parts"),
+    ("remove", "word/header1.xml", "missing_parts"),
+    ("add", "word/media/extra.png", "added_parts"),
+])
+def test_original_comparison_detects_changes_outside_body(source, tmp_path, mutation, part, field):
+    output = tmp_path / "changed.docx"
+    with ZipFile(source) as before, ZipFile(output, "w") as after:
+        for info in before.infolist():
+            if mutation == "remove" and info.filename == part:
+                continue
+            data = before.read(info.filename)
+            after.writestr(info, data + b" " if mutation == "change" and info.filename == part else data)
+        if mutation == "add":
+            after.writestr(part, b"image")
+    report = verify_docx(output, original=source)
+    assert not report["verified"] and not report["preservation_verified"]
+    assert report["preservation"][field] == [part]
+
+
+def test_original_comparison_detects_section_layout_changes(source, tmp_path):
+    from licos_dev_sdk.document_docx_package import DocxPackage
+
+    package = DocxPackage(source)
+    section = next(package.root.iter(qn("w:sectPr")))
+    section.find(qn("w:pgMar")).set(qn("w:left"), "999")
+    output = tmp_path / "layout.docx"
+    package.save(output)
+    report = verify_docx(output, original=source)
+    assert not report["verified"]
+    assert not report["preservation"]["section_properties_unchanged"]
+    assert report["preservation"]["changed_parts"] == []

licos_dev_sdk-0.4.3/tests/test_html_docx_features.py

@@ -0,0 +1,46 @@
+"""Exercise the public HTML-to-Word API with actual document parts and images."""
+
+import base64
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml.ns import qn
+from PIL import Image
+
+from licos_dev_sdk import create_docx
+
+
+def test_html_generates_native_toc_merged_table_and_embedded_images(tmp_path):
+    picture = tmp_path / "figure.png"
+    Image.new("RGB", (80, 40), "#145DA0").save(picture)
+    encoded = base64.b64encode(picture.read_bytes()).decode("ascii")
+    html = f'''<html><head><style>
+      th {{ background-color: #145DA0; color: #ffffff; }}
+      td {{ border: 1px solid #333333; }}
+    </style></head><body>
+      <h1>测试报告</h1><h2>设备统计</h2><h3>设备清单</h3>
+      <table><tr><th colspan="2">设备</th><th>数量</th></tr>
+        <tr><td rowspan="2">泵组</td><td>离心泵</td><td>2</td></tr>
+        <tr><td>阀门</td><td>3</td></tr></table>
+      <p><img src="figure.png" width="160" alt="本地图片"></p>
+      <p><img src="data:image/png;base64,{encoded}" width="160" alt="内嵌图片"></p>
+    </body></html>'''
+    output = create_docx(html, "report", content_type="html", output_dir=str(tmp_path),
+                         asset_base_path=str(tmp_path), include_toc=True, header="内部资料", footer="测试页脚")
+    document = Document(output)
+    assert [p.text for p in document.paragraphs if p.style.name.startswith("Heading")] == ["测试报告", "设备统计", "设备清单"]
+    fields = [n.text for n in document.element.iter(qn("w:instrText"))]
+    assert any('TOC \\o "1-3"' in text for text in fields)
+    assert document.settings.element.find(qn("w:updateFields")).get(qn("w:val")) == "true"
+    table = document.tables[0]
+    assert len(table.rows) == 3 and len(table.columns) == 3
+    assert table.cell(0, 0)._tc is table.cell(0, 1)._tc
+    assert table.cell(1, 0)._tc is table.cell(2, 0)._tc
+    assert table.cell(2, 1).text == "阀门" and table.cell(2, 2).text == "3"
+    assert 'w:fill="145DA0"' in table.cell(0, 0)._tc.xml
+    assert len(document.inline_shapes) == 2
+    assert "内部资料" in document.sections[0].header.paragraphs[0].text
+    assert "测试页脚" in document.sections[0].footer.paragraphs[0].text
+    with ZipFile(output) as archive:
+        images = [archive.read(name) for name in archive.namelist() if name.startswith("word/media/")]
+    assert picture.read_bytes() in images