Word × Python── Extracting paragraphs and tables with python-docx and writing results to a separate file

"""Check .docx text against a style list in document order, including tables and hyperlinks."""
import csv
from pathlib import Path

from docx import Document
from docx.table import Table
from docx.text.hyperlink import Hyperlink

TERMS = Path("samples/style_terms.csv")
DOCS = sorted(Path("samples").glob("*.docx"))


def load_terms(path):
    with open(path, encoding="utf-8-sig", newline="") as f:
        return list(csv.DictReader(f))


def iter_paragraphs(container, where=""):
    """Yield (location, paragraph) for body paragraphs and every table cell, in document order."""
    for i, block in enumerate(container.iter_inner_content(), 1):
        if isinstance(block, Table):
            seen = []
            for r, row in enumerate(block.rows, 1):
                for c, cell in enumerate(row.cells, 1):
                    if cell in seen:  # merged cells repeat across grid positions
                        continue
                    seen.append(cell)
                    yield from iter_paragraphs(cell, "%sT%d-r%dc%d/" % (where, i, r, c))
        else:
            yield "%sB%d(%s)" % (where, i, block.style.name), block


def main():
    terms = load_terms(TERMS)
    hits, links = [], []
    for path in DOCS:
        for where, para in iter_paragraphs(Document(path)):
            for item in para.iter_inner_content():
                if isinstance(item, Hyperlink):
                    links.append((path.name, where, item.text, item.address))
            for t in terms:
                if t["term"] in para.text:
                    hits.append((path.name, where, t["term"], t["action"], para.text.strip()))
    with open("out_term_hits.csv", "w", encoding="utf-8-sig", newline="") as f:
        w = csv.writer(f)
        w.writerow(["file", "where", "term", "action", "text"])
        w.writerows(hits)
    print("hits:", len(hits), "links:", len(links))
    for h in hits[:6]:
        print(" | ".join(h[:4]))
    for link in links:
        print("link:", " | ".join(link))


if __name__ == "__main__":
    main()

"""Export Word tables to CSV, keeping merged and nested cells visible."""
import csv
from pathlib import Path

from docx import Document

DOCS = sorted(Path("samples").glob("*.docx"))


def table_rows(table, path):
    """Yield one record per grid position; nested tables are walked too."""
    seen = []
    for r, row in enumerate(table.rows):
        col = row.grid_cols_before  # skip grid columns omitted at the start of the row
        for cell in row.cells:
            repeat = cell in seen  # a merged cell appears once per grid column it covers
            if not repeat:
                seen.append(cell)
            yield {"table": path, "row": r, "col": col, "span": cell.grid_span,
                   "merged_repeat": repeat, "text": cell.text.strip().replace("\n", " / ")}
            if not repeat:
                for k, inner in enumerate(cell.tables, 1):
                    yield from table_rows(inner, "%s>r%dc%d.t%d" % (path, r, col, k))
            col += 1


def main():
    records = []
    for path in DOCS:
        doc = Document(path)
        for i, table in enumerate(doc.tables, 1):
            for rec in table_rows(table, "t%d" % i):
                records.append(dict(rec, file=path.name))
        print("%s: top-level tables %d" % (path.name, len(doc.tables)))
    fields = ["file", "table", "row", "col", "span", "merged_repeat", "text"]
    with open("out_tables.csv", "w", encoding="utf-8-sig", newline="") as f:
        w = csv.DictWriter(f, fieldnames=fields)
        w.writeheader()
        w.writerows(records)
    nested = sorted({r["file"] + ":" + r["table"] for r in records if ">" in r["table"]})
    print("cells:", len(records), "merged repeats:", sum(r["merged_repeat"] for r in records))
    print("nested tables:", nested)


if __name__ == "__main__":
    main()

"""Build a heading outline from Word's built-in Heading styles and flag skipped levels."""
import csv
import re
from pathlib import Path

from docx import Document

DOCS = sorted(Path("samples").glob("*.docx"))
HEADING = re.compile(r"^Heading ([1-9])$")  # built-in names are stored in English


def outline(doc):
    rows, prev = [], 0
    for i, p in enumerate(doc.paragraphs, 1):
        m = HEADING.match(p.style.name or "")
        if not m:
            continue
        level = int(m.group(1))
        issue = "skipped level" if level > prev + 1 else ""
        rows.append({"paragraph": i, "level": level, "heading": p.text.strip(), "issue": issue})
        prev = level
    return rows


