Migrating to python-hwpx 5.0

python-hwpx 5.0 is the HWPX object model, OPC/OXML, and the format-native primitives built on them. The application workflows that grew inside the library — agent editing, document authoring, form-fill, eval-plan, exam typesetting, institutional lint, and Hancom rendering — now live in python-hwpx-automation, which has owned their canonical implementation since the 4.x line.

Nothing here is discontinued. Every removed import has a named replacement, and python-hwpx 4.x keeps all of it for anyone who needs time.

If you use the MCP server or the skill

Nothing to do. The tool names, schemas, and results are unchanged; only the implementation’s address moved, and it moved before this release.

If you import `hwpx` directly

Install the companion package and change the import path:

pip install python-hwpx-automation

The tables below give the exact replacement for each removed surface.

Rolling back

pip install "python-hwpx<5" restores every 4.x surface. The 4.x line stays available; it is not a deprecated dead end you are being pushed off.

Removed surfaces

Exam typesetting — `hwpx.exam`

Question parsing, block measurement, and composition into a form.

removed	replacement
`hwpx.exam.compose_exam_into_form`	`hwpx_automation.office.exam.compose.compose_exam_into_form`, or the MCP `compose_exam` tool
`hwpx.exam.measure`	`hwpx_automation.office.exam.measure`, or the MCP `verify_question_splits` tool
`hwpx.exam.parser`	`hwpx_automation.office.exam.parser`
`hwpx.exam.ir`	`hwpx_automation.office.exam.ir`
`hwpx.exam.profile`	`hwpx_automation.office.exam.profile`

The examples/compose_exam.py script is removed with it; the skill’s exam workflow covers the same ground through the MCP tools.

Why it moved: laying out exam questions to fit a specific form is a document genre, not a property of the HWPX format. The primitives it stands on — tables, paragraphs, page geometry, package preservation — are all still core, which is why the MCP owner builds on them rather than carrying its own copy.

Agent editing — `hwpx.agent` and the `hwpx` command

removed	replacement
`hwpx.agent.*`	`hwpx_automation.office.agent`
`hwpx` console command	the same command, declared by `python-hwpx-automation`

MCP declares hwpx in the train that raises its core floor to 5.0, so no valid install ever has two packages claiming the name. Install the companion package and the command keeps working with the same subcommands.

Authoring — `hwpx.authoring`, `builder`, `design`, `presets`

removed	replacement
`create_document_from_plan`, `validate_document_plan`, `normalize_document_plan`	`hwpx_automation.office.authoring`, or the MCP `validate_document_plan` → `create_document_from_plan` tools
`hwpx.builder.Document`, `Section`, `Paragraph`, `Table`, `Header`, `Footer`	`hwpx_automation.office.authoring.builder`
`hwpx.design`, `hwpx.presets`	`hwpx_automation.office.authoring.design` / `.presets`
`hwpx.tools.report_parser.parse_government_report_text`	`hwpx_automation.office.authoring`, or the MCP tool of the same name

Why: a document plan is a genre description, and a Korean government report is an institutional form. Core still gives you paragraphs, runs, tables, headers and page geometry — the builder composes those, it does not extend the format.

Form fill and eval plans

removed	replacement
`hwpx.form_fill`, `hwpx.formfill_quality`, `hwpx.fill_residue`, `hwpx.guidance_scan`, `hwpx.template_formfit`	`hwpx_automation.office.form_fill`, or `analyze_form_fill` → `apply_form_fill` → `verify_form_fill`
`hwpx.evalplan_fill`	`hwpx_automation.office.evalplan`, or `apply_evalplan_fill`

The measurement contract stayed: hwpx.form_fit — policy, measure, engine, report, apply — is still core, because core’s own table and field APIs call it. What left is the seal placement, the PDF extraction, and the institutional rules.

Compliance, quality, utilities

removed	replacement
`hwpx.tools.official_lint`	`hwpx_automation.office.compliance.official_lint`
`hwpx.tools.pii`	`hwpx_automation.office.compliance.pii`
`hwpx.tools.table_compute`	`hwpx_automation.office.utilities`
`hwpx.tools.style_profile`, `hwpx.tools.advanced_generators`	`hwpx_automation.office.authoring`

Mail merge — a default that changed

hwpx.tools.mail_merge.mail_merge is gone. Use merge_template_rows, which is now public.

# 4.x — masking was on by default, through rules core no longer carries
mail_merge(template, rows, output_dir=out)

# 5.0 — the caller supplies the sanitizer, and the choice is visible
from hwpx.tools.mail_merge import merge_template_rows
merge_template_rows(template, rows, output_dir=out, value_sanitizer=my_masker)

This is the one removal that changes a default rather than an address, so it is worth being explicit: the old wrapper masked personal information unless you opted out. Rather than flip that default to “do nothing” — which would leak quietly for anyone who did not read this page — the wrapper is gone, and the generic function has always required you to say what sanitizing means.

hwpx_automation.office.compliance provides a policy you can pass straight in.

Rendering and PDF reading — injected, not discovered

Core no longer looks for a Hancom installation or an imaging stack.

# 4.x — core resolved an oracle behind your back
verify_redline(before, after)

# 5.0 — the companion layer supplies the backend
from hwpx_automation.office.rendering import resolve_hancom_backend
verify_redline(before, after, oracle=resolve_hancom_backend())

Without a backend the report is render_checked=False and opensClean=None. That is deliberate: an unverified result should say so rather than look like a pass. The same applies to verify_fill, and to toc_fidelity.toc_verify(..., extract=...).

`python-hwpx[visual]` is now an empty extra

pip install "python-hwpx[visual]" still succeeds — the extra is kept deliberately so existing install commands and lockfiles do not break — but in 5.0 it installs nothing. In 4.2.0 it pulled in pymupdf, pillow and numpy.

pip does not warn about a declared-but-empty extra, so an upgrade takes the imaging stack away silently and you find out later at the first import fitz. If you were relying on it, move to the companion:

4.x	5.0
`python-hwpx[visual]`	`python-hwpx-automation[oracle]` (render/PDF) or `python-hwpx-automation[vision]`

Core owns no imaging runtime in 5.0; that is the same boundary the rendering change above describes.

Removed from the wheel

hwpx.benchmark and hwpx.conformance no longer ship, and the hwpx-conformance command is gone with them. They are repository QA assets. If you were running the conformance campaign, work from a checkout.

The complete 77-path removal inventory is machine-pinned for both source and built distributions. See architecture/product-boundary.md for the ownership, dependency, and non-resurrection contract.