WolfSDKWolfXLWolfPPTWolfDocxWolfRender

WolfDocx documentation - Commercial

Fill Word templates and run DOCX mail merge in Python

Use Community find_replace for a supported literal text substitution, not as an implicit Word mail-merge engine. For real MERGEFIELD templates and one output per recipient, use WolfDocx Commercial and its source-bound mail-merge request. The Commercial example below is not available from the public pip install wolfdocx package.

Choose the template operation

A visible placeholder, a Word merge field, and a repeated table row are different structures. Replacing ordinary text does not evaluate a Word field or repeat a row. Identify the structure in the template first, then choose the corresponding operation instead of treating every placeholder as the same syntax.

Community's Document.find_replace can substitute ordinary placeholder text through a regular expression. Use the Community editing example for that path. Do not use it to rewrite protected field instructions. Commercial provides merge_documents for recipient records and author_template for explicitly selected repeated template structures.

Commercial installation and inputs

This page's Python sample targets the commercially licensed wolfdocx installation from the authenticated index. Install it in a separate environment from Community, using the authenticated index and the credential from the checkout success page. Both editions install under the name wolfdocx from different indexes; an environment holds one or the other, and installing Community alone does not supply this workflow.

The command below is for bash or zsh after pip authentication has been configured. It deliberately contains no credential. Never put a purchase token into source code or a committed installation command.

python -m pip install wolfdocx --index-url https://packages.wolfxl.com/wolfdocx/simple/

Prepare template.docx with the Word field MERGEFIELD Client. Use a new recipients output directory and an absent records-new.json file. The template is an existing reviewed Word document, not a plain-text file renamed to DOCX.

Publish one recipient document

import hashlib
import json
from pathlib import Path

from wolfdocx.mail_merge import merge_documents, parse_mail_merge_request

source = Path("template.docx")
data_path = Path("records-new.json")
with data_path.open("x", encoding="utf-8") as stream:
    json.dump({"records": [
        {"id": "acme", "values": {"Client": "Acme Ltd"}}
    ]}, stream)

report = merge_documents(parse_mail_merge_request({
    "source": str(source),
    "source_sha256": hashlib.sha256(source.read_bytes()).hexdigest(),
    "output_dir": "recipients",
    "data": {
        "path": str(data_path),
        "sha256": hashlib.sha256(data_path.read_bytes()).hexdigest(),
    },
}))
if not report.passed:
    raise SystemExit(report.code)
print(json.dumps(report.to_dict(), indent=2))

The records document has a records array. Each record has an id and values map keyed by the template's merge-field names. For this input, the successful batch publishes recipients/acme.docx. Additional records produce separate recipient files rather than concatenating every letter into one document.

The request binds both source and data to their SHA-256 digests. This connects the operation to the actual files reviewed by your application. Changing the template or the records after building those bindings is not an invitation to merge the new bytes under the old request.

Request memberMeaning
source, source_sha256Reviewed template path and its exact-byte digest.
output_dirNew directory for the recipient batch.
data.path, data.sha256Records JSON and its exact-byte digest.

Inspect before building a batch

The Commercial discover_mail_merge_targets function inventories reachable merge fields without publishing a document. Use that inventory to check names and structure before assembling recipient data. Inventory success means discovery succeeded; it does not guarantee that a later merge will pass every validation or publication check.

The engine stages the batch before publication. An occupied destination or unsupported merge structure is a refusal, not permission to emit an incomplete recipient set. Read the report and correct the actual input or target rather than deleting output directories automatically.

What it does not do

  • This example does not render recipients or convert them to PDF.
  • It does not demonstrate every conditional field, nested region, or repeated-row operation.
  • Community does not gain Commercial APIs through this shared import name.
  • A published recipient is not proof of identical Word pagination.

Related tasks

See the mail-merge task guide, repeating template rows and blocks, and reports and command-line use.

Get WolfDocx

WolfDocx Community is MIT-licensed and free, including commercial use. It edits existing .docx files in place in pure Python and does not render pages or convert to PDF. WolfDocx Commercial does not change those rights.

pip install wolfdocx

WolfDocx Commercial is an organization-scoped subscription. WolfDocx Community installs from public PyPI with pip install wolfdocx. WolfDocx Commercial installs from the authenticated WolfDocx package index with a per-purchase credential, issued on the checkout success page after payment and reissued through https://wolfxl.com/recover.

Review the scoped before-and-after memo files in the reporting walkthrough, or ask about your document before purchasing if compatibility is uncertain.

See WolfDocx Commercial

Related tasks