def main():
    with open("out_outline.csv", "w", encoding="utf-8-sig", newline="") as f:
        w = csv.DictWriter(f, fieldnames=["file", "paragraph", "level", "heading", "issue"])
        w.writeheader()
        for path in DOCS:
            rows = outline(Document(path))
            if not any(r["level"] == 1 for r in rows):
                rows.insert(0, {"paragraph": 0, "level": 0, "heading": "", "issue": "no Heading 1"})
            print("==", path.name)
            for r in rows:
                w.writerow(dict(r, file=path.name))
                mark = "   <-- " + r["issue"] if r["issue"] else ""
                print("  " * max(r["level"] - 1, 0) + r["heading"] + mark)


if __name__ == "__main__":
    main()

"""Inventory .docx files: core properties plus header/footer text per section."""
import csv
from pathlib import Path

from docx import Document

DOCS = sorted(Path("samples").glob("*.docx"))
FIELDS = ["file", "section", "title", "author", "last_modified_by", "revision", "modified_utc",
          "header", "header_source", "footer", "footer_source", "issues"]


def story_text(part):
    """Text of a header/footer, or None when it is linked (reading .paragraphs would add one)."""
    if part.is_linked_to_previous:
        return None
    return " / ".join(p.text for p in part.paragraphs if p.text.strip())


def inventory(path):
    doc = Document(path)
    cp = doc.core_properties
    rows, last = [], {"header": "", "footer": ""}
    for i, section in enumerate(doc.sections, 1):
        row = {"file": path.name, "section": i, "title": cp.title, "author": cp.author,
               "last_modified_by": cp.last_modified_by, "revision": cp.revision,
               "modified_utc": cp.modified.isoformat() if cp.modified else ""}
        for kind in ("header", "footer"):
            text = story_text(getattr(section, kind))
            if text is None:
                row[kind + "_source"] = "previous section" if i > 1 else "none"
                text = last[kind]
            else:
                row[kind + "_source"] = "own"
            row[kind] = last[kind] = text
        issues = []
        if not cp.title:
            issues.append("no title")
        if not row["footer"]:
            issues.append("no footer text")
        row["issues"] = "; ".join(issues)
        rows.append(row)
    return rows


def main():
    rows = [r for path in DOCS for r in inventory(path)]
    with open("out_doc_inventory.csv", "w", encoding="utf-8-sig", newline="") as f:
        w = csv.DictWriter(f, fieldnames=FIELDS)
        w.writeheader()
        w.writerows(rows)
    print("files:", len(DOCS), "sections:", len(rows))
    for r in rows:
        print("%s s%d | author=%s | footer=%s (%s) | %s" % (
            r["file"], r["section"], r["author"], r["footer"], r["footer_source"], r["issues"] or "ok"))


if __name__ == "__main__":
    main()

"""Add style-list hits as Word comments on a copy of each document (python-docx 1.2.0+)."""
import csv
from pathlib import Path

from docx import Document

TERMS = Path("samples/style_terms.csv")
DOCS = sorted(Path("samples").glob("doc_*.docx"))
AUTHOR = "style-check"


def load_terms(path):
    with open(path, encoding="utf-8-sig", newline="") as f:
        return list(csv.DictReader(f))


def paragraphs(doc):
    """Body paragraphs, then paragraphs in table cells (merged cells visited once)."""
    yield from doc.paragraphs
    for table in doc.tables:
        seen = []
        for row in table.rows:
            for cell in row.cells:
                if cell in seen:
                    continue
                seen.append(cell)
                yield from cell.paragraphs


def annotate(path, terms):
    doc = Document(path)
    added = []
    for p in paragraphs(doc):
        found = [t for t in terms if t["term"] in p.text]
        if not found or not p.runs:
            continue
        note = "\n".join("%s: %s" % (t["term"], t["action"]) for t in found)
        comment = doc.add_comment(runs=p.runs, text=note, author=AUTHOR)
        added.append((comment.comment_id, p.text.strip()[:30]))
    out = Path("out_%s_commented.docx" % path.stem)
    if out.resolve() == path.resolve():
        raise SystemExit("refusing to overwrite the input")
    doc.save(out)
    return out, added


