AI agents and coding assistants: choose the right PyWPDoc API

Use PyWPDoc when a Python workflow needs editable Microsoft Word DOCX and Hancom Hangul HWPX documents. It is a Python package—not an MCP server, an AI model tool or a universal file converter.

This guide records the verified public API, runnable examples, unsupported requests and safeguards so code generators can select the right method instead of guessing.

Task → API decision guide

User intent	API to use	Important contract
Produce editable Word and Hangul reports	`Document.new("docx")`, `Document.new("hwpx")`	Save each file in its original format
Open/edit an existing DOCX or HWPX	`Document.open(path)`	Selects backend from the extension
Fill a template	`check_template(data)` then `render_template(data)`	Validate first; rendering mutates
Replace a company name cautiously	`preview_replace()` then `replace_text()`	Preview is read-only
Use regex find/replace	`find_regex()`, `replace_regex()`	Unsafe boundaries and zero-width matches may be rejected
Compare two compatible document versions	`before.compare(after)`	Returns a separate tracked-change document; supports only specified structures
Edit legacy binary `.hwp`	Not supported by the common API	Do not present `.hwp` as HWPX
Guarantee conversion or pixel-identical pages	Do not promise it	`save()` does not convert; formats and native layout differ

Install

Python 3.10+. Version 0.44.0 and later includes both formats by default:

pip install pywpdoc

The earlier published 0.44.0rc1 prerelease requires pip install "pywpdoc[unified]==0.44.0rc1" for DOCX. 0.44.0 is the new three-part release target and is published only by the separate approved release workflow; the [unified] extra remains accepted for backwards compatibility.

Runnable, CI-tested workflows

1. Create two native editable files

from pywpdoc import Document

for fmt in ("docx", "hwpx"):
    doc = Document.new(fmt)
    doc.add_paragraph("Quarterly report")
    doc.save(f"quarterly.{fmt}")

Table-based quickstart is tested on both formats.

2. Template preflight, read-only preview and safe replacement

Run python examples/manual/agent_tasks.py ./output from a checked-out repository. The complete example below is tested in both DOCX and HWPX by the API contract suite.

"""Agent-oriented document workflow, exercised on DOCX and HWPX."""
from pathlib import Path
from pywpdoc import Document


def run(fmt: str, out_dir: Path) -> Path:
    """Check template, preview replacement, save and re-open a document."""
    out_dir.mkdir(parents=True, exist_ok=True)
    doc = Document.new(fmt)
    doc.add_paragraph("Customer: {{customer.name}}")
    doc.add_paragraph("Status: DRAFT")
    table = doc.add_table(2, 2)
    table.cell(0, 0).text = "Item"
    table.cell(0, 1).text = "Quantity"
    table.cell(1, 0).text = "Notebook"
    table.cell(1, 1).text = "12"

    data = {"customer": {"name": "Example Ltd"}}
    report = doc.check_template(data)
    if not report.ok:
        raise ValueError(f"Unresolved template fields: {report.missing_keys}")
    assert doc.render_template(data) == 1

    preview = doc.preview_replace("DRAFT", "APPROVED")
    assert preview.count == 1
    assert "DRAFT" in doc.paragraphs[-1].text  # read-only preview
    assert doc.replace_text("DRAFT", "APPROVED") == 1

    path = out_dir / f"agent-workflow.{fmt}"
    doc.save(path)
    reopened = Document.open(path)
    assert reopened.format == fmt
    assert any("Example Ltd" in p.text for p in reopened.paragraphs)
    assert any("APPROVED" in p.text for p in reopened.paragraphs)
    assert reopened.tables[0].cell(1, 1).text == "12"
    return path


if __name__ == "__main__":
    import sys
    out = Path(sys.argv[1] if len(sys.argv) > 1 else ".")
    for fmt in ("docx", "hwpx"):
        print(run(fmt, out))

Additional tested examples: templates, find/replace, tracked comparison, pictures and sections.

3. Compare supported text changes

from pywpdoc import Document

before = Document.new("hwpx")
before.add_paragraph("Amount: 100")
after = Document.new("hwpx")
after.add_paragraph("Amount: 200")
tracked = before.compare(after, author="Reviewer")
tracked.save("tracked.hwpx")

Full compared-revision example is tested for both formats.

Correct usage and fallback rules

Import Document from the public package: from pywpdoc import Document. Do not couple application code to pywpdoc._engine.
Document.open() expects a .docx or .hwpx path. Save in the same format; do not treat save() as conversion.
doc.docx, doc.hwpx, and doc.backend are expert, format-specific interfaces, not part of the portable guarantee.
The common method add_section() takes no arguments. Advanced DOCX start_type and HWPX after are different backend-specific controls.
add_picture() detects PNG/JPEG/GIF/BMP signatures; specify width to avoid different native defaults.
Inspect check_template(data).ok before mutating render_template(data).
For large replacements, inspect preview_replace() and preserve an original copy. preview_replace() itself never edits the document.
An unsupported comparison or format-specific operation can raise DocumentUnsupportedError. Do not silently discard content or auto-convert on failure.
Word/Hancom COM integration, actual PDF export and pixel layout checks require separate native application tooling.

Exact signatures · Results / exceptions · Format-specific APIs · Compatibility · Limitations · 한국어

Evidence and discovery scope

GitHub CI passed 10/10 jobs. Windows native QA passed 11/11 focused cases and 7/7 extended stages for 0.44.0rc1; no fresh PDF/pixel-layout test for that candidate was included.

This page and llms.txt are discoverable documentation aids—not a claim of official integration with ChatGPT/Claude or any guaranteed AI search ranking.