# 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.

# 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:

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):

pandoc -t markdown report.docx -o report.md

# fallback if pandoc is missing
from docx import Document
text = "\n".join(p.text for p in Document("report.docx").paragraphs)

Modify:

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.