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

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

@@ -1,4 +1,4 @@
-# Word SDK / CLI 0.4.3
+# Word SDK / CLI 0.4.4
 
 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
@@ -10,6 +10,7 @@ Use `licos-dev --version` to query the installed document CLI version.
 | CLI command | SDK function | Input |
 | --- | --- | --- |
 | `docx-structure` | `read_docx_structure` | File, blocks/paragraphs/tables, page |
+| `docx-inspect` | `inspect_docx` | File, all/fields/images/tables, offset/limit |
 | `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 |
@@ -62,6 +63,19 @@ Use `licos-dev --version` to query the installed document CLI version.
 
 ## Verification
 
+`docx-inspect` reports native field instructions (including split-run TOC fields),
+field completeness, embedded/external/missing image references, and table dimensions
+across document stories, including headers and footers. Each scope has its own
+`next_offset`; counts cover the entire document. `update_fields_on_open` describes
+the Word setting; neither it nor `toc_count` certifies rendered pagination.
+Use `docx-structure` for editable body targets.
+
+Batch verification entries require `target`, exactly one of `text` or `text_file`,
+and optional `mode`. JSON `text_file` is a UTF-8 path relative to the JSON file's
+directory. Single CLI `--text-file` is relative to cwd. SDK `base_dir` defaults to
+cwd and can set the file resolution directory explicitly. Empty text is valid;
+unknown keys, conflicting inputs and file errors identify the assertion and field.
+
 Run Python tests serially with the current source on `PYTHONPATH`:
 
 ```text

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

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

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

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

{licos_dev_sdk-0.4.3 → licos_dev_sdk-0.4.4}/src/licos_dev_sdk/__init__.py

@@ -30,6 +30,7 @@ def __getattr__(name: str):
         "create_docx_from_template": ("document", "create_docx_from_template"),
         "edit_docx": ("document", "edit_docx"),
         "read_docx_structure": ("document_docx_structure", "read_docx_structure"),
+        "inspect_docx": ("document_docx_inspect", "inspect_docx"),
         "read_docx_target": ("document_docx_structure", "read_docx_target"),
         "edit_docx_structure": ("document_docx_structure", "edit_docx_structure"),
         "replace_docx_text": ("document_docx_structure", "replace_docx_text"),
