docx

Word documents (.docx)

A .docx is a ZIP archive of XML parts. Two ways in, and picking the right one is most of the job:

Need	Route
Write a document, edit text, add tables/images/styles	python-docx (scripts/ here)
Tracked changes, comments, footnotes, content controls, anything python-docx has no API for	raw OOXML — scripts/ooxml.py unpack, edit the XML, pack

Never hand-write a whole .docx as XML from nothing. Start from a real file — either one python-docx produced or one the user supplied — and modify it.

Before editing an existing file, look at it

scripts/inspect_docx.py report.docx

Prints every paragraph with its index and style, every table with its dimensions, section/page setup, headers and footers, and the document's declared styles. Do this first on any file you did not create. Paragraph indices from this listing are what the editing recipes below address.

Creating a document

Write a short Python script using python-docx. The API worth remembering:

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

doc = Document()                      # or Document("template.docx") to build on one

doc.add_heading("Quarterly Report", level=1)
p = doc.add_paragraph("Ordinary body text. ")
run = p.add_run("Bold tail.")         # runs carry the character formatting
run.bold = True
p.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

table = doc.add_table(rows=1, cols=3)
table.style = "Table Grid"            # without a style the table has NO borders
hdr = table.rows[0].cells
hdr[0].text, hdr[1].text, hdr[2].text = "Region", "Q1", "Q2"
for region, q1, q2 in data:
    cells = table.add_row().cells
    cells[0].text = region
    cells[1].text = f"{q1:,.0f}"

doc.add_picture("chart.png", width=Inches(6))
doc.add_page_break()
doc.save("report.docx")

Points that cost time if you learn them the hard way:

• All measurements are typed. Pt, Inches, Cm, Emu — never a bare number. Internally everything is EMU (914400 per inch).
• Formatting lives on runs, not paragraphs. paragraph.text = "x" destroys the paragraph's runs and their formatting. To change text while keeping formatting, assign to run.text on the existing runs.
• A table with no .style has no visible borders. "Table Grid" is the usual intent.
• Styles must already exist in the document. Building on a user's template inherits their styles; Document() gives you the default set. Check with inspect_docx.py before referencing a style by name.
• add_heading(level=0) produces a Title, not a heading.