Python-docx Word Document Automation Skill

Overview

Python-docx is a Python library for creating and manipulating Microsoft Word (.docx) documents. This skill covers comprehensive patterns for document automation including:

• Document creation from scratch or templates

• Paragraph formatting with styles, fonts, and alignment

• Table generation with merged cells, styles, and formatting

• Headers and footers with page numbers and dynamic content

• Image insertion with sizing and positioning

• Style management for consistent document appearance

• Template manipulation for document workflows

• Mail merge patterns for bulk document generation

When to Use This Skill

USE when:

• Creating Word documents programmatically from data

• Generating reports with consistent formatting

• Building contracts, invoices, or legal documents

• Automating template-based document creation

• Modifying existing Word documents

• Creating documents with complex table structures

• Generating technical documentation with code blocks

• Building multi-section documents with headers/footers

• Creating documents with embedded images and charts

• Batch processing document generation

DON'T USE when:

• Simple template filling (use docx-templates instead)

• PDF generation is the final output (use pypdf or reportlab)

• Need real-time collaborative editing

• Document requires complex macros or VBA

• Need to preserve complex Word features (use COM automation on Windows)

• Only need to extract text from documents (use python-docx2txt)

Prerequisites

Installation

Using pip

pip install python-docx

Using uv (recommended)

uv pip install python-docx

With image support

pip install python-docx Pillow

Full installation with all optional dependencies

pip install python-docx Pillow lxml

Verify Installation

from docx import Document from docx.shared import Inches, Pt, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.enum.table import WD_TABLE_ALIGNMENT

print("python-docx installed successfully!")

Core Capabilities

1. Basic Document Creation

""" Create a basic Word document with title, paragraphs, and formatting. """ from docx import Document from docx.shared import Inches, Pt, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING from docx.oxml.ns import qn from docx.oxml import OxmlElement

def create_basic_document(output_path: str) -> None: """Create a basic document with common elements.""" # Create new document doc = Document()

# Set document properties
core_properties = doc.core_properties
core_properties.author = "Document Generator"
core_properties.title = "Sample Report"
core_properties.subject = "Automated Document Generation"