def main():
    terms = load_terms(TERMS)
    for path in DOCS:
        out, added = annotate(path, terms)
        reopened = Document(out)
        print("%s -> %s comments: %d (reopened: %d)" % (path.name, out.name, len(added), len(reopened.comments)))
        for cid, text in added[:3]:
            print("  #%s %s" % (cid, text))


if __name__ == "__main__":
    main()

"""Compare two versions paragraph by paragraph and write the result to a new Word report."""
import difflib
from pathlib import Path

from docx import Document
from docx.shared import Pt

OLD = Path("samples/doc_a.docx")
NEW = Path("samples/doc_b.docx")
OUT = Path("out_diff_report.docx")


def texts(path):
    doc = Document(path)
    lines = [p.text.strip() for p in doc.paragraphs if p.text.strip()]
    for table in doc.tables:
        for row in table.rows:
            lines.append(" | ".join(c.text.strip() for c in row.cells))
    return lines


def diff(old, new):
    sm = difflib.SequenceMatcher(a=old, b=new, autojunk=False)
    return [(tag, "\n".join(old[i1:i2]), "\n".join(new[j1:j2]))
            for tag, i1, i2, j1, j2 in sm.get_opcodes() if tag != "equal"]


def write_report(rows, out):
    doc = Document()  # new document from the built-in default template
    doc.add_heading("Version comparison", level=1)
    doc.add_paragraph("Old: %s / New: %s / Changes: %d" % (OLD.name, NEW.name, len(rows)))
    table = doc.add_table(rows=1, cols=3, style="Table Grid")
    for cell, label in zip(table.rows[0].cells, ("change", "old", "new")):
        cell.text = label
    for tag, a, b in rows:
        cells = table.add_row().cells
        cells[0].text, cells[1].text, cells[2].text = tag, a, b
    for row in table.rows:
        for cell in row.cells:
            for p in cell.paragraphs:
                for run in p.runs:
                    run.font.size = Pt(9)
    doc.save(out)


def main():
    if OUT.resolve() in (OLD.resolve(), NEW.resolve()):
        raise SystemExit("output must not overwrite an input")
    rows = diff(texts(OLD), texts(NEW))
    write_report(rows, OUT)
    print("changes:", len(rows))
    for tag, a, b in rows[:4]:
        print("%-7s | %s | %s" % (tag, a.replace("\n", " / ")[:40], b.replace("\n", " / ")[:40]))
    print("saved", OUT, "tables in report:", len(Document(OUT).tables))


if __name__ == "__main__":
    main()

"""Download a .docx from OneDrive/SharePoint with Microsoft Graph and summarize it in memory."""
import asyncio
import io
import os
from pathlib import Path

from azure.identity import DeviceCodeCredential
from docx import Document
from kiota_abstractions.base_request_configuration import RequestConfiguration
from msgraph import GraphServiceClient
from msgraph.generated.drives.item.items.item.content.content_request_builder import (
    ContentRequestBuilder,
)

SCOPES = ["Files.Read"]
FORMAT = os.environ.get("DOWNLOAD_FORMAT", "")  # "" = original file, "pdf" = converted copy


def summarize(data):
    """Count paragraphs, tables and headings in .docx bytes without touching the disk."""
    doc = Document(io.BytesIO(data))
    heads = [p.text for p in doc.paragraphs if p.style.name.startswith("Heading")]
    return {"paragraphs": len(doc.paragraphs), "tables": len(doc.tables),
            "headings": len(heads), "first_heading": heads[0] if heads else ""}


async def main():
    if FORMAT not in ("", "pdf"):
        raise SystemExit("DOWNLOAD_FORMAT must be empty or pdf")
    cred = DeviceCodeCredential(client_id=os.environ["CLIENT_ID"], tenant_id=os.environ["TENANT_ID"])
    client = GraphServiceClient(credentials=cred, scopes=SCOPES)
    item = client.drives.by_drive_id(os.environ["DRIVE_ID"]).items.by_drive_item_id(os.environ["ITEM_ID"])
    if FORMAT:
        query = ContentRequestBuilder.ContentRequestBuilderGetQueryParameters(format=FORMAT)
        data = await item.content.get(request_configuration=RequestConfiguration(query_parameters=query))
        out = Path("out_item.%s" % FORMAT)
        out.write_bytes(data)
        print("saved", out, len(data), "bytes")
        return
    data = await item.content.get()
    print(summarize(data))


if __name__ == "__main__":
    asyncio.run(main())