# DOCX JSON Replacer
A powerful Python library for replacing template placeholders in DOCX files with JSON data. Supports advanced features like dynamic tables, HTML formatting in cells, and individual cell styling.
[](https://badge.fury.io/py/docx-json-replacer)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
## ✨ Features
- 📝 **Simple placeholder replacement** in paragraphs and tables
- 📊 **Dynamic table generation** from JSON data
- 🎨 **Advanced table styling** with row-level and cell-level customization
- 🔤 **HTML formatting support** in table cells (`<b>`, `<i>`, `<u>`, `<br>`, `<p>`)
- 🎯 **Smart HTML tag handling** for malformed or duplicate tags
- 🚀 **Batch processing** capabilities
- 💻 **Command-line interface** for easy automation
- 🐍 **Simple Python API** for integration
## 📦 Installation
```bash
pip install docx-json-replacer
```
## 🚀 Quick Start
### Command Line
```bash
# Basic usage
docx-json-replacer template.docx data.json -o output.docx
# Without -o flag, creates template_replaced.docx
docx-json-replacer template.docx data.json
```
### Python API
```python
from docx_json_replacer import DocxReplacer
# Create replacer instance
replacer = DocxReplacer('template.docx')
# Replace with JSON data
json_data = {
"name": "John Doe",
"company": "Acme Corp",
"table_data": [
{
"cells": ["Header 1", "Header 2", "Header 3"],
"style": {"bg": "4472C4", "color": "FFFFFF", "bold": True}
},
{
"cells": ["Row 1 Col 1", "Row 1 Col 2", "Row 1 Col 3"]
}
]
}
replacer.replace_from_json(json_data)
replacer.save('output.docx')
```
## 📄 Template Format
Use double curly braces for placeholders:
```
Dear {{name}},
Welcome to {{company}}!
{{table_data}}
```
Placeholders work in:
- Regular paragraphs
- Table cells
- Headers and footers
- Nested structures with dots (e.g., `{{client.name}}`)
## 📊 Table Support
### Basic Table (List of Lists)
```json
{
"simple_table": [
["Header 1", "Header 2"],
["Row 1 Col 1", "Row 1 Col 2"]
]
}
```
### Styled Table with Row-Level Styling
```json
{
"styled_table": [
{
"cells": ["Header 1", "Header 2", "Header 3"],
"style": {
"bg": "4472C4",
"color": "FFFFFF",
"bold": true
}
},
{
"cells": ["Data 1", "Data 2", "Data 3"],
"style": {
"bg": "F2F2F2"
}
}
]
}
```
### Individual Cell Styling (v0.6.0+)
```json
{
"cell_styled_table": [
{
"cells": ["Red Cell", "Green Cell", "Blue Cell"],
"cell_styles": [
{"bg": "FF0000", "color": "FFFFFF", "bold": true},
{"bg": "00FF00", "color": "000000", "italic": true},
{"bg": "0000FF", "color": "FFFFFF", "underline": true}
]
}
]
}
```
### Mixed Row and Cell Styling
```json
{
"mixed_table": [
{
"cells": ["Default", "Default", "Special"],
"style": {"bg": "E7E6E6"},
"cell_styles": [
null,
null,
{"bg": "FFFF00", "bold": true}
]
}
]
}
```
### HTML Formatting in Cells (v0.6.0+)
```json
{
"html_table": [
{
"cells": [
"Normal text",
"<b>Bold text</b>",
"<i>Italic</i> and <u>underline</u>"
]
},
{
"cells": [
"Line 1<br>Line 2<br>Line 3",
"<b>Title</b><br><i>Subtitle</i>",
"<p>Paragraph 1</p><p>Paragraph 2</p>"
]
}
]
}
```
## 🎨 Style Properties
| Property | Description | Example |
|----------|-------------|---------|
| `bg` | Background color (hex without #) | `"4472C4"` |
| `color` | Text color (hex without #) | `"FFFFFF"` |
| `bold` | Bold text | `true`/`false` |
| `italic` | Italic text | `true`/`false` |
| `underline` | Underlined text | `true`/`false` |
### Style Priority Order
1. Inline cell object style (highest priority)
2. `cell_styles` array entry
3. Row `style` (lowest priority)
## 🔧 Advanced Usage
### Processing Multiple Files
```python
from docx_json_replacer import DocxReplacer
import json
# Process multiple documents
templates = ['template1.docx', 'template2.docx']
data_files = ['data1.json', 'data2.json']
for template, data_file in zip(templates, data_files):
with open(data_file, 'r') as f:
data = json.load(f)
replacer = DocxReplacer(template)
replacer.replace_from_json(data)
replacer.save(f'output_{template}')
```
### Real-World Example: Invoice Generation
```python
from docx_json_replacer import DocxReplacer
invoice_data = {
"invoice_number": "INV-2024-001",
"date": "2024-01-15",
"client.name": "ABC Corporation",
"client.address": "123 Business St.",
"items": [
{
"cells": ["Item", "Quantity", "Price", "Total"],
"style": {"bg": "333333", "color": "FFFFFF", "bold": True}
},
{
"cells": ["Widget A", "10", "$10.00", "$100.00"]
},
{
"cells": ["Widget B", "5", "$20.00", "$100.00"]
},
{
"cells": ["<b>Total</b>", "", "", "<b>$200.00</b>"],
"cell_styles": [
{"bg": "E7E6E6", "bold": True},
{"bg": "E7E6E6"},
{"bg": "E7E6E6"},
{"bg": "E7E6E6", "bold": True}
]
}
]
}
replacer = DocxReplacer('invoice_template.docx')
replacer.replace_from_json(invoice_data)
replacer.save('invoice_INV-2024-001.docx')
```
## 📋 Complete Example
### Template (template.docx)
```
Contract Number: {{contract_number}}
Client: {{client.name}}
Address: {{client.address}}
Items:
{{items}}
Terms: {{terms}}
```
### Data (data.json)
```json
{
"contract_number": "2024-001",
"client.name": "ABC Corporation",
"client.address": "456 Business Ave",
"items": [
{
"cells": ["Product", "Quantity", "Price"],
"style": {"bg": "4472C4", "color": "FFFFFF", "bold": true}
},
{
"cells": ["<b>Widget A</b>", "10", "$100"],
"cell_styles": [{"bg": "E7E6E6"}, null, null]
},
{
"cells": ["<b>Widget B</b>", "5", "$200"],
"cell_styles": [{"bg": "E7E6E6"}, null, null]
}
],
"terms": "Payment due in 30 days"
}
```
### Command
```bash
docx-json-replacer template.docx data.json -o contract_2024_001.docx
```
## 🆕 What's New in v0.6.0
- **HTML Support in Tables**: Format text with `<b>`, `<i>`, `<u>`, `<br>`, and `<p>` tags
- **Cell-Level Styling**: Individual styling for each cell in a table
- **Smart Tag Handling**: Properly handles malformed or duplicate HTML tags
- **Improved Performance**: Optimized table generation and styling
## 📋 Requirements
- Python 3.7+
- python-docx >= 0.8.11
- docxcompose >= 1.3.0
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [python-docx](https://python-docx.readthedocs.io/)
- Table composition with [docxcompose](https://github.com/4teamwork/docxcompose)
## 📞 Support
For issues and feature requests, please use the [GitHub issue tracker](https://github.com/liuspatt/docx-json-replacer/issues).
## 📚 Links
- [PyPI Package](https://pypi.org/project/docx-json-replacer/)
- [GitHub Repository](https://github.com/liuspatt/docx-json-replacer)
- [Documentation](https://github.com/liuspatt/docx-json-replacer#readme)
Raw data
{
"_id": null,
"home_page": "https://github.com/liuspatt/docx-json-replacer",
"name": "docx-json-replacer",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "docx, json, template, replace, table, html, formatting, cell-styling, document-generation, office, word, automation",
"author": "liuspatt",
"author_email": "liuspatt <liuspatt@example.com>",
"download_url": "https://files.pythonhosted.org/packages/12/5a/d800a4313b251948fc99ccb2e9d7856b39d4c0e5ba410ed8c7adf3d268e7/docx_json_replacer-0.6.6.tar.gz",
"platform": null,
"description": "# DOCX JSON Replacer\n\nA powerful Python library for replacing template placeholders in DOCX files with JSON data. Supports advanced features like dynamic tables, HTML formatting in cells, and individual cell styling.\n\n[](https://badge.fury.io/py/docx-json-replacer)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n## \u2728 Features\n\n- \ud83d\udcdd **Simple placeholder replacement** in paragraphs and tables\n- \ud83d\udcca **Dynamic table generation** from JSON data\n- \ud83c\udfa8 **Advanced table styling** with row-level and cell-level customization\n- \ud83d\udd24 **HTML formatting support** in table cells (`<b>`, `<i>`, `<u>`, `<br>`, `<p>`)\n- \ud83c\udfaf **Smart HTML tag handling** for malformed or duplicate tags\n- \ud83d\ude80 **Batch processing** capabilities\n- \ud83d\udcbb **Command-line interface** for easy automation\n- \ud83d\udc0d **Simple Python API** for integration\n\n## \ud83d\udce6 Installation\n\n```bash\npip install docx-json-replacer\n```\n\n## \ud83d\ude80 Quick Start\n\n### Command Line\n\n```bash\n# Basic usage\ndocx-json-replacer template.docx data.json -o output.docx\n\n# Without -o flag, creates template_replaced.docx\ndocx-json-replacer template.docx data.json\n```\n\n### Python API\n\n```python\nfrom docx_json_replacer import DocxReplacer\n\n# Create replacer instance\nreplacer = DocxReplacer('template.docx')\n\n# Replace with JSON data\njson_data = {\n \"name\": \"John Doe\",\n \"company\": \"Acme Corp\",\n \"table_data\": [\n {\n \"cells\": [\"Header 1\", \"Header 2\", \"Header 3\"],\n \"style\": {\"bg\": \"4472C4\", \"color\": \"FFFFFF\", \"bold\": True}\n },\n {\n \"cells\": [\"Row 1 Col 1\", \"Row 1 Col 2\", \"Row 1 Col 3\"]\n }\n ]\n}\n\nreplacer.replace_from_json(json_data)\nreplacer.save('output.docx')\n```\n\n## \ud83d\udcc4 Template Format\n\nUse double curly braces for placeholders:\n\n```\nDear {{name}},\n\nWelcome to {{company}}!\n\n{{table_data}}\n```\n\nPlaceholders work in:\n- Regular paragraphs\n- Table cells\n- Headers and footers\n- Nested structures with dots (e.g., `{{client.name}}`)\n\n## \ud83d\udcca Table Support\n\n### Basic Table (List of Lists)\n```json\n{\n \"simple_table\": [\n [\"Header 1\", \"Header 2\"],\n [\"Row 1 Col 1\", \"Row 1 Col 2\"]\n ]\n}\n```\n\n### Styled Table with Row-Level Styling\n```json\n{\n \"styled_table\": [\n {\n \"cells\": [\"Header 1\", \"Header 2\", \"Header 3\"],\n \"style\": {\n \"bg\": \"4472C4\",\n \"color\": \"FFFFFF\",\n \"bold\": true\n }\n },\n {\n \"cells\": [\"Data 1\", \"Data 2\", \"Data 3\"],\n \"style\": {\n \"bg\": \"F2F2F2\"\n }\n }\n ]\n}\n```\n\n### Individual Cell Styling (v0.6.0+)\n```json\n{\n \"cell_styled_table\": [\n {\n \"cells\": [\"Red Cell\", \"Green Cell\", \"Blue Cell\"],\n \"cell_styles\": [\n {\"bg\": \"FF0000\", \"color\": \"FFFFFF\", \"bold\": true},\n {\"bg\": \"00FF00\", \"color\": \"000000\", \"italic\": true},\n {\"bg\": \"0000FF\", \"color\": \"FFFFFF\", \"underline\": true}\n ]\n }\n ]\n}\n```\n\n### Mixed Row and Cell Styling\n```json\n{\n \"mixed_table\": [\n {\n \"cells\": [\"Default\", \"Default\", \"Special\"],\n \"style\": {\"bg\": \"E7E6E6\"},\n \"cell_styles\": [\n null,\n null,\n {\"bg\": \"FFFF00\", \"bold\": true}\n ]\n }\n ]\n}\n```\n\n### HTML Formatting in Cells (v0.6.0+)\n```json\n{\n \"html_table\": [\n {\n \"cells\": [\n \"Normal text\",\n \"<b>Bold text</b>\",\n \"<i>Italic</i> and <u>underline</u>\"\n ]\n },\n {\n \"cells\": [\n \"Line 1<br>Line 2<br>Line 3\",\n \"<b>Title</b><br><i>Subtitle</i>\",\n \"<p>Paragraph 1</p><p>Paragraph 2</p>\"\n ]\n }\n ]\n}\n```\n\n## \ud83c\udfa8 Style Properties\n\n| Property | Description | Example |\n|----------|-------------|---------|\n| `bg` | Background color (hex without #) | `\"4472C4\"` |\n| `color` | Text color (hex without #) | `\"FFFFFF\"` |\n| `bold` | Bold text | `true`/`false` |\n| `italic` | Italic text | `true`/`false` |\n| `underline` | Underlined text | `true`/`false` |\n\n### Style Priority Order\n1. Inline cell object style (highest priority)\n2. `cell_styles` array entry\n3. Row `style` (lowest priority)\n\n## \ud83d\udd27 Advanced Usage\n\n### Processing Multiple Files\n```python\nfrom docx_json_replacer import DocxReplacer\nimport json\n\n# Process multiple documents\ntemplates = ['template1.docx', 'template2.docx']\ndata_files = ['data1.json', 'data2.json']\n\nfor template, data_file in zip(templates, data_files):\n with open(data_file, 'r') as f:\n data = json.load(f)\n\n replacer = DocxReplacer(template)\n replacer.replace_from_json(data)\n replacer.save(f'output_{template}')\n```\n\n### Real-World Example: Invoice Generation\n```python\nfrom docx_json_replacer import DocxReplacer\n\ninvoice_data = {\n \"invoice_number\": \"INV-2024-001\",\n \"date\": \"2024-01-15\",\n \"client.name\": \"ABC Corporation\",\n \"client.address\": \"123 Business St.\",\n \"items\": [\n {\n \"cells\": [\"Item\", \"Quantity\", \"Price\", \"Total\"],\n \"style\": {\"bg\": \"333333\", \"color\": \"FFFFFF\", \"bold\": True}\n },\n {\n \"cells\": [\"Widget A\", \"10\", \"$10.00\", \"$100.00\"]\n },\n {\n \"cells\": [\"Widget B\", \"5\", \"$20.00\", \"$100.00\"]\n },\n {\n \"cells\": [\"<b>Total</b>\", \"\", \"\", \"<b>$200.00</b>\"],\n \"cell_styles\": [\n {\"bg\": \"E7E6E6\", \"bold\": True},\n {\"bg\": \"E7E6E6\"},\n {\"bg\": \"E7E6E6\"},\n {\"bg\": \"E7E6E6\", \"bold\": True}\n ]\n }\n ]\n}\n\nreplacer = DocxReplacer('invoice_template.docx')\nreplacer.replace_from_json(invoice_data)\nreplacer.save('invoice_INV-2024-001.docx')\n```\n\n## \ud83d\udccb Complete Example\n\n### Template (template.docx)\n```\nContract Number: {{contract_number}}\nClient: {{client.name}}\nAddress: {{client.address}}\n\nItems:\n{{items}}\n\nTerms: {{terms}}\n```\n\n### Data (data.json)\n```json\n{\n \"contract_number\": \"2024-001\",\n \"client.name\": \"ABC Corporation\",\n \"client.address\": \"456 Business Ave\",\n \"items\": [\n {\n \"cells\": [\"Product\", \"Quantity\", \"Price\"],\n \"style\": {\"bg\": \"4472C4\", \"color\": \"FFFFFF\", \"bold\": true}\n },\n {\n \"cells\": [\"<b>Widget A</b>\", \"10\", \"$100\"],\n \"cell_styles\": [{\"bg\": \"E7E6E6\"}, null, null]\n },\n {\n \"cells\": [\"<b>Widget B</b>\", \"5\", \"$200\"],\n \"cell_styles\": [{\"bg\": \"E7E6E6\"}, null, null]\n }\n ],\n \"terms\": \"Payment due in 30 days\"\n}\n```\n\n### Command\n```bash\ndocx-json-replacer template.docx data.json -o contract_2024_001.docx\n```\n\n## \ud83c\udd95 What's New in v0.6.0\n\n- **HTML Support in Tables**: Format text with `<b>`, `<i>`, `<u>`, `<br>`, and `<p>` tags\n- **Cell-Level Styling**: Individual styling for each cell in a table\n- **Smart Tag Handling**: Properly handles malformed or duplicate HTML tags\n- **Improved Performance**: Optimized table generation and styling\n\n## \ud83d\udccb Requirements\n\n- Python 3.7+\n- python-docx >= 0.8.11\n- docxcompose >= 1.3.0\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [python-docx](https://python-docx.readthedocs.io/)\n- Table composition with [docxcompose](https://github.com/4teamwork/docxcompose)\n\n## \ud83d\udcde Support\n\nFor issues and feature requests, please use the [GitHub issue tracker](https://github.com/liuspatt/docx-json-replacer/issues).\n\n## \ud83d\udcda Links\n\n- [PyPI Package](https://pypi.org/project/docx-json-replacer/)\n- [GitHub Repository](https://github.com/liuspatt/docx-json-replacer)\n- [Documentation](https://github.com/liuspatt/docx-json-replacer#readme)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Replace template placeholders in DOCX files with JSON data, supports tables with HTML formatting and cell-level styling",
"version": "0.6.6",
"project_urls": {
"Changelog": "https://github.com/liuspatt/docx-json-replacer/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/liuspatt/docx-json-replacer#readme",
"Homepage": "https://github.com/liuspatt/docx-json-replacer",
"Issues": "https://github.com/liuspatt/docx-json-replacer/issues",
"Repository": "https://github.com/liuspatt/docx-json-replacer"
},
"split_keywords": [
"docx",
" json",
" template",
" replace",
" table",
" html",
" formatting",
" cell-styling",
" document-generation",
" office",
" word",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4766d619fc351af106ddb4d81464c9d82a5572491add918a29da162839cd167a",
"md5": "eb1cee851aba5f5676f78c638be22bb1",
"sha256": "872dfdd9fb00294ff8d8a70e9089d40b572df6aad2ad4cd4cadea7ef3c4840fa"
},
"downloads": -1,
"filename": "docx_json_replacer-0.6.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eb1cee851aba5f5676f78c638be22bb1",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 22749,
"upload_time": "2025-10-09T02:12:57",
"upload_time_iso_8601": "2025-10-09T02:12:57.437967Z",
"url": "https://files.pythonhosted.org/packages/47/66/d619fc351af106ddb4d81464c9d82a5572491add918a29da162839cd167a/docx_json_replacer-0.6.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "125ad800a4313b251948fc99ccb2e9d7856b39d4c0e5ba410ed8c7adf3d268e7",
"md5": "e4813a51b144c96605feb8aa26f24425",
"sha256": "f0691960de78a35ea2648d8c22f2287b7679311a10af7a5d2c191dd13bbcde65"
},
"downloads": -1,
"filename": "docx_json_replacer-0.6.6.tar.gz",
"has_sig": false,
"md5_digest": "e4813a51b144c96605feb8aa26f24425",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22359,
"upload_time": "2025-10-09T02:12:58",
"upload_time_iso_8601": "2025-10-09T02:12:58.446516Z",
"url": "https://files.pythonhosted.org/packages/12/5a/d800a4313b251948fc99ccb2e9d7856b39d4c0e5ba410ed8c7adf3d268e7/docx_json_replacer-0.6.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-09 02:12:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "liuspatt",
"github_project": "docx-json-replacer",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "docxtpl",
"specs": [
[
">=",
"0.20.0"
]
]
},
{
"name": "python-docx",
"specs": [
[
">=",
"0.8.11"
]
]
}
],
"lcname": "docx-json-replacer"
}
JSON
