---
name: processing-docx
description: Creates, reads, and modifies Word documents (.docx, .dotx) with python-docx — paragraphs, headings, tables, images, styles — and reads them as Markdown via pandoc. Use when the user asks to create, open, read, edit, or fix a Word document, mentions .docx/.dotx files, or wants a report, memo, letter, or template in Word format. Do not use for PDFs, spreadsheets, Google Docs, or Markdown files.
---

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

# Processing DOCX

## When to use / when NOT to use
- **Use for:** creating, reading, or modifying `.docx` and `.dotx` files — text, headings, tables, images, styles.
- **Do NOT use for:** PDFs, spreadsheets, Google Docs (different API), or plain Markdown/text files.

## Quick reference

Default library: **python-docx**. Reading: **pandoc** first, python-docx as fallback. Escape hatch: unzip + edit `word/document.xml` + rezip for what python-docx can't do (tracked changes, comments).

**Create:**
```python
from docx import Document
doc = Document()
doc.add_heading("Quarterly Report", level=1)
doc.add_paragraph("Revenue grew 12% quarter over quarter.")
t = doc.add_table(rows=2, cols=2)
t.style = "Table Grid"
t.rows[0].cells[0].text = "Region"
doc.save("report.docx")
```

**Read (pandoc default, python-docx fallback):**
```bash
pandoc -t markdown report.docx -o report.md
```
```python
# fallback if pandoc is missing
from docx import Document
text = "\n".join(p.text for p in Document("report.docx").paragraphs)
```

**Modify:**
```python
from docx import Document
doc = Document("report.docx")
for p in doc.paragraphs:
    if "12%" in p.text:
        for run in p.runs:
            run.text = run.text.replace("12%", "14%")
doc.save("report.docx")
```

## Workflow
1. Classify the task: create / read / modify.
2. Read: try `pandoc -t markdown file.docx`; if pandoc is not installed, fall back to python-docx text extraction (note: fallback loses images and most formatting fidelity).
3. Create/modify with python-docx. When editing, reuse the document's existing styles (`doc.styles`) instead of hardcoding fonts.
4. For tracked changes or comments, python-docx cannot help: unzip the `.docx`, edit `word/document.xml`, rezip with the original file layout (see recipes).
5. Validate: re-open the saved file with `Document(path)` — if it raises, fix before delivering. Confirm expected paragraph/table counts.
6. Report the output path and what changed.

## Edge cases & failure modes
- **python-docx missing** → `pip install python-docx`. **pandoc missing** → `brew install pandoc` (macOS) / `apt-get install pandoc`; or use the python-docx fallback.
- **Corrupt / not a zip** → `Document()` raises `PackageNotFoundError`; report the file is not a valid docx, stop.
- **Password-protected document** → python-docx cannot decrypt; ask the user for an unprotected copy.
- **`.doc` (legacy binary)** → not supported by python-docx; convert first: `soffice --headless --convert-to docx file.doc`.
- **Large documents (hundreds of pages)** → python-docx loads the whole XML tree; fine to ~10k paragraphs, but prefer targeted XML edits for bulk find-and-replace across huge files.

## References
Deeper recipes (styles, images, headers/footers, find-and-replace across runs, XML escape hatch, conversion, gotchas): see [references/recipes.md](references/recipes.md).