@@ -108,7 +109,7 @@ def __getattr__(name: str):
 
 
 __all__ = [
-    "read_docx_structure", "read_docx_target", "edit_docx_structure",
+    "inspect_docx", "read_docx_structure", "read_docx_target", "edit_docx_structure",
     "replace_docx_text", "delete_docx_blocks", "verify_docx", "set_docx_cell", "insert_docx_rows",
     "create_json", "create_xml", "create_yaml",
     "create_zip", "create_tar_gz",

licos_dev_sdk-0.4.4/src/licos_dev_sdk/document_docx_expectations.py

@@ -0,0 +1,30 @@
+"""The shared single/batch verification assertion contract."""
+
+from pathlib import Path
+
+
+def expected_text(expectation, index, base_dir):
+    prefix = f"expectation {index}"
+    if not isinstance(expectation, dict):
+        raise ValueError(f"{prefix} must be an object")
+    unknown = set(expectation) - {"target", "text", "text_file", "mode"}
+    if unknown:
+        raise ValueError(f"{prefix}: unknown fields {', '.join(sorted(unknown))}; allowed: target, text, text_file, mode")
+    if "target" not in expectation:
+        raise ValueError(f"{prefix}.target is required")
+    if ("text" in expectation) == ("text_file" in expectation):
+        raise ValueError(f"{prefix}: provide exactly one of text and text_file")
+    field = "text_file" if "text_file" in expectation else "text"
+    value = expectation[field]
+    if not isinstance(value, str) or (field == "text_file" and not value):
+        raise ValueError(f"{prefix}.{field} must be {'a non-empty' if field == 'text_file' else 'a'} string")
+    mode = expectation.get("mode", "equals")
+    if mode not in ("equals", "contains", "absent"):
+        raise ValueError(f"{prefix}.mode must be equals, contains or absent")
+    if field == "text_file":
+        path = Path(base_dir) / Path(value).expanduser()
+        try:
+            value = path.read_text(encoding="utf-8")
+        except (OSError, UnicodeError) as exc:
+            raise ValueError(f"{prefix}.text_file: {exc}") from exc
+    return value, mode

licos_dev_sdk-0.4.4/src/licos_dev_sdk/document_docx_inspect.py

@@ -0,0 +1,90 @@
+"""Inspect native Word fields, image references and tables without modifying a package."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+import posixpath
+
+from lxml import etree
+
+from .document_docx_package import DocxPackage
+
+W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}"
+R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
+A = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+V = "{urn:schemas-microsoft-com:vml}"
+
+
+def _xml(data):
+    return etree.fromstring(data, etree.XMLParser(resolve_entities=False, no_network=True))
+
+
+def _fields(root, part):
+    fields, stack = [], []
+    for element in root.iter():
+        if element.tag == W + "fldSimple":
+            fields.append({"part": part, "instruction": element.get(W + "instr", ""), "complete": True})
+        elif element.tag == W + "fldChar":
+            kind = element.get(W + "fldCharType")
+            if kind == "begin":
+                field = {"part": part, "instruction": "", "complete": False}
+                fields.append(field)
+                stack.append((field, True))
+            elif kind == "separate" and stack:
+                stack[-1] = (stack[-1][0], False)
+            elif kind == "end" and stack:
+                stack.pop()[0]["complete"] = True
+        elif element.tag == W + "instrText" and stack and stack[-1][1]:
+            stack[-1][0]["instruction"] += element.text or ""
+    for field in fields:
+        instruction = field["instruction"].strip()
+        field["type"] = instruction.split(maxsplit=1)[0].upper() if instruction else ""
+    return fields
+
+
+def inspect_docx(source: str | Path, *, scope: str = "all", offset: int = 1, limit: int = 20) -> dict:
+    """Return counts and paginated fields/images/tables. Field presence does not certify pagination."""
+    if scope not in {"all", "fields", "images", "tables"}:
+        raise ValueError("scope must be all, fields, images or tables")
+    if type(offset) is not int or offset < 1 or type(limit) is not int or not 1 <= limit <= 200:
+        raise ValueError("offset must be positive; limit must be 1-200")
+    package = DocxPackage(source)
+    parts = {info.filename: data for info, data in package.parts}
+    fields, images, tables = [], [], []
+    for part, data in parts.items():
+        if not part.startswith("word/") or not part.endswith(".xml"):
+            continue
+        root = package.root if part == "word/document.xml" else _xml(data)
+        fields.extend(_fields(root, part))
+        rel_path = str(PurePosixPath(part).parent / "_rels" / (PurePosixPath(part).name + ".rels"))
+        relationships = {rel.get("Id"): rel for rel in _xml(parts[rel_path])} if rel_path in parts else {}
+        for element in root.iter():
+            if element.tag == W + "tbl":
+                grid = element.find(W + "tblGrid")
+                tables.append({"part": part, "row_count": len(element.findall(W + "tr")),
+                               "column_count": len(grid) if grid is not None else None})
+            if element.tag not in {A + "blip", V + "imagedata"}:
+                continue
+            rid = element.get(R + "embed") or element.get(R + "link") or element.get(R + "id")
+            rel = relationships.get(rid)
+            if rel is None:
+                images.append({"part": part, "relationship_id": rid, "status": "missing_relationship"})
+                continue
+            target = rel.get("Target", "")
+            external = rel.get("TargetMode") == "External"
+            target_part = None if external else posixpath.normpath(posixpath.join(posixpath.dirname(part), target)).lstrip("/")
+            images.append({"part": part, "relationship_id": rid, "target": target,
+                           "external": external, "package_part": target_part,
+                           "status": "external" if external else "embedded" if target_part in parts else "missing_part"})
+    settings = _xml(parts["word/settings.xml"]) if "word/settings.xml" in parts else None
+    update = settings.find(W + "updateFields") if settings is not None else None
+    report = {"path": str(package.path), "revision": package.revision,
+              "field_count": len(fields), "toc_count": sum(field["type"] == "TOC" for field in fields),
+              "image_count": len(images), "table_count": len(tables),
+              "update_fields_on_open": update is not None and update.get(W + "val", "true") not in {"false", "0", "off"},
+              "rendered_layout_verified": False}
+    for name, items in (("fields", fields), ("images", images), ("tables", tables)):
+        if scope in {"all", name}:
+            selected = items[offset - 1:offset - 1 + limit]
+            report[name] = {"items": selected, "next_offset": offset + len(selected) if offset - 1 + len(selected) < len(items) else None}
+    return report

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

@@ -202,7 +202,7 @@ def delete_docx_blocks(source: str | Path, output: str | Path, *, revision: str,
 
 
 def verify_docx(source: str | Path, *, expectations: list[dict] | None = None,
-                original: str | Path | None = None) -> dict:
+                original: str | Path | None = None, base_dir: str | Path = ".") -> dict:
     """Check package structure and exact positions; absent assertions do not certify content."""
     package = DocxPackage(source)
     structure = _Structure(package.root)
@@ -212,12 +212,9 @@ def verify_docx(source: str | Path, *, expectations: list[dict] | None = None,
     if not isinstance(expectations, list):
         raise TypeError("expectations must be an array")
     mismatches = []
+    from .document_docx_expectations import expected_text
     for index, expectation in enumerate(expectations, 1):
-        if not isinstance(expectation, dict) or not {"target", "text"} <= set(expectation) or set(expectation) - {"target", "text", "mode"}:
-            raise ValueError(f"expectation {index} requires target,text and optional mode")
-        expected, mode = expectation["text"], expectation.get("mode", "equals")
-        if not isinstance(expected, str) or mode not in {"equals", "contains", "absent"}:
-            raise ValueError(f"expectation {index}: text must be a string; mode must be equals, contains or absent")
+        expected, mode = expected_text(expectation, index, base_dir)
         actual = _text(structure.target(expectation["target"]))
         passed = actual == expected if mode == "equals" else expected in actual if mode == "contains" else expected not in actual
         if not passed:

licos_dev_sdk-0.4.4/tests/test_docx_inspect.py

@@ -0,0 +1,113 @@
+import base64
+from io import BytesIO
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+import pytest
+
+from licos_dev_sdk import inspect_docx, verify_docx
+
+
+def field_run(paragraph, tag, value):
+    element = OxmlElement('w:' + tag)
+    if tag == 'instrText':
+        element.text = value
+    else:
+        element.set(qn('w:fldCharType'), value)
+    paragraph.add_run()._r.append(element)
+
+
+def test_inspect_native_fields_images_and_tables_without_rewriting(tmp_path):
+    path = tmp_path / 'report.docx'
+    doc = Document()
+    p = doc.add_paragraph()
+    field_run(p, 'fldChar', 'begin')
+    field_run(p, 'instrText', ' TO')
+    field_run(p, 'instrText', 'C \\o "1-3" ')
+    field_run(p, 'fldChar', 'separate')
+    p.add_run('Cached table of contents')
+    field_run(p, 'fldChar', 'end')
+    simple = OxmlElement('w:fldSimple')
+    simple.set(qn('w:instr'), 'PAGE')
+    doc.sections[0].footer.paragraphs[0]._p.append(simple)
+    png = base64.b64decode('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAwMCAO+aTtQAAAAASUVORK5CYII=')
+    doc.add_picture(BytesIO(png))
+    doc.sections[0].header.paragraphs[0].add_run().add_picture(BytesIO(png))
+    doc.add_table(rows=3, cols=2)
+    update = OxmlElement('w:updateFields')
+    update.set(qn('w:val'), 'true')
+    doc.settings.element.append(update)
+    doc.save(path)
+    original = path.read_bytes()
+    report = inspect_docx(path, limit=1)
+    assert report['toc_count'] == 1 and report['field_count'] == 2
+    assert report['image_count'] == 2 and report['table_count'] == 1
+    assert report['fields']['items'][0]['complete']
+    assert report['fields']['items'][0]['instruction'] == ' TOC \\o "1-3" '
+    assert report['images']['next_offset'] == 2
+    assert report['tables']['items'][0] == {'part': 'word/document.xml', 'row_count': 3, 'column_count': 2}
+    second = inspect_docx(path, scope='images', offset=2)
+    assert second['images']['items'][0]['part'].startswith('word/header')
+    assert second['images']['items'][0]['status'] == 'embedded'
+    assert 'fields' not in second
+    assert report['update_fields_on_open'] and not report['rendered_layout_verified']
+    assert path.read_bytes() == original
+    with ZipFile(path) as archive:
+        parts = {name: archive.read(name) for name in archive.namelist()}
+    image_part = report['images']['items'][0]['package_part']
+    parts.pop(image_part)
+    with ZipFile(path, 'w') as archive:
+        for name, data in parts.items():
+            archive.writestr(name, data)
+    assert inspect_docx(path)['images']['items'][0]['status'] == 'missing_part'
+
+
+def test_incomplete_toc_and_external_or_missing_image_relationships(tmp_path):
+    path = tmp_path / 'linked.docx'
+    doc = Document()
+    p = doc.add_paragraph()
+    field_run(p, 'fldChar', 'begin')
+    field_run(p, 'instrText', 'TOC')
+    rid = doc.part.relate_to('https://example.com/image.png',
+                            'http://schemas.openxmlformats.org/officeDocument/2006/relationships/image', is_external=True)
+    for relationship in (rid, 'missing'):
+        blip = OxmlElement('a:blip')
+        blip.set(qn('r:link'), relationship)
+        p.add_run()._r.append(blip)
+    doc.save(path)
+    report = inspect_docx(path)
+    assert not report['fields']['items'][0]['complete']
+    assert [image['status'] for image in report['images']['items']] == ['external', 'missing_relationship']
+
+
+def test_batch_file_assertions_resolve_from_explicit_base_and_keep_exact_text(tmp_path, monkeypatch):
+    path = tmp_path / 'report.docx'
+    text = '  中文🙂\tA\n' * 90 + '  '
+    doc = Document()
+    doc.add_paragraph(text)
+    doc.save(path)
+    expected = tmp_path / 'expected.txt'
+    expected.write_text(text, encoding='utf-8')
+    monkeypatch.chdir(tmp_path.parent)
+    assertion = {'target': {'block': 1}, 'text_file': 'expected.txt'}
+    assert verify_docx(path, expectations=[assertion], base_dir=tmp_path)['verified']
+    assertion['text_file'] = str(expected)
+    assert verify_docx(path, expectations=[assertion])['verified']
+
+
+@pytest.mark.parametrize(('assertion', 'error'), [
+    ({'text-file': 'x.txt'}, 'unknown fields text-file'),
+    ({'text': 'x', 'text_file': 'x.txt'}, 'exactly one'),
+    ({'text_file': None}, 'text_file must be'),
+    ({'text_file': 'missing.txt'}, 'expectation 1.text_file'),
+    ({'text': '', 'mode': []}, 'mode must be'),
+])
+def test_invalid_assertions_report_precise_schema_field(tmp_path, assertion, error):
+    path = tmp_path / 'report.docx'
+    doc = Document()
+    doc.add_paragraph('')
+    doc.save(path)
+    with pytest.raises(ValueError, match=error):
+        verify_docx(path, expectations=[{'target': {'block': 1}, **assertion}], base_dir=tmp_path)