Word Documents with python-docx

💡 Key concepts

• Object model: Document → paragraphs → runs (text with the same formatting) and tables → rows → cells. Sections hold headers and footers.

  from docx import Document
  from docx.shared import Inches, Pt
  
  doc = Document("Status_Report_TEMPLATE.docx")      # uses the template's styles
  doc.add_heading("PRG-002 IRONWOOD Tactical Network: Monthly Status", level=1)
  p = doc.add_paragraph("Overall cost performance is ")
  p.add_run("AMBER").bold = True
  p.add_run(f" (CPI {cpi:.2f}).")
  table = doc.add_table(rows=1, cols=4)
  table.style = "Table Grid"                          # the style must exist in the template
  for cell, text in zip(table.rows[0].cells, ["Milestone", "Baseline", "Forecast", "Slip (days)"]):
      cell.text = text
  for m in late_milestones.itertuples():
      row = table.add_row().cells
      row[0].text, row[1].text, row[2].text, row[3].text = m.MilestoneName, f"{m.BaselineDate:%d %b %Y}", f"{m.ForecastDate:%d %b %Y}", str(m.SlipDays)
  doc.add_picture("scurve_PRG-002.png", width=Inches(6))
  doc.save("PRG-002_Status_2026-09.docx")
  

• Styles come from the template: Build Status_Report_TEMPLATE.docx in Word with your organization's fonts, heading styles, table styles, header/footer, and portion-marking/banner placeholders as required by your organization's marking guidance. (Use only fictional or unclassified training markings in practice.)
• Placeholder replacement gotcha: Word often splits {{PROGRAM_NAME}} across several runs, so a simple run-level replace misses it. Solutions: type placeholders in one go and clear formatting, replace at paragraph level (then rebuild runs), or use the docxtpl library (Jinja2 templates for docx, built on python-docx).
• Cell shading and advanced formatting: Some features (cell background color) need low-level XML (docx.oxml). Write a small helper function once and reuse it.
• Narrative generation from data: rule-based text, e.g. "CPI declined from 0.96 to 0.91 over 3 months, driven by WBS 1.3 (Hull Integration)."

🛠 Hands-on exercise: One-Program Status Report

Data: EVM snapshot (4.3), milestones (MilestoneName, BaselineDate, ForecastDate, ActualDate, SlipDays, Status), risks (Title, Likelihood, Consequence, Status, Owner), contracts (ContractNumber, Vendor, ContractType, CeilingValue, ObligatedToDate, PoPEnd).

1. Create a Word template with styles and a header/footer containing "FICTIONAL TRAINING DATA".
2. Generate a document for PRG-002 with: title, "Data as of" line, an executive summary paragraph (rule-based RAG text), an EVM metrics table, an S-curve image (matplotlib → PNG → add_picture), a late milestones table, top 5 risks, and contract status.
3. Add page numbers in the footer (python-docx needs a field-code XML snippet. Find it in the docs/community examples and wrap it in a helper.)

📦 Mini-project: Placeholder Engine

Write fill_template(doc_path, mapping: dict, out_path) that replaces {{KEY}} placeholders across body paragraphs, tables, headers, and footers, including placeholders split across runs. Test it with a template containing 10 placeholders. (Then compare with doing the same in docxtpl and write a short note on when you'd use each.)