# Add title with formatting
title = doc.add_heading('Monthly Performance Report', level=0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER

# Add subtitle paragraph
subtitle = doc.add_paragraph()
subtitle_run = subtitle.add_run('January 2026')
subtitle_run.font.size = Pt(14)
subtitle_run.font.italic = True
subtitle.alignment = WD_ALIGN_PARAGRAPH.CENTER

# Add section heading
doc.add_heading('Executive Summary', level=1)

# Add paragraph with multiple runs (different formatting)
para = doc.add_paragraph()
para.add_run('This report summarizes ').font.size = Pt(11)
bold_run = para.add_run('key performance metrics')
bold_run.bold = True
bold_run.font.size = Pt(11)
para.add_run(' for the month of January 2026.')

# Add bullet points
doc.add_heading('Key Highlights', level=2)

bullets = [
    'Revenue increased by 15% compared to last month',
    'Customer satisfaction score reached 92%',
    'New user registrations up 25%',
    'Support ticket resolution time reduced by 10%'
]

for bullet in bullets:
    para = doc.add_paragraph(bullet, style='List Bullet')

# Add numbered list
doc.add_heading('Action Items', level=2)

actions = [
    'Review Q1 budget allocation',
    'Schedule team performance reviews',
    'Finalize marketing campaign for Q2'
]

for action in actions:
    doc.add_paragraph(action, style='List Number')

# Save document
doc.save(output_path)
print(f"Document saved to {output_path}")

Usage

create_basic_document('basic_report.docx')

2. Advanced Paragraph Formatting

""" Advanced paragraph formatting with custom styles, spacing, and indentation. """ from docx import Document from docx.shared import Pt, Inches, Cm, Twips from docx.enum.text import WD_ALIGN_PARAGRAPH, WD_LINE_SPACING, WD_TAB_ALIGNMENT from docx.enum.style import WD_STYLE_TYPE from docx.oxml.ns import nsdecls from docx.oxml import parse_xml

def create_formatted_document(output_path: str) -> None: """Create document with advanced paragraph formatting.""" doc = Document()

# Create custom style
styles = doc.styles

# Create paragraph style
custom_style = styles.add_style('CustomBody', WD_STYLE_TYPE.PARAGRAPH)
custom_style.font.name = 'Calibri'
custom_style.font.size = Pt(11)
custom_style.paragraph_format.space_before = Pt(6)
custom_style.paragraph_format.space_after = Pt(6)
custom_style.paragraph_format.line_spacing = 1.15

# Create character style for highlighting
highlight_style = styles.add_style('Highlight', WD_STYLE_TYPE.CHARACTER)
highlight_style.font.bold = True
highlight_style.font.color.rgb = None  # Will use theme color

# Add heading
doc.add_heading('Document Formatting Examples', level=0)

# Paragraph with custom alignment and spacing
doc.add_heading('Text Alignment', level=1)

# Left aligned (default)
para_left = doc.add_paragraph('Left aligned text (default)')
para_left.alignment = WD_ALIGN_PARAGRAPH.LEFT

# Center aligned
para_center = doc.add_paragraph('Center aligned text')
para_center.alignment = WD_ALIGN_PARAGRAPH.CENTER

# Right aligned
para_right = doc.add_paragraph('Right aligned text')
para_right.alignment = WD_ALIGN_PARAGRAPH.RIGHT

# Justified
para_justified = doc.add_paragraph(
    'Justified text spreads evenly across the line width. '
    'This is useful for formal documents and reports where '
    'a clean, professional appearance is desired.'
)
para_justified.alignment = WD_ALIGN_PARAGRAPH.JUSTIFY

# Line spacing examples
doc.add_heading('Line Spacing', level=1)

# Single spacing
single_para = doc.add_paragraph(
    'Single spaced paragraph. Line spacing is set to 1.0 '
    'which means the lines are close together.'
)
single_para.paragraph_format.line_spacing = 1.0

# 1.5 spacing
one_half_para = doc.add_paragraph(
    'One and a half spaced paragraph. Line spacing is set to 1.5 '
    'which provides moderate spacing between lines.'
)
one_half_para.paragraph_format.line_spacing = 1.5

# Double spacing
double_para = doc.add_paragraph(
    'Double spaced paragraph. Line spacing is set to 2.0 '
    'which is common for academic and legal documents.'
)
double_para.paragraph_format.line_spacing = 2.0

# Indentation examples
doc.add_heading('Indentation', level=1)

# First line indent
first_indent = doc.add_paragraph(
    'This paragraph has a first line indent. The first line starts '
    'further to the right than subsequent lines, which is a common '
    'style for body text in books and formal documents.'
)
first_indent.paragraph_format.first_line_indent = Inches(0.5)

# Left indent (block indent)
left_indent = doc.add_paragraph(
    'This paragraph has a left indent applied. The entire paragraph '
    'is shifted to the right, which is useful for quotations or '
    'secondary information.'
)
left_indent.paragraph_format.left_indent = Inches(0.75)

# Right indent
right_indent = doc.add_paragraph(
    'This paragraph has a right indent. The right edge of the text '
    'is moved inward from the page margin.'
)
right_indent.paragraph_format.right_indent = Inches(0.75)

# Hanging indent (for references/bibliography)
hanging = doc.add_paragraph(
    'Smith, J. (2026). The Complete Guide to Document Automation. '
    'Publisher Name. This is an example of a hanging indent commonly '
    'used in bibliographies and reference lists.'
)
hanging.paragraph_format.left_indent = Inches(0.5)
hanging.paragraph_format.first_line_indent = Inches(-0.5)

# Font formatting examples
doc.add_heading('Font Formatting', level=1)

font_para = doc.add_paragraph()

# Normal text
font_para.add_run('Normal text, ')

# Bold
bold_run = font_para.add_run('bold text, ')
bold_run.bold = True

# Italic
italic_run = font_para.add_run('italic text, ')
italic_run.italic = True

# Underline
underline_run = font_para.add_run('underlined text, ')
underline_run.underline = True

# Strikethrough
strike_run = font_para.add_run('strikethrough text, ')
strike_run.font.strike = True

# Subscript
font_para.add_run('H')
sub_run = font_para.add_run('2')
sub_run.font.subscript = True
font_para.add_run('O, ')

# Superscript
font_para.add_run('E=mc')
sup_run = font_para.add_run('2')
sup_run.font.superscript = True

# Different font sizes
doc.add_heading('Font Sizes', level=2)

sizes_para = doc.add_paragraph()
for size in [8, 10, 12, 14, 16, 18, 24]:
    run = sizes_para.add_run(f'{size}pt ')
    run.font.size = Pt(size)

# Save document
doc.save(output_path)
print(f"Formatted document saved to {output_path}")

create_formatted_document('formatted_document.docx')

3. Table Creation and Formatting

""" Create and format tables with merged cells, styles, and custom formatting. """ from docx import Document from docx.shared import Inches, Pt, Cm, Twips from docx.enum.table import WD_TABLE_ALIGNMENT, WD_ROW_HEIGHT_RULE from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.oxml.ns import nsdecls, qn from docx.oxml import parse_xml, OxmlElement from typing import List, Dict, Any, Optional

def set_cell_shading(cell, color: str) -> None: """Set cell background color.""" shading_elm = OxmlElement('w:shd') shading_elm.set(qn('w:fill'), color) cell._tc.get_or_add_tcPr().append(shading_elm)

def set_cell_borders(cell, border_color: str = "000000", border_size: int = 4) -> None: """Set cell borders.""" tc = cell._tc tcPr = tc.get_or_add_tcPr() tcBorders = OxmlElement('w:tcBorders')

for border_name in ['top', 'left', 'bottom', 'right']:
    border = OxmlElement(f'w:{border_name}')
    border.set(qn('w:val'), 'single')
    border.set(qn('w:sz'), str(border_size))
    border.set(qn('w:color'), border_color)
    tcBorders.append(border)

tcPr.append(tcBorders)

def create_data_table( doc: Document, headers: List[str], data: List[List[Any]], header_color: str = "4472C4", alternate_row_color: Optional[str] = "D9E2F3" ) -> None: """Create a formatted data table with headers and styling.""" # Create table table = doc.add_table(rows=1, cols=len(headers)) table.alignment = WD_TABLE_ALIGNMENT.CENTER

# Style header row
header_cells = table.rows[0].cells
for i, header in enumerate(headers):
    cell = header_cells[i]
    cell.text = header

    # Format header cell
    set_cell_shading(cell, header_color)

    # Format text
    paragraph = cell.paragraphs[0]
    paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = paragraph.runs[0]
    run.font.bold = True
    run.font.color.rgb = None  # White text
    run.font.size = Pt(11)

# Add data rows
for row_idx, row_data in enumerate(data):
    row = table.add_row()

    for col_idx, value in enumerate(row_data):
        cell = row.cells[col_idx]
        cell.text = str(value)

        # Alternate row shading
        if alternate_row_color and row_idx % 2 == 0:
            set_cell_shading(cell, alternate_row_color)

        # Center align numbers
        if isinstance(value, (int, float)):
            cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.RIGHT

return table

def create_merged_header_table(doc: Document) -> None: """Create table with merged cells for complex headers.""" # Create 5x4 table table = doc.add_table(rows=5, cols=4) table.style = 'Table Grid'

# Merge cells for main header
top_left = table.cell(0, 0)
top_right = table.cell(0, 3)
top_left.merge(top_right)
top_left.text = "Quarterly Sales Report 2026"
top_left.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER
top_left.paragraphs[0].runs[0].bold = True
set_cell_shading(top_left, "2F5496")

# Merge cells for category headers
# Q1-Q2 header
q1_q2 = table.cell(1, 1)
q1_q2_end = table.cell(1, 2)
q1_q2.merge(q1_q2_end)
q1_q2.text = "First Half"
q1_q2.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER
set_cell_shading(q1_q2, "5B9BD5")

# Q3-Q4 header
table.cell(1, 3).text = "Q3-Q4"
set_cell_shading(table.cell(1, 3), "5B9BD5")

# Product header (merged vertically)
table.cell(1, 0).text = "Product"
set_cell_shading(table.cell(1, 0), "5B9BD5")

# Sub-headers
sub_headers = ['', 'Q1', 'Q2', 'Total']
for i, header in enumerate(sub_headers):
    cell = table.cell(2, i)
    cell.text = header
    set_cell_shading(cell, "BDD7EE")

# Data rows
data = [
    ['Widget A', '100', '150', '250'],
    ['Widget B', '200', '180', '380']
]

for row_idx, row_data in enumerate(data, start=3):
    for col_idx, value in enumerate(row_data):
        table.cell(row_idx, col_idx).text = value

def create_document_with_tables(output_path: str) -> None: """Create document with various table examples.""" doc = Document()

doc.add_heading('Table Examples', level=0)

# Simple data table
doc.add_heading('Sales Data', level=1)

headers = ['Product', 'Q1 Sales', 'Q2 Sales', 'Q3 Sales', 'Q4 Sales', 'Total']
data = [
    ['Laptop Pro', 150, 175, 200, 225, 750],
    ['Desktop Ultra', 80, 95, 110, 130, 415],
    ['Monitor HD', 200, 220, 240, 260, 920],
    ['Keyboard Elite', 500, 520, 540, 580, 2140],
]

create_data_table(doc, headers, data)

doc.add_paragraph()  # Spacing

# Merged header table
doc.add_heading('Complex Table with Merged Cells', level=1)
create_merged_header_table(doc)

doc.add_paragraph()

# Table with specific column widths
doc.add_heading('Table with Custom Column Widths', level=1)

table = doc.add_table(rows=4, cols=3)
table.style = 'Table Grid'

# Set column widths
widths = [Inches(1.5), Inches(3.0), Inches(1.5)]
for row in table.rows:
    for idx, (cell, width) in enumerate(zip(row.cells, widths)):
        cell.width = width

# Add content
headers = ['ID', 'Description', 'Status']
for i, header in enumerate(headers):
    cell = table.rows[0].cells[i]
    cell.text = header
    cell.paragraphs[0].runs[0].bold = True
    set_cell_shading(cell, "E7E6E6")

data = [
    ['001', 'Implement new feature for document generation', 'Complete'],
    ['002', 'Review and approve design specifications', 'In Progress'],
    ['003', 'Deploy to production environment', 'Pending'],
]

for row_idx, row_data in enumerate(data, start=1):
    for col_idx, value in enumerate(row_data):
        table.rows[row_idx].cells[col_idx].text = value

doc.save(output_path)
print(f"Table document saved to {output_path}")

create_document_with_tables('table_examples.docx')

4. Headers, Footers, and Page Setup

""" Configure headers, footers, page numbers, and page setup. """ from docx import Document from docx.shared import Inches, Pt, Cm from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.enum.section import WD_ORIENT from docx.oxml.ns import qn from docx.oxml import OxmlElement

def add_page_number(paragraph) -> None: """Add page number field to paragraph.""" run = paragraph.add_run() fldChar1 = OxmlElement('w:fldChar') fldChar1.set(qn('w:fldCharType'), 'begin')

instrText = OxmlElement('w:instrText')
instrText.set(qn('xml:space'), 'preserve')
instrText.text = "PAGE"

fldChar2 = OxmlElement('w:fldChar')
fldChar2.set(qn('w:fldCharType'), 'separate')

fldChar3 = OxmlElement('w:fldChar')
fldChar3.set(qn('w:fldCharType'), 'end')

run._r.append(fldChar1)
run._r.append(instrText)
run._r.append(fldChar2)
run._r.append(fldChar3)

def add_total_pages(paragraph) -> None: """Add total page count field to paragraph.""" run = paragraph.add_run() fldChar1 = OxmlElement('w:fldChar') fldChar1.set(qn('w:fldCharType'), 'begin')

instrText = OxmlElement('w:instrText')
instrText.set(qn('xml:space'), 'preserve')
instrText.text = "NUMPAGES"

fldChar2 = OxmlElement('w:fldChar')
fldChar2.set(qn('w:fldCharType'), 'separate')

fldChar3 = OxmlElement('w:fldChar')
fldChar3.set(qn('w:fldCharType'), 'end')

run._r.append(fldChar1)
run._r.append(instrText)
run._r.append(fldChar2)
run._r.append(fldChar3)

def create_document_with_headers_footers(output_path: str) -> None: """Create document with headers, footers, and page numbers.""" doc = Document()

# Access the default section
section = doc.sections[0]

# Set page margins
section.top_margin = Inches(1)
section.bottom_margin = Inches(1)
section.left_margin = Inches(1.25)
section.right_margin = Inches(1.25)

# Set page size (Letter)
section.page_width = Inches(8.5)
section.page_height = Inches(11)

# Configure header
header = section.header
header_para = header.paragraphs[0]

# Add company logo placeholder and title
header_para.text = "ACME Corporation"
header_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
header_run = header_para.runs[0]
header_run.bold = True
header_run.font.size = Pt(14)

# Add subtitle to header
subtitle_para = header.add_paragraph()
subtitle_para.text = "Confidential Document"
subtitle_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
subtitle_para.runs[0].font.size = Pt(10)
subtitle_para.runs[0].italic = True

# Configure footer with page numbers
footer = section.footer
footer_para = footer.paragraphs[0]
footer_para.alignment = WD_ALIGN_PARAGRAPH.CENTER

# Add "Page X of Y" format
footer_para.add_run("Page ")
add_page_number(footer_para)
footer_para.add_run(" of ")
add_total_pages(footer_para)

# Add document content
doc.add_heading('Document Title', level=0)

# Add multiple paragraphs to create multiple pages
for i in range(1, 4):
    doc.add_heading(f'Section {i}', level=1)
    for j in range(5):
        doc.add_paragraph(
            f'This is paragraph {j+1} of section {i}. '
            'Lorem ipsum dolor sit amet, consectetur adipiscing elit. '
            'Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. '
            'Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.'
        )

    # Add page break after each section (except last)
    if i < 3:
        doc.add_page_break()

doc.save(output_path)
print(f"Document with headers/footers saved to {output_path}")

def create_landscape_document(output_path: str) -> None: """Create document with landscape orientation.""" doc = Document()

section = doc.sections[0]

# Set landscape orientation
section.orientation = WD_ORIENT.LANDSCAPE

# Swap width and height for landscape
new_width = section.page_height
new_height = section.page_width
section.page_width = new_width
section.page_height = new_height

# Add content
doc.add_heading('Wide Format Report', level=0)
doc.add_paragraph('This document is in landscape orientation, ideal for wide tables.')

# Add wide table
table = doc.add_table(rows=5, cols=8)
table.style = 'Table Grid'

headers = ['ID', 'Name', 'Q1', 'Q2', 'Q3', 'Q4', 'Total', 'Growth']
for i, header in enumerate(headers):
    table.rows[0].cells[i].text = header

doc.save(output_path)
print(f"Landscape document saved to {output_path}")

create_document_with_headers_footers('headers_footers.docx') create_landscape_document('landscape_report.docx')

5. Image Insertion and Positioning

""" Insert and position images in Word documents. """ from docx import Document from docx.shared import Inches, Pt, Cm, Emu from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.oxml.ns import qn from docx.oxml import OxmlElement from pathlib import Path from io import BytesIO from typing import Optional, Tuple import requests

def add_image_from_url(doc: Document, url: str, width: Optional[float] = None) -> None: """Add image from URL to document.""" response = requests.get(url) image_stream = BytesIO(response.content)

if width:
    doc.add_picture(image_stream, width=Inches(width))
else:
    doc.add_picture(image_stream)

def add_image_with_caption( doc: Document, image_path: str, caption: str, width: float = 4.0, figure_num: int = 1 ) -> None: """Add image with centered caption below.""" # Add image para = doc.add_paragraph() para.alignment = WD_ALIGN_PARAGRAPH.CENTER run = para.add_run() run.add_picture(image_path, width=Inches(width))

# Add caption
caption_para = doc.add_paragraph()
caption_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
caption_run = caption_para.add_run(f'Figure {figure_num}: {caption}')
caption_run.italic = True
caption_run.font.size = Pt(10)

def add_inline_image(paragraph, image_path: str, width: float = 1.0) -> None: """Add image inline with text.""" run = paragraph.add_run() run.add_picture(image_path, width=Inches(width))

def create_document_with_images(output_path: str, sample_image_path: str) -> None: """Create document with various image placements.""" doc = Document()

doc.add_heading('Image Examples', level=0)

# Check if sample image exists
if not Path(sample_image_path).exists():
    # Create a placeholder message if no image
    doc.add_paragraph(
        'Note: Sample image not found. Replace with actual image path.'
    )
    doc.save(output_path)
    return

# Simple centered image
doc.add_heading('Centered Image', level=1)
doc.add_paragraph('The image below is centered on the page:')

img_para = doc.add_paragraph()
img_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
run = img_para.add_run()
run.add_picture(sample_image_path, width=Inches(4))

# Image with caption
doc.add_heading('Image with Caption', level=1)
doc.add_paragraph('Images can include descriptive captions:')
add_image_with_caption(
    doc,
    sample_image_path,
    'Sample chart showing quarterly results',
    width=4.0,
    figure_num=1
)

# Multiple images in a row (using table)
doc.add_heading('Multiple Images Side by Side', level=1)
doc.add_paragraph('Use tables to arrange images side by side:')

# Create 1x3 table for images
table = doc.add_table(rows=2, cols=3)

for i in range(3):
    cell = table.cell(0, i)
    para = cell.paragraphs[0]
    para.alignment = WD_ALIGN_PARAGRAPH.CENTER
    run = para.add_run()
    run.add_picture(sample_image_path, width=Inches(1.8))

    # Add caption below each image
    caption_cell = table.cell(1, i)
    caption_cell.paragraphs[0].text = f'Image {i + 1}'
    caption_cell.paragraphs[0].alignment = WD_ALIGN_PARAGRAPH.CENTER

# Inline image with text
doc.add_heading('Inline Images', level=1)
para = doc.add_paragraph('You can include small images ')
run = para.add_run()
run.add_picture(sample_image_path, width=Inches(0.5))
para.add_run(' inline with your text for icons or small graphics.')

doc.save(output_path)
print(f"Document with images saved to {output_path}")

Usage (provide path to actual image)

create_document_with_images('image_document.docx', 'sample_chart.png')

6. Style Management and Custom Styles

""" Create and manage document styles for consistent formatting. """ from docx import Document from docx.shared import Pt, Inches, RGBColor from docx.enum.style import WD_STYLE_TYPE from docx.enum.text import WD_ALIGN_PARAGRAPH from docx.oxml.ns import qn from docx.oxml import OxmlElement from typing import Dict, Any

def create_custom_styles(doc: Document) -> Dict[str, Any]: """Create a set of custom styles for the document.""" styles = doc.styles created_styles = {}

# Custom Heading 1
if 'CustomHeading1' not in [s.name for s in styles]:
    h1_style = styles.add_style('CustomHeading1', WD_STYLE_TYPE.PARAGRAPH)
    h1_style.base_style = styles['Heading 1']
    h1_style.font.name = 'Georgia'
    h1_style.font.size = Pt(18)
    h1_style.font.bold = True
    h1_style.font.color.rgb = RGBColor(0x2E, 0x74, 0xB5)
    h1_style.paragraph_format.space_before = Pt(24)
    h1_style.paragraph_format.space_after = Pt(12)
    created_styles['heading1'] = h1_style

# Custom Heading 2
if 'CustomHeading2' not in [s.name for s in styles]:
    h2_style = styles.add_style('CustomHeading2', WD_STYLE_TYPE.PARAGRAPH)
    h2_style.base_style = styles['Heading 2']
    h2_style.font.name = 'Georgia'
    h2_style.font.size = Pt(14)
    h2_style.font.bold = True
    h2_style.font.color.rgb = RGBColor(0x2E, 0x74, 0xB5)
    h2_style.paragraph_format.space_before = Pt(18)
    h2_style.paragraph_format.space_after = Pt(6)
    created_styles['heading2'] = h2_style

# Custom Body Text
if 'CustomBody' not in [s.name for s in styles]:
    body_style = styles.add_style('CustomBody', WD_STYLE_TYPE.PARAGRAPH)
    body_style.font.name = 'Calibri'
    body_style.font.size = Pt(11)
    body_style.paragraph_format.space_after = Pt(8)
    body_style.paragraph_format.line_spacing = 1.15
    body_style.paragraph_format.first_line_indent = Inches(0.25)
    created_styles['body'] = body_style

# Custom Quote
if 'CustomQuote' not in [s.name for s in styles]:
    quote_style = styles.add_style('CustomQuote', WD_STYLE_TYPE.PARAGRAPH)
    quote_style.font.name = 'Calibri'
    quote_style.font.size = Pt(11)
    quote_style.font.italic = True
    quote_style.font.color.rgb = RGBColor(0x59, 0x59, 0x59)
    quote_style.paragraph_format.left_indent = Inches(0.5)
    quote_style.paragraph_format.right_indent = Inches(0.5)
    quote_style.paragraph_format.space_before = Pt(12)
    quote_style.paragraph_format.space_after = Pt(12)
    created_styles['quote'] = quote_style

# Code Block Style
if 'CodeBlock' not in [s.name for s in styles]:
    code_style = styles.add_style('CodeBlock', WD_STYLE_TYPE.PARAGRAPH)
    code_style.font.name = 'Consolas'
    code_style.font.size = Pt(10)
    code_style.paragraph_format.space_before = Pt(6)
    code_style.paragraph_format.space_after = Pt(6)
    code_style.paragraph_format.left_indent = Inches(0.25)
    created_styles['code'] = code_style

# Highlight Character Style
if 'Highlight' not in [s.name for s in styles]:
    highlight_style = styles.add_style('Highlight', WD_STYLE_TYPE.CHARACTER)
    highlight_style.font.bold = True
    highlight_style.font.color.rgb = RGBColor(0xC0, 0x00, 0x00)
    created_styles['highlight'] = highlight_style

return created_styles

def create_styled_document(output_path: str) -> None: """Create document using custom styles.""" doc = Document()

# Create custom styles
create_custom_styles(doc)

# Use custom styles
doc.add_paragraph('Technical Report', style='CustomHeading1')

doc.add_paragraph('Introduction', style='CustomHeading2')

intro = doc.add_paragraph(
    'This document demonstrates the use of custom styles for consistent '
    'formatting throughout the document. Custom styles allow you to define '
    'formatting once and apply it consistently.',
    style='CustomBody'
)

doc.add_paragraph('Key Concepts', style='CustomHeading2')

doc.add_paragraph(
    'Style management is essential for professional documents. '
    'It ensures consistency and makes global formatting changes easy.',
    style='CustomBody'
)

# Add quote
doc.add_paragraph(
    '"Good typography is invisible. Bad typography is everywhere." - Oliver Reichenstein',
    style='CustomQuote'
)

doc.add_paragraph('Code Example', style='CustomHeading2')

# Add code block
code = """def hello_world():
print("Hello, World!")
return True"""

doc.add_paragraph(code, style='CodeBlock')

doc.add_paragraph('Conclusion', style='CustomHeading2')

conclusion = doc.add_paragraph(style='CustomBody')
conclusion.add_run('Custom styles provide ')
highlight_run = conclusion.add_run('powerful formatting control')
highlight_run.style = 'Highlight'
conclusion.add_run(' for document automation.')

doc.save(output_path)
print(f"Styled document saved to {output_path}")

create_styled_document('styled_document.docx')

Integration Examples

Report Generation from Database

""" Generate reports from database query results. """ from docx import Document from docx.shared import Inches, Pt from docx.enum.text import WD_ALIGN_PARAGRAPH from datetime import datetime from typing import List, Dict, Any import sqlite3

def generate_database_report( db_path: str, query: str, output_path: str, title: str = "Database Report" ) -> None: """Generate Word report from database query.""" # Connect and fetch data conn = sqlite3.connect(db_path) conn.row_factory = sqlite3.Row cursor = conn.cursor() cursor.execute(query) rows = cursor.fetchall() columns = [description[0] for description in cursor.description] conn.close()

# Create document
doc = Document()

# Title
title_para = doc.add_heading(title, level=0)
title_para.alignment = WD_ALIGN_PARAGRAPH.CENTER

# Metadata
meta_para = doc.add_paragraph()
meta_para.alignment = WD_ALIGN_PARAGRAPH.CENTER
meta_para.add_run(f'Generated: {datetime.now().strftime("%Y-%m-%d %H:%M")}')
meta_para.add_run(f' | Records: {len(rows)}')

doc.add_paragraph()  # Spacing

# Create table
if rows:
    table = doc.add_table(rows=len(rows) + 1, cols=len(columns))
    table.style = 'Table Grid'

    # Headers
    for i, col in enumerate(columns):
        cell = table.rows[0].cells[i]
        cell.text = col.replace('_', ' ').title()
        cell.paragraphs[0].runs[0].bold = True

    # Data
    for row_idx, row in enumerate(rows, start=1):
        for col_idx, col in enumerate(columns):
            table.rows[row_idx].cells[col_idx].text = str(row[col])
else:
    doc.add_paragraph('No records found.')

doc.save(output_path)
print(f"Report saved to {output_path}")

Template-Based Document Generation

""" Generate documents by modifying a template. """ from docx import Document from docx.shared import Pt from typing import Dict, Any from pathlib import Path import re

def replace_placeholders(doc: Document, replacements: Dict[str, str]) -> None: """Replace {{placeholder}} patterns in document.""" # Process paragraphs for para in doc.paragraphs: for key, value in replacements.items(): placeholder = f'{{{{{key}}}}}' if placeholder in para.text: for run in para.runs: if placeholder in run.text: run.text = run.text.replace(placeholder, str(value))

# Process tables
for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            for para in cell.paragraphs:
                for key, value in replacements.items():
                    placeholder = f'{{{{{key}}}}}'
                    if placeholder in para.text:
                        for run in para.runs:
                            if placeholder in run.text:
                                run.text = run.text.replace(placeholder, str(value))

def generate_from_template( template_path: str, output_path: str, data: Dict[str, Any] ) -> None: """Generate document from template with data substitution.""" # Load template doc = Document(template_path)

# Replace placeholders
replace_placeholders(doc, data)

# Save generated document
doc.save(output_path)
print(f"Generated document saved to {output_path}")

Usage example

data = { 'client_name': 'Acme Corporation', 'date': '2026-01-17', 'contract_value': '$50,000', 'project_duration': '6 months', 'contact_person': 'John Smith' }

generate_from_template('contract_template.docx', 'acme_contract.docx', data)

Batch Document Generation

""" Generate multiple documents from a data source. """ from docx import Document from docx.shared import Pt, Inches from typing import List, Dict, Any from pathlib import Path import csv from concurrent.futures import ThreadPoolExecutor, as_completed

def generate_single_document( template_path: str, output_dir: Path, data: Dict[str, Any], filename_field: str = 'id' ) -> str: """Generate a single document from template.""" doc = Document(template_path)

# Replace placeholders
for para in doc.paragraphs:
    for key, value in data.items():
        placeholder = f'{{{{{key}}}}}'
        if placeholder in para.text:
            for run in para.runs:
                if placeholder in run.text:
                    run.text = run.text.replace(placeholder, str(value))

# Generate filename
filename = f"{data.get(filename_field, 'document')}.docx"
output_path = output_dir / filename

doc.save(str(output_path))
return str(output_path)

def batch_generate_documents( template_path: str, csv_data_path: str, output_dir: str, max_workers: int = 4 ) -> List[str]: """Generate multiple documents from CSV data.""" output_path = Path(output_dir) output_path.mkdir(parents=True, exist_ok=True)

# Read CSV data
with open(csv_data_path, 'r') as f:
    reader = csv.DictReader(f)
    records = list(reader)

generated_files = []

# Generate documents in parallel
with ThreadPoolExecutor(max_workers=max_workers) as executor:
    futures = {
        executor.submit(
            generate_single_document,
            template_path,
            output_path,
            record
        ): record
        for record in records
    }

    for future in as_completed(futures):
        try:
            result = future.result()
            generated_files.append(result)
            print(f"Generated: {result}")
        except Exception as e:
            print(f"Error generating document: {e}")

return generated_files

Usage

batch_generate_documents(

'invoice_template.docx',

'clients.csv',

'generated_invoices/'

)

Best Practices

1. Document Structure

"""Best practices for document organization."""

DO: Create reusable document builders

class ReportBuilder: def init(self, template_path=None): self.doc = Document(template_path) if template_path else Document()

def add_title(self, text):
    self.doc.add_heading(text, level=0)
    return self

def add_section(self, title, content):
    self.doc.add_heading(title, level=1)
    self.doc.add_paragraph(content)
    return self

def save(self, output_path):
    self.doc.save(output_path)

DO: Use context managers for cleanup

from contextlib import contextmanager

@contextmanager def document_context(output_path): doc = Document() try: yield doc finally: doc.save(output_path)

Usage

with document_context('report.docx') as doc: doc.add_heading('Title', level=0) doc.add_paragraph('Content')

2. Style Consistency

"""Maintain consistent styling across documents."""

DO: Define style constants

class DocumentStyles: FONT_HEADING = 'Georgia' FONT_BODY = 'Calibri' SIZE_TITLE = Pt(24) SIZE_HEADING1 = Pt(18) SIZE_HEADING2 = Pt(14) SIZE_BODY = Pt(11) COLOR_PRIMARY = RGBColor(0x2E, 0x74, 0xB5) COLOR_SECONDARY = RGBColor(0x59, 0x59, 0x59)

DO: Create style factory functions

def apply_heading_style(paragraph, level=1): run = paragraph.runs[0] if paragraph.runs else paragraph.add_run() run.font.name = DocumentStyles.FONT_HEADING run.font.bold = True run.font.color.rgb = DocumentStyles.COLOR_PRIMARY

if level == 1:
    run.font.size = DocumentStyles.SIZE_HEADING1
elif level == 2:
    run.font.size = DocumentStyles.SIZE_HEADING2

3. Error Handling

"""Robust error handling for document operations.""" from pathlib import Path import logging

logger = logging.getLogger(name)

def safe_generate_document(template_path, output_path, data): """Generate document with comprehensive error handling.""" try: # Validate inputs if not Path(template_path).exists(): raise FileNotFoundError(f"Template not found: {template_path}")

    # Ensure output directory exists
    Path(output_path).parent.mkdir(parents=True, exist_ok=True)

    # Generate document
    doc = Document(template_path)
    # ... processing ...
    doc.save(output_path)

    logger.info(f"Document generated: {output_path}")
    return {"success": True, "path": output_path}

except FileNotFoundError as e:
    logger.error(f"File not found: {e}")
    return {"success": False, "error": str(e)}

except PermissionError as e:
    logger.error(f"Permission denied: {e}")
    return {"success": False, "error": "Permission denied"}

except Exception as e:
    logger.exception(f"Unexpected error: {e}")
    return {"success": False, "error": str(e)}

4. Performance Optimization

"""Optimize document generation performance."""

DO: Reuse Document objects when generating similar documents

class DocumentPool: def init(self, template_path): self.template_path = template_path

def generate(self, data, output_path):
    # Load fresh copy of template for each generation
    doc = Document(self.template_path)
    # Process...
    doc.save(output_path)

DO: Use streaming for large documents

def generate_large_table(doc, data_generator, chunk_size=1000): """Generate large table in chunks to manage memory.""" table = None headers_added = False

for chunk in data_generator:
    if table is None:
        headers = list(chunk[0].keys())
        table = doc.add_table(rows=1, cols=len(headers))
        for i, header in enumerate(headers):
            table.rows[0].cells[i].text = header
        headers_added = True

    for row_data in chunk:
        row = table.add_row()
        for i, value in enumerate(row_data.values()):
            row.cells[i].text = str(value)

Troubleshooting

Common Issues

1. Font Not Appearing Correctly

Problem: Font doesn't display in Word

Solution: Use fonts available on target system

Check available fonts

def get_available_fonts(): """List fonts that should work cross-platform.""" return [ 'Arial', 'Calibri', 'Times New Roman', 'Georgia', 'Verdana', 'Tahoma', 'Consolas', 'Courier New' ]

Use fallback fonts

def set_font_with_fallback(run, preferred_font, fallback='Arial'): run.font.name = preferred_font # Set East Asian font as fallback run._element.rPr.rFonts.set(qn('w:eastAsia'), fallback)

2. Table Width Issues

Problem: Table columns not sized correctly

Solution: Explicitly set column widths

def set_column_widths(table, widths): """Set explicit column widths for table.""" for row in table.rows: for idx, (cell, width) in enumerate(zip(row.cells, widths)): cell.width = width

Usage

widths = [Inches(1), Inches(3), Inches(2)] set_column_widths(table, widths)

3. Image Not Displaying

Problem: Image doesn't appear in document

Solution: Verify image path and format

from pathlib import Path from PIL import Image

def validate_and_add_image(doc, image_path, width=None): """Validate image before adding to document.""" path = Path(image_path)

if not path.exists():
    raise FileNotFoundError(f"Image not found: {image_path}")

# Check format
supported_formats = {'.png', '.jpg', '.jpeg', '.gif', '.bmp', '.tiff'}
if path.suffix.lower() not in supported_formats:
    raise ValueError(f"Unsupported format: {path.suffix}")

# Validate image can be opened
try:
    with Image.open(image_path) as img:
        img.verify()
except Exception as e:
    raise ValueError(f"Invalid image file: {e}")

# Add to document
if width:
    doc.add_picture(str(image_path), width=Inches(width))
else:
    doc.add_picture(str(image_path))

4. Style Not Applied

Problem: Custom style not appearing

Solution: Ensure style exists before using

def safe_apply_style(paragraph, style_name, doc): """Apply style with fallback if not found.""" try: paragraph.style = style_name except KeyError: # Style doesn't exist, create it or use default if style_name not in [s.name for s in doc.styles]: # Create minimal style from docx.enum.style import WD_STYLE_TYPE doc.styles.add_style(style_name, WD_STYLE_TYPE.PARAGRAPH) paragraph.style = style_name

Version History

1.0.0 (2026-01-17)

• Initial skill creation

• Core capabilities documentation

• 6 complete code examples

• Integration patterns

• Best practices guide

• Troubleshooting section

Resources

• Official Documentation: https://python-docx.readthedocs.io/

• GitHub Repository: https://github.com/python-openxml/python-docx

• PyPI Package: https://pypi.org/project/python-docx/

• Open XML SDK Reference: https://docs.microsoft.com/en-us/office/open-xml/

Related Skills

• docx-templates - Jinja2-style template rendering for Word documents

• pypdf - PDF manipulation and generation

• openpyxl - Excel file automation

• python-pptx - PowerPoint presentation generation

This skill provides comprehensive patterns for Word document automation refined from production document generation systems.