Fill DOCX Templates from JSON Data with Python

Automating document creation saves time and reduces errors. Many businesses need to generate similar documents with different data. Python makes this easy.

This guide shows how to fill DOCX templates using JSON data. We will use the python-docx library. This approach is perfect for reports, certificates, and forms.

Why Automate DOCX Templates?

Manual document creation is slow and prone to mistakes. Automated templates ensure consistency. They also save hours of repetitive work.

JSON data can come from databases, APIs, or user input. Combining it with DOCX templates creates powerful automation. This method scales well for large volumes.

You might also find our guide on Generate Certificates in DOCX with Python helpful for specific use cases.

Setting Up Your Environment

First, install the python-docx library. Use pip for installation. This library handles DOCX file operations.

pip install python-docx

Create a new Python file for your script. Import the necessary modules. We will use json and docx.

import json
from docx import Document

Creating a DOCX Template

Start with a Word document template. Use placeholders for dynamic content. These will be replaced with actual data.

Create a simple template with placeholders. Use clear naming conventions. For example: {name}, {date}, {amount}.

Save this as template.docx. The placeholders mark where data will go. Keep the template simple and well-structured.

Preparing JSON Data

JSON data should match your template placeholders. Use key-value pairs. The keys correspond to placeholder names.

# Sample JSON data
data = {
    "company_name": "Tech Solutions Inc",
    "client_name": "John Smith",
    "invoice_date": "2024-01-15",
    "invoice_number": "INV-2024-001",
    "amount": "$1,250.00"
}

You can load JSON from a file too. Use the json.load() method. This handles external data sources.

Loading and Processing the Template

Load your template document using python-docx. The Document() function opens the file. Then we can modify its content.

# Load the template
doc = Document('template.docx')

Now we need to replace placeholders. Search through all paragraphs and tables. Update text where placeholders are found.

Replacing Placeholders with Data

Create a function to handle placeholder replacement. It should iterate through document elements. Replace matches with actual values.

def replace_placeholders(doc, data):
    for paragraph in doc.paragraphs:
        for key, value in data.items():
            placeholder = '{' + key + '}'
            if placeholder in paragraph.text:
                paragraph.text = paragraph.text.replace(placeholder, str(value))
    
    # Also check tables
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for key, value in data.items():
                    placeholder = '{' + key + '}'
                    if placeholder in cell.text:
                        cell.text = cell.text.replace(placeholder, str(value))

This function handles both regular text and tables. It ensures all placeholders get replaced. The comprehensive replacement is crucial for complete automation.

Saving the Generated Document

After replacing all placeholders, save the new document. Use a different filename to preserve the template. The save() method handles this.

# Save the filled document
doc.save('filled_invoice.docx')

Your generated document is now ready. It contains all the data from your JSON. The template remains unchanged for future use.

Complete Working Example

Here is a complete script that brings everything together. It loads data, processes the template, and saves the result.

import json
from docx import Document

def fill_docx_template(template_path, output_path, data):
    # Load template
    doc = Document(template_path)
    
    # Replace placeholders in paragraphs
    for paragraph in doc.paragraphs:
        for key, value in data.items():
            placeholder = '{' + key + '}'
            if placeholder in paragraph.text:
                paragraph.text = paragraph.text.replace(placeholder, str(value))
    
    # Replace placeholders in tables
    for table in doc.tables:
        for row in table.rows:
            for cell in row.cells:
                for key, value in data.items():
                    placeholder = '{' + key + '}'
                    if placeholder in cell.text:
                        cell.text = cell.text.replace(placeholder, str(value))
    
    # Save filled document
    doc.save(output_path)
    print(f"Document saved to {output_path}")

# Example usage
json_data = {
    "invoice_number": "INV-2024-001",
    "client_name": "Sarah Johnson",
    "amount": "$2,500.00",
    "due_date": "2024-02-15"
}

fill_docx_template('template.docx', 'invoice_2024_001.docx', json_data)

Document saved to invoice_2024_001.docx

Handling Complex Templates

Some templates have complex formatting or special elements. You might need more advanced techniques for these cases.

For templates requiring conditional logic or loops, consider using Python DOCX Templates with Jinja2. This provides more powerful templating capabilities.

When working with multiple languages or special characters, check our Python docx Multilingual Unicode Fonts Guide for proper handling.

Best Practices and Tips

Always backup your template files. Test with sample data first. Use descriptive placeholder names that match JSON keys.

Handle errors gracefully. Check if placeholders exist in the template. Validate JSON data before processing.

For large-scale automation, consider batching multiple documents. This approach works well for mass mailings or report generation.

Conclusion

Filling DOCX templates from JSON data is powerful and efficient. Python-docx makes automation accessible. This method saves time and ensures accuracy.

You can generate invoices, reports, certificates, and more. The technique scales from simple to complex documents. Start automating your document workflow today.

Remember to explore related topics like document conversion and advanced formatting. This will expand your document automation capabilities significantly.