docxspec 0.0.9

Lightweight Word report generation library based on python-docx

docxspec

English | 简体中文

docxspec is a structured Word report generation library built on top of python-docx.

It provides a small, template-driven API for generating .docx reports from user-supplied templates and containerized content blocks. It is designed for automated test reports, simulation reports, and other engineering document workflows.

Features

• Template-based Word report generation
• Structured content container API
• Text, image, and table insertion
• Rich text style helpers
• Automatic figure and table caption numbering
• Page field helpers such as PAGE and NUMPAGES
• Word field refresh helpers for TOC, figure lists, table lists, and captions
• KL-standard document classification, validation, and standard document assembly
• PyPI-ready packaging and CI/CD workflows

Installation

Install from PyPI:

pip install docxspec

Or install from source:

git clone https://github.com/Poggi-Tang/DocxSpec.git
cd DocxSpec
pip install -e .

Quick Start

from docxspec import BODY_STYLE, WordAPI, make_rich_text

api = WordAPI("your_template.docx")

text = make_rich_text(
    "This text is inserted into the template.",
    BODY_STYLE,
)

image_container = api.new_container()
image_container.add_image(
    "your_image.png",
    width_cm=8.0,
    align="center",
)

table_container = api.new_container()
table_container.add_table_by_config(
    {
        "data": [
            ["Name", "Value"],
            ["Example", "123"],
        ]
    }
)

api.render(
    {
        "text": text,
        "image": image_container.subdoc,
        "table": table_container.subdoc,
    },
    "report.docx",
)

Table cells can also contain mixed text and images. Image parts support explicit sizing:

table_container.add_table(
    [
        ["Field", "Content"],
        [
            "Test method",
            [
                "1. Build test topology\n",
                {"image": "topology.png", "width_cm": 6.0},
                "\n2. Run simulation and record output",
            ],
        ],
    ]
)

For JSON-like configurations, use {"type": "mixed", "parts": [...]} and {"type": "image", "path": "...", "width_cm": 3.0} when a more explicit schema is preferred.

How It Works

docxspec uses two main ideas:

1. WordAPI loads a .docx template and renders the final output.
2. Containers are used to build structured sub-document blocks such as images, tables, captions, and styled paragraphs.

A typical workflow is:

1. Prepare a Word template
2. Build text or container content
3. Pass the rendered blocks into api.render(...)
4. Export the final report

Template Requirements

docxspec is template-driven.

When preparing your own template, make sure that:

• the template structure matches the placeholders or render targets used by your code
• the required paragraph / table styles exist in the template
• custom report styles are defined in advance if your project depends on them

The demo template in Demo/template.docx is provided as a runnable example, but demo assets are not packaged into the published wheel. The KL master template used by build_standard_docx() is bundled separately as package data.

KL Standard Documents

docxspec also provides KL-standard document utilities for workflows that start from an existing body-only .docx file and need a standardized output document.

from docxspec import build_standard_docx, check_word_standard, classify_docx_body

report = classify_docx_body("body.docx")
build_result = build_standard_docx(
    "body.docx",
    "standard.docx",
    "Demo/template.docx",
)
check_result = check_word_standard("standard.docx")

These APIs reuse the KL styles and field-code rules from the master template. They are intended for document standardization and validation, while WordAPI remains the primary API for template-driven report generation.

Refreshing Word Fields

docxspec can mark a generated .docx so Word/WPS refreshes fields when the document is opened. On Windows with Microsoft Word installed, it can also refresh fields immediately through Word COM automation.

from docxspec import refresh_docx_fields

result = refresh_docx_fields("report.docx", use_word=True)
print(result.word_refreshed, result.error)

Install the optional Word automation dependency when immediate COM refresh is needed:

pip install "docxspec[word]"

Without Microsoft Word or pywin32, refresh_docx_fields() still writes the updateFields flag so the fields can update when the file is opened.

Demo Directory

The repository includes a runnable demo set in Demo/.

Shared template:

• Demo/template.docx

Example scripts:

• Demo/demo1_paragraph.py
• Demo/demo2_container_paragraph.py
• Demo/demo3_container_image_caption.py
• Demo/demo4_container_table_caption.py
• Demo/demo5_container_table_image_caption.py
• Demo/demo6_header_footer.py
• Demo/demo7_styles_in_container.py
• Demo/demo8_all_in_one.py
• Demo/demo9_block_template.py
• Demo/demo10_kl_standard.py
• Demo/demo11_table_mixed_cell.py

Run them from the repository root, for example:

python Demo/demo1_paragraph.py
python Demo/demo8_all_in_one.py
python Demo/demo9_block_template.py
python Demo/demo10_kl_standard.py

Generated files are written to Demo/output/.

Reusing Word Blocks

BlockTemplate can extract a repeated caption + table block from an existing Word template and insert cloned copies back into a document or a container. This is useful when the template already contains field captions, merged cells, images, or carefully prepared table styles.

Place a marker paragraph immediately before the source caption and table:

{{SOURCE_TABLE_BLOCK}}
Table <SEQ field> {{TABLE_TITLE}}
<table with placeholders>

Then extract and reuse the block:

from docxspec import WordAPI

api = WordAPI("template.docx")
block_template = api.extract_table_block("{{SOURCE_TABLE_BLOCK}}", remove_block=True)

container = api.new_container()
container.add_block(
    block_template.clone().replace_text(
        {
            "{{TABLE_TITLE}}": "Default icon display",
            "{{ITEM_ID}}": "FT_Demo_UI_001",
        }
    )
)

api.render({"result": container.subdoc}, "report.docx")

For documents that must preserve Word field captions as strictly as possible, prefer insert_block_at_marker(...) followed by saving the document directly.

Project Structure

DocxSpec
├── .github/
│   └── workflows/
├── Demo/
├── src/
│   └── docxspec/
│       ├── __init__.py
│       ├── word_api.py
│       └── word_styles.py
├── tests/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README.zh-CN.md
└── pyproject.toml

Release Automation

This repository is prepared for a professional Python package workflow:

• CI runs lint and tests on push and pull request
• Trusted Publishing publishes to PyPI from GitHub Actions
• Build artifacts include both source distribution and wheel

Development

pip install -e .[dev]
pytest
ruff check .

When developing locally, prepare your own .docx template files in the repository or project workspace and pass their paths explicitly to WordAPI.

License

MIT License. See LICENSE.