<!--
Author: Simon-Pierre Boucher
Contact: contact@spboucher.ai
-->

# DOCX Recipes — python-docx (+ pandoc, raw XML)

## Contents
- Create with formatting (styles, fonts, page setup, images, headers/footers)
- Tables
- Read / extract (text, tables, structure)
- Modify (find-and-replace across runs, insert/delete paragraphs)
- Raw-XML escape hatch (tracked changes, comments)
- Convert (docx ↔ markdown/pdf)
- Gotchas

## Create with formatting

```python
from docx import Document
from docx.shared import Pt, Inches, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH

doc = Document()

# Page setup — US Letter (python-docx defaults to the template's size)
section = doc.sections[0]
section.page_width, section.page_height = Inches(8.5), Inches(11)
section.left_margin = section.right_margin = Inches(1)

# Built-in styles: use them so a table of contents works
doc.add_heading("Title of Report", level=0)      # style "Title"
doc.add_heading("Introduction", level=1)         # style "Heading 1"

p = doc.add_paragraph("Body text with ")
run = p.add_run("bold emphasis")
run.bold = True
run.font.size = Pt(11)
run.font.color.rgb = RGBColor(0x44, 0x72, 0xC4)
p.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

# Bullets and numbers come from styles, never literal characters
doc.add_paragraph("First point", style="List Bullet")
doc.add_paragraph("Step one", style="List Number")

# Image, sized by width (height scales proportionally)
doc.add_picture("chart.png", width=Inches(5))

# Header/footer
doc.sections[0].header.paragraphs[0].text = "Confidential"
doc.sections[0].footer.paragraphs[0].text = "Page footer"

doc.save("report.docx")
```

## Tables

```python
table = doc.add_table(rows=1, cols=3)
table.style = "Table Grid"                       # built-in style name
hdr = table.rows[0].cells
for i, h in enumerate(["Region", "Q1", "Q2"]):
    hdr[i].text = h
    hdr[i].paragraphs[0].runs[0].bold = True
for region, q1, q2 in [("East", "100", "150")]:
    row = table.add_row().cells
    row[0].text, row[1].text, row[2].text = region, q1, q2

# Merge cells
a = table.cell(0, 0); b = table.cell(0, 1)
merged = a.merge(b)
```

## Read / extract

```python
from docx import Document
doc = Document("report.docx")

# All body text in order (paragraphs only — table text is separate)
text = "\n".join(p.text for p in doc.paragraphs)

# Tables → list of rows
tables = [[[cell.text for cell in row.cells] for row in t.rows] for t in doc.tables]

# Structure: headings with levels
outline = [(p.style.name, p.text) for p in doc.paragraphs if p.style.name.startswith("Heading")]
```

Full-fidelity read: `pandoc -t markdown report.docx` (keeps headings, lists, tables, links).

## Modify

**Find-and-replace — the run-splitting problem.** Word splits a paragraph's text into runs at arbitrary points, so a target string often spans runs. Safe pattern: operate at paragraph level, rebuild runs only when the paragraph actually matches.

```python
def replace_in_paragraph(p, old, new):
    if old not in p.text:
        return
    # Concatenate, replace, put everything in the first run, empty the rest.
    # Trade-off: intra-paragraph formatting collapses to the first run's format.
    full = p.text.replace(old, new)
    for run in p.runs:
        run.text = ""
    if p.runs:
        p.runs[0].text = full
    else:
        p.add_run(full)

doc = Document("report.docx")
for p in doc.paragraphs:
    replace_in_paragraph(p, "FY2025", "FY2026")
for t in doc.tables:
    for row in t.rows:
        for cell in row.cells:
            for p in cell.paragraphs:
                replace_in_paragraph(p, "FY2025", "FY2026")
doc.save("report.docx")
```

**Insert/delete paragraphs:**
```python
# Insert before an existing paragraph
target = doc.paragraphs[3]
new_p = target.insert_paragraph_before("Inserted text", style="Normal")

# Delete: python-docx has no API — remove the XML element
p = doc.paragraphs[5]
p._element.getparent().remove(p._element)
```

## Raw-XML escape hatch

For tracked changes (`w:ins`/`w:del`), comments, or anything python-docx lacks:

```bash
mkdir unpacked && cd unpacked && unzip -o ../report.docx
# edit word/document.xml (and word/comments.xml for comments)
zip -r ../report-edited.docx . -x '.*'   # zip from inside so paths stay relative
```

Accept all tracked changes = keep `w:ins` content (strip the wrapper tag), delete `w:del` elements entirely. Validate the result opens: `python3 -c "from docx import Document; Document('report-edited.docx')"`.

## Convert

```bash
pandoc report.md -o report.docx              # markdown → docx
pandoc -t markdown report.docx -o report.md  # docx → markdown
soffice --headless --convert-to pdf report.docx   # docx → pdf
soffice --headless --convert-to docx legacy.doc   # .doc → .docx
```

## Gotchas

- **python-docx cannot read or write tracked changes, comments, or fields** (page numbers, TOC field codes) — use the XML escape hatch.
- **A TOC inserted programmatically shows empty until Word/LibreOffice refreshes fields**; headings must use built-in `Heading N` styles for it to populate.
- **Runs split unpredictably** — never assume one run per paragraph; see the find-and-replace pattern above.
- **`doc.paragraphs` skips text inside tables, headers, footers, and text boxes** — iterate those containers separately.
- **New documents inherit the bundled default template** (Calibri, A4 in some builds); set page size and margins explicitly when layout matters.
- **Style names are English built-ins** ("Heading 1", "Table Grid") regardless of Word's UI language; a missing custom style raises `KeyError` on use.
- **`.dotx` templates:** open normally, but save as `.docx` unless the user wants a template back.