docxblocks 1.1.0

High-level block-based abstraction over python-docx for building dynamic Word documents in code.

docxblocks

🧱 High-level, block-based abstraction for python-docx.

🚀 Why docxblocks?

Unlike templating libraries like docxtpl, docxblocks keeps all logic in Python, not in .docx files. Build dynamic Word reports from structured block objects inside your codebase.

✨ Key Features

• Block types: text, heading, table, bullets, image
• Inline text by default - consecutive text blocks stay on the same line
• Style control via consistent style dictionaries
• Graceful fallback for missing data
• Declarative, testable, version-controlled
• No logic inside Word templates

📦 Installation

pip install docxblocks

📘 See the Style Guide for all supported style keys, color formats, and alignment options.

📄 Creating Word Templates

Important: Placeholder Requirements

Each placeholder MUST be in its own paragraph. This is crucial for proper document generation.

✅ Correct Template Structure:

Paragraph 1: {{main}}
Paragraph 2: (empty or other content)
Paragraph 3: {{header}}

❌ Incorrect Template Structure:

Paragraph 1: Some text {{main}} more text
Paragraph 2: {{header}} and other content

How to Create Templates:

1. Open Microsoft Word and create a new document
2. Add placeholders by typing them in separate paragraphs:
   • Type {{main}} and press Enter
   • Type {{header}} and press Enter
   • Each placeholder gets its own paragraph
3. Save as .docx format
4. Use in your code with DocxBuilder("template.docx")

Template Example:

Document Title

{{header}}

{{main}}

{{footer}}

🧱 Block-Based API (Core Concept)

Each piece of content is a block:

{
  "type": "text",
  "text": "All systems operational.",
  "style": {
    "bold": True,
    "italic": False,
    "font_color": "007700",
    "align": "center",
    "style": "Normal"
  }
}

Block types:

Type	Required Keys	Optional Keys
text	text	new_paragraph
heading	text, level
table	content
image	path
bullets	items (list)

📝 Inline Text

Text blocks are inline by default - they continue on the same line as previous text blocks:

blocks = [
    {"type": "text", "text": "Participant Name: "},
    {"type": "text", "text": "John Doe", "style": {"bold": True}},
    {"type": "text", "text": " (ID: "},
    {"type": "text", "text": "12345", "style": {"font_color": "007700"}},
    {"type": "text", "text": ")"},
    {"type": "text", "text": "New paragraph starts here", "new_paragraph": True},
]

Use "new_paragraph": true to force a new paragraph.

🧪 Example

from docxblocks import DocxBuilder

builder = DocxBuilder("template.docx")
builder.insert("{{main}}", [
    {"type": "heading", "text": "Summary", "level": 2},
    {"type": "text", "text": "This report provides status."},
    {
        "type": "table",
        "content": {
            "headers": ["Service", "Status"],
            "rows": [["API", "OK"], ["DB", "OK"]]
        },
        "style": {
            "header_styles": {"bold": True, "bg_color": "f2f2f2"},
            "column_widths": [0.5, 0.5]
        }
    },
    {"type": "image", "path": "chart.png", "style": {"max_width": "4in"}}
])
builder.save("output.docx")

🛠️ Philosophy

Keep the logic in your code — not in your Word template.

• Fully programmatic document generation
• No fragile embedded logic ({{ if x }}) in .docx
• Declarative, JSON-like format ideal for automation and templating
• Built for dynamic, testable, repeatable reports

🧪 Development

Setup

# Clone the repository
git clone https://github.com/frank-895/docxblocks.git
cd docxblocks

# Run the development setup script
./scripts/setup_dev.sh

Testing

# Run all tests
PYTHONPATH=. pytest tests

# Run tests with verbose output
PYTHONPATH=. pytest tests -v

# Run specific test file
PYTHONPATH=. pytest tests/test_text_block.py

Examples

# Run individual examples
cd examples
python text_block_example.py
python table_block_example.py
python image_block_example.py
python combined_example.py
python inline_text_example.py  # New inline text example

Continuous Integration

GitHub Actions automatically runs tests on:

• Every push to main and develop branches
• Every pull request to main
• Multiple Python versions (3.9, 3.10, 3.11)

Note: Tests run automatically in CI, so you can push your changes and see the results on GitHub.

📄 License

MIT - LICENSE