dsh-office-kit 0.2.0 → 0.3.1

package/assets/skills/office-documents/scripts/internal_nav.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python
+"""Build deterministic internal navigation: a linked contents list and anchors.
+
+Word's TOC field needs a refresh before its links work.  This script instead
+writes static hyperlinks that any renderer follows: bookmarks on every heading,
+a contents list at the top (with quick links and back links), and optional
+Top/Bottom anchors.  Because the entries are literal text there is nothing to
+update before the file is read.
+
+Exit codes: 0 success, 1 no headings, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+TOP_BOOKMARK = "nav_top"
+BOTTOM_BOOKMARK = "nav_bottom"
+TOC_BOOKMARK = "nav_toc"
+
+
+def link_run(text: str, anchor: str):
+    link = etree.Element(kit.q("hyperlink"))
+    link.set(kit.q("anchor"), anchor)
+    link.append(kit.make_run(text))
+    return link
+
+
+def add_bookmark(paragraph, name: str, ident: int) -> None:
+    start = etree.Element(kit.q("bookmarkStart"))
+    start.set(kit.q("id"), str(ident))
+    start.set(kit.q("name"), name)
+    end = etree.Element(kit.q("bookmarkEnd"))
+    end.set(kit.q("id"), str(ident))
+    position = 1 if paragraph.find(kit.q("pPr")) is not None else 0
+    paragraph.insert(position, start)
+    paragraph.append(end)
+
+
+def paragraph(style: str | None = None):
+    node = etree.Element(kit.q("p"))
+    if style:
+        props = etree.SubElement(node, kit.q("pPr"))
+        etree.SubElement(props, kit.q("pStyle")).set(kit.q("val"), style)
+    return node
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Add bookmark anchors and static internal links to headings.")
+    parser.add_argument("input_docx", help="Input .docx")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--toc_title", default="Table of Contents")
+    parser.add_argument("--levels", nargs="+", type=int, default=[1, 2, 3], help="Heading levels to include")
+    parser.add_argument("--no_quicklinks", action="store_true", help="Skip the quick links bar")
+    parser.add_argument("--no_back_to_toc", action="store_true", help="Skip per-heading back links")
+    parser.add_argument("--no_top_bottom", action="store_true", help="Skip Top/Bottom anchors")
+    args = parser.parse_args(argv)
+
+    try:
+        doc = kit.Docx(args.input_docx)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    body = doc.body()
+    headings = []
+    ident = doc.next_id()
+    for paragraph_node in list(body.iter(kit.q("p"))):
+        level = kit.heading_level(paragraph_node)
+        text = kit.paragraph_text(paragraph_node).strip()
+        if level in args.levels and text:
+            name = "nav_h%d" % ident
+            add_bookmark(paragraph_node, name, ident)
+            headings.append({"level": level, "text": text, "anchor": name})
+            ident += 1
+
+    if not headings:
+        print("error: document has no headings at levels %s" % args.levels, file=sys.stderr)
+        return 1
+
+    first = body.find(kit.q("p"))
+    if first is None:
+        first = etree.SubElement(body, kit.q("p"))
+    position = body.index(first)
+
+    block = []
+    if not args.no_top_bottom:
+        top = paragraph()
+        add_bookmark(top, TOP_BOOKMARK, ident)
+        ident += 1
+        block.append(top)
+
+    title = paragraph("Heading1")
+    add_bookmark(title, TOC_BOOKMARK, ident)
+    ident += 1
+    title.append(kit.make_run(args.toc_title))
+    block.append(title)
+
+    if not args.no_quicklinks:
+        quick = paragraph()
+        quick.append(kit.make_run("Quick links: "))
+        for index, item in enumerate([entry for entry in headings if entry["level"] == 1] or headings):
+            if index:
+                quick.append(kit.make_run(" | "))
+            quick.append(link_run(item["text"], item["anchor"]))
+        block.append(quick)
+
+    for item in headings:
+        entry = paragraph("TOC%d" % item["level"] if item["level"] <= 3 else "TOC3")
+        props = entry.find(kit.q("pPr"))
+        ind = etree.SubElement(props, kit.q("ind"))
+        ind.set(kit.q("left"), str((item["level"] - 1) * 360))
+        entry.append(link_run(item["text"], item["anchor"]))
+        block.append(entry)
+
+    for offset, node in enumerate(block):
+        body.insert(position + offset, node)
+
+    if not args.no_back_to_toc:
+        for paragraph_node in list(body.iter(kit.q("p"))):
+            if any(entry["anchor"] == name for entry in headings for name in (paragraph_node.find(kit.q("bookmarkStart")).get(kit.q("name")),) if paragraph_node.find(kit.q("bookmarkStart")) is not None):
+                back = paragraph("Caption")
+                back.append(link_run("Back to contents", TOC_BOOKMARK))
+                paragraph_node.addnext(back)
+
+    if not args.no_top_bottom:
+        last = paragraph()
+        add_bookmark(last, BOTTOM_BOOKMARK, ident)
+        ident += 1
+        last.append(link_run("Back to top", TOP_BOOKMARK))
+        body.append(last)
+
+    doc.save(args.out)
+    kit.emit({"ok": True, "output": str(Path(args.out)), "headings": headings, "entries": len(block)})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/make_fixtures.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python
+"""Generate small documents that exercise the awkward parts of the format.
+
+Reviewing comments, tracked changes or watermarks is impossible without files
+that contain them, and hand-building those by clicking in Word is not repeatable.
+Each fixture targets one feature so a script's report can be judged against a
+known-clean or known-broken input.
+
+Exit codes: 0 success, 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import tempfile
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+from docx import Document
+from docx.shared import Inches
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+
+def base_document(title: str, paragraphs: list[str]) -> Document:
+    document = Document()
+    document.add_heading(title, level=1)
+    for text in paragraphs:
+        document.add_paragraph(text)
+    return document
+
+
+def mark_paragraph(paragraph, before: str, deleted: str, inserted: str, after: str, author: str, date: str) -> None:
+    rpr = kit.first_rpr(paragraph)
+    kit.clear_paragraph_content(paragraph)
+    paragraph.append(kit.make_run(before, etree.fromstring(etree.tostring(rpr)) if rpr is not None else None))
+    deletion = etree.SubElement(paragraph, kit.q("del"))
+    deletion.set(kit.q("id"), "101")
+    deletion.set(kit.q("author"), author)
+    deletion.set(kit.q("date"), date)
+    deletion.append(kit.make_run(deleted, tag="delText"))
+    insertion = etree.SubElement(paragraph, kit.q("ins"))
+    insertion.set(kit.q("id"), "102")
+    insertion.set(kit.q("author"), author)
+    insertion.set(kit.q("date"), date)
+    insertion.append(kit.make_run(inserted))
+    paragraph.append(kit.make_run(after))
+
+
+def make_tracked(target: Path) -> dict:
+    document = base_document("Revisions demo", ["Regional revenue grew by 12% in the quarter.", "Hardware sales stayed flat."])
+    document.save(target)
+    doc = kit.Docx(target)
+    paragraphs = doc.paragraphs()
+    mark_paragraph(paragraphs[1], "Regional revenue grew by ", "12%", "14%", " in the quarter.", "Reviewer", "2024-05-01T09:00:00Z")
+    mark_paragraph(paragraphs[2], "Hardware sales ", "stayed", "remained", " flat.", "Reviewer", "2024-05-01T09:01:00Z")
+    settings = doc.xml("word/settings.xml")
+    if settings.find(kit.q("trackRevisions")) is None:
+        settings.append(settings.makeelement(kit.q("trackRevisions"), {}))
+    doc.save(target)
+    return {"path": str(target), "tracked_changes": 4}
+
+
+def make_watermark(target: Path) -> dict:
+    document = base_document("Watermark demo", ["This copy is for internal review."])
+    document.save(target)
+    doc = kit.Docx(target)
+    part = doc.ensure_header_footer("header")
+    doc.xml(part).append(kit.watermark_paragraph("DRAFT", doc.next_id()))
+    doc.save(target)
+    return {"path": str(target), "watermark": "DRAFT"}
+
+
+def make_comments(target: Path) -> dict:
+    document = base_document("Comments demo", ["The first paragraph carries a question.", "The second paragraph is clean."])
+    document.save(target)
+    doc = kit.Docx(target)
+    root = etree.Element(kit.q("comments"), nsmap={"w": kit.W, "r": kit.R})
+    doc.set_xml("word/comments.xml", root)
+    doc.ensure_override("word/comments.xml", kit.CT_BY_REL[kit.REL_COMMENTS])
+    doc.ensure_rel("word/document.xml", kit.REL_COMMENTS, "comments.xml")
+    comment = etree.SubElement(root, kit.q("comment"))
+    comment.set(kit.q("id"), "1")
+    comment.set(kit.q("author"), "Reviewer")
+    comment.set(kit.q("initials"), "RV")
+    comment.set(kit.q("date"), "2024-05-02T10:00:00Z")
+    body = etree.SubElement(comment, kit.q("p"))
+    etree.SubElement(etree.SubElement(body, kit.q("r")), kit.q("t")).text = "Is this number current?"
+
+    paragraph = doc.paragraphs()[1]
+    start = etree.Element(kit.q("commentRangeStart"))
+    start.set(kit.q("id"), "1")
+    paragraph.insert(1, start)
+    end = etree.SubElement(paragraph, kit.q("commentRangeEnd"))
+    end.set(kit.q("id"), "1")
+    run = etree.SubElement(paragraph, kit.q("r"))
+    etree.SubElement(run, kit.q("commentReference")).set(kit.q("id"), "1")
+    doc.save(target)
+    return {"path": str(target), "comments": 1}
+
+
+def make_edge_cases(target: Path, image_dir: Path) -> dict:
+    image_path = image_dir / "sample.png"
+    try:
+        from PIL import Image
+
+        Image.new("RGB", (320, 200), "#4472c4").save(image_path)
+    except ImportError:
+        image_path = None
+
+    document = Document()
+    document.add_heading("Edge cases", level=1)
+    document.add_paragraph("")
+    document.add_heading("A level three heading after a level one", level=3)
+    document.add_paragraph("A very long paragraph " * 40)
+    document.add_paragraph("Contact: writer@example.org or +1 555 010 9999.")
+    table = document.add_table(rows=2, cols=10)
+    for row_index in range(2):
+        for column_index in range(10):
+            table.cell(row_index, column_index).text = "R%dC%d" % (row_index + 1, column_index + 1)
+    if image_path is not None:
+        document.add_picture(str(image_path), width=Inches(4))
+    document.save(target)
+    return {"path": str(target), "fixtures": ["empty_paragraph", "skipped_heading_level", "wide_table", "image_without_alt", "contact_details"]}
+
+
+BUILDERS = {
+    "tracked": make_tracked,
+    "watermark": make_watermark,
+    "comments": make_comments,
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Create sample .docx files for tracked changes, watermarks, comments and edge cases.")
+    parser.add_argument("--outdir", required=True, help="Directory for the generated files")
+    parser.add_argument("--only", default="all", help="tracked, watermark, comments, edge, or all")
+    args = parser.parse_args(argv)
+
+    out_dir = Path(args.outdir).expanduser().resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    wanted = [name.strip() for name in args.only.split(",") if name.strip()]
+    if "all" in wanted:
+        wanted = ["tracked", "watermark", "comments", "edge"]
+    unknown = [name for name in wanted if name not in BUILDERS and name != "edge"]
+    if unknown:
+        print("error: unknown fixture %s" % ", ".join(unknown), file=sys.stderr)
+        return 2
+
+    results = []
+    try:
+        for name in wanted:
+            if name == "edge":
+                results.append(make_edge_cases(out_dir / "edge_cases.docx", out_dir))
+            else:
+                results.append(BUILDERS[name](out_dir / ("%s.docx" % name)))
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    kit.emit({"ok": True, "outdir": str(out_dir), "fixtures": results})
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/skills/office-documents/scripts/merge_docx_append.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python
+"""Append one document's body to another, carrying its parts across.
+
+Merging by pasting XML is the easy half; the hard half is that the second file's
+relationships point at its own media, numbering and styles.  This script copies
+those parts into the base under free names, remaps relationship ids and
+numbering ids, and brings over any style the appended content needs.
+
+Drawings are refused by default: a nested drawing can carry its own rel chain and
+silently break a merge, so it has to be asked for explicitly.
+
+Exit codes: 0 success, 1 refused (drawings present, incompatible input), 2 bad input.
+"""
+
+from __future__ import annotations
+
+import argparse
+import posixpath
+import sys
+from pathlib import Path
+
+from lxml import etree
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import docx_kit as kit
+
+# Windows consoles default to a legacy code page; every payload is UTF-8 JSON.
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+CT = "{http://schemas.openxmlformats.org/package/2006/content-types}"
+W_NS = "{http://schemas.openxmlformats.org/package/2006/relationships}"
+REL_NUMBERING = kit.REL_NUMBERING
+
+
+def free_part_name(base: kit.Docx, source: str) -> str:
+    folder = posixpath.dirname(source) or "word/media"
+    stem, extension = posixpath.splitext(posixpath.basename(source))
+    candidate = posixpath.join(folder, stem + extension)
+    counter = 1
+    while base.exists(candidate):
+        candidate = posixpath.join(folder, "%s_copy%d%s" % (stem, counter, extension))
+        counter += 1
+    return candidate
+
+
+def copy_part(base: kit.Docx, append: kit.Docx, source: str) -> str:
+    target = free_part_name(base, source)
+    base.parts[target] = append.parts[source]
+    base.order.append(target)
+    base._cache.pop(target, None)
+    for node in append.content_types().findall(CT + "Override"):
+        if node.get("PartName") == "/" + source:
+            base.ensure_override(target, node.get("ContentType"))
+            break
+    return target
+
+
+def copy_defaults(base: kit.Docx, append: kit.Docx) -> None:
+    existing = {(node.get("Extension") or "").lower() for node in base.content_types().findall(CT + "Default")}
+    for node in append.content_types().findall(CT + "Default"):
+        extension = (node.get("Extension") or "").lower()
+        if extension and extension not in existing:
+            clone = etree.SubElement(base.content_types(), CT + "Default")
+            clone.set("Extension", node.get("Extension"))
+            clone.set("ContentType", node.get("ContentType"))
+            existing.add(extension)
+
+
+def ensure_style(base: kit.Docx, append: kit.Docx, wanted: str) -> bool:
+    if not append.exists("word/styles.xml") or not wanted:
+        return False
+    base_styles = base.xml("word/styles.xml")
+    present = {node.get(kit.q("styleId")) for node in base_styles.findall(kit.q("style"))}
+    if wanted in present:
+        return False
+    source_styles = {node.get(kit.q("styleId")): node for node in append.xml("word/styles.xml").findall(kit.q("style"))}
+    pending = [wanted]
+    copied = False
+    while pending:
+        style_id = pending.pop()
+        node = source_styles.get(style_id)
+        if node is None or style_id in present:
+            continue
+        clone = etree.fromstring(etree.tostring(node))
+        base_styles.append(clone)
+        present.add(style_id)
+        copied = True
+        for link_tag in ("basedOn", "next", "link"):
+            ref = node.find(kit.q(link_tag))
+            if ref is not None and ref.get(kit.q("val")):
+                pending.append(ref.get(kit.q("val")))
+    return copied
+
+
+def remap_numbering(base: kit.Docx, append: kit.Docx, nodes: list) -> dict[str, str]:
+    used = set()
+    for node in nodes:
+        for num_pr in node.iter(kit.q("numPr")):
+            num_id = num_pr.find(kit.q("numId"))
+            if num_id is not None and num_id.get(kit.q("val")):
+                used.add(num_id.get(kit.q("val")))
+    if not used or not append.exists("word/numbering.xml"):
+        return {}
+    if not base.exists("word/numbering.xml"):
+        base.parts["word/numbering.xml"] = append.parts["word/numbering.xml"]
+        base.order.append("word/numbering.xml")
+        base.ensure_override("word/numbering.xml", "application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml")
+        base.ensure_rel("word/document.xml", kit.REL_NUMBERING, "numbering.xml")
+        return {}
+
+    base_root = base.xml("word/numbering.xml")
+    source_root = append.xml("word/numbering.xml")
+    base_nums = {node.get(kit.q("numId")): node for node in base_root.findall(kit.q("num"))}
+    base_abstract = {node.get(kit.q("abstractNumId")): node for node in base_root.findall(kit.q("abstractNum"))}
+    next_num = max([int(value) for value in base_nums if (value or "").isdigit()], default=0) + 1
+    next_abstract = max([int(value) for value in base_abstract if (value or "").isdigit()], default=0) + 1
+    source_nums = {node.get(kit.q("numId")): node for node in source_root.findall(kit.q("num"))}
+    source_abstract = {node.get(kit.q("abstractNumId")): node for node in source_root.findall(kit.q("abstractNum"))}
+    mapping = {}
+    for old in used:
+        node = source_nums.get(old)
+        if node is None:
+            continue
+        clone = etree.fromstring(etree.tostring(node))
+        reference = clone.find(kit.q("abstractNumId"))
+        abstract_old = reference.get(kit.q("val")) if reference is not None else None
+        if abstract_old in source_abstract and abstract_old not in base_abstract:
+            abstract_clone = etree.fromstring(etree.tostring(source_abstract[abstract_old]))
+            abstract_clone.set(kit.q("abstractNumId"), str(next_abstract))
+            base_root.insert(0, abstract_clone)
+            base_abstract[str(next_abstract)] = abstract_clone
+            next_abstract += 1
+            if reference is not None:
+                reference.set(kit.q("val"), abstract_clone.get(kit.q("abstractNumId")))
+        clone.set(kit.q("numId"), str(next_num))
+        mapping[old] = str(next_num)
+        base_root.append(clone)
+        base_nums[str(next_num)] = clone
+        next_num += 1
+    return mapping
+
+
+def remap_relationships(base: kit.Docx, append: kit.Docx, nodes: list) -> int:
+    mapping = {}
+    copied = 0
+    source_rels = {entry["id"]: entry for entry in append.relationships("word/document.xml")}
+    attributes = (kit.q("embed", kit.R), kit.q("id", kit.R), kit.q("link", kit.R))
+    for node in nodes:
+        for element in node.iter():
+            for attribute in attributes:
+                rid = element.get(attribute)
+                if not rid:
+                    continue
+                if rid not in mapping:
+                    rel = source_rels.get(rid)
+                    if rel is None:
+                        mapping[rid] = rid
+                        continue
+                    if rel["mode"] == "External":
+                        mapping[rid] = base.ensure_rel("word/document.xml", rel["type"], rel["target"], external=True)
+                    elif append.exists(rel["resolved"]):
+                        target = copy_part(base, append, rel["resolved"])
+                        relative = posixpath.relpath(target, "word")
+                        mapping[rid] = base.ensure_rel("word/document.xml", rel["type"], relative)
+                        copied += 1
+                    else:
+                        mapping[rid] = rid
+                element.set(attribute, mapping[rid])
+    return copied
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Append one .docx body to another, copying media, numbering and styles.")
+    parser.add_argument("base", help="Document to append to")
+    parser.add_argument("append", help="Document whose body is copied in")
+    parser.add_argument("--out", required=True, help="Output .docx")
+    parser.add_argument("--allow_drawings", action="store_true", help="Copy drawings and their relationships")
+    args = parser.parse_args(argv)
+
+    try:
+        base = kit.Docx(args.base)
+        append = kit.Docx(args.append)
+    except (OSError, KeyError) as exc:
+        print("error: %s" % exc, file=sys.stderr)
+        return 2
+
+    append_body = append.body()
+    incoming = [child for child in append_body if child.tag != kit.q("sectPr")]
+    if not incoming:
+        print("error: %s has an empty body" % args.append, file=sys.stderr)
+        return 2
+
+    has_drawings = any(child.find(".//" + tag) is not None for child in incoming for tag in (kit.q("drawing"), kit.q("pict")))
+    if has_drawings and not args.allow_drawings:
+        print("error: appended body contains drawings; re-run with --allow_drawings", file=sys.stderr)
+        return 1
+
+    style_ids = set()
+    numbering_nodes = []
+    for child in incoming:
+        for node in child.iter():
+            for tag in ("pStyle", "rStyle", "tblStyle"):
+                if node.tag == kit.q(tag) and node.get(kit.q("val")):
+                    style_ids.add(node.get(kit.q("val")))
+        if child.find(".//" + kit.q("numPr")) is not None:
+            numbering_nodes.append(child)
+
+    styles_copied = sum(1 for style_id in sorted(style_ids) if ensure_style(base, append, style_id))
+    number_map = remap_numbering(base, append, numbering_nodes)
+
+    clones = [etree.fromstring(etree.tostring(child)) for child in incoming]
+    if number_map:
+        for clone in clones:
+            for num_pr in clone.iter(kit.q("numPr")):
+                num_id = num_pr.find(kit.q("numId"))
+                if num_id is not None and num_id.get(kit.q("val")) in number_map:
+                    num_id.set(kit.q("val"), number_map[num_id.get(kit.q("val"))])
+    media_copied = remap_relationships(base, append, clones)
+    copy_defaults(base, append)
+
+    body = base.body()
+    sect = body.find(kit.q("sectPr"))
+    anchor = body.index(sect) if sect is not None else len(body)
+    for offset, clone in enumerate(clones):
+        body.insert(anchor + offset, clone)
+
+    base.save(args.out)
+    kit.emit(
+        {
+            "ok": True,
+            "output": str(Path(args.out)),
+            "appended_elements": len(clones),
+            "styles_copied": styles_copied,
+            "media_copied": media_copied,
+            "numbering_remapped": len(number_map),
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())