python-hwpx product boundary
python-hwpx is the engine: an independently useful library that reads and
writes HWPX (and HWP 5.0) documents, comparable in role to python-docx.
Where the line is (7.0)
Since 7.0 the line is drawn by what a feature does with the file (owner decision for 7.0; it replaces the 2026-11-12 criterion “by what installing one brings in”).
Engine —
python-hwpx. The same file gives the same answer, and the answer is what the file says: open, read, traverse, edit, create, save, validate and preserve, and measure what Hancom would draw from what is stored (line layout, glyph widths, page estimates, equation boxes). A feature that reports or writes what is in the file belongs here, even when it knows Hancom’s vocabulary or how Korean documents are written (outline style names, number forms).Automation —
python-hwpx-automation. Everything that converts, guesses, prefers or judges: conversion to and from other formats (Markdown, HTML, ingest of other formats, framework loaders), guessing what a form means (a cell found by the label beside it, check marks typed as text), taste (a named report look, previews drawn approximately), genre rules (official-document references, format rule sets), batch workflows (mail merge), and everything that needs a server, a renderer or Hancom.Plugin —
hwpx-skill. Task judgment, routing and prompt guidance.
Product |
Holds |
|---|---|
|
the document model and facade, OPC/OXML parts, reading and plain-text extraction, the table map, editing and creating, form fields and cells by position, measurement, validation, preservation and recovery |
|
Markdown/HTML in and out ( |
|
task judgment, routing and prompt guidance |
7.0 moved the conversion and guessing features accordingly; each old name
raises an error that names its new place (hwpx._moved_modules,
migration-7.0.md). Core never imports the
automation package: the guidance is a table of names.
The mechanisms below do not change with the criterion. The closed import allowlist, the ownership ledger and the layer leak guard stay; a new third-party import still needs its own entry and its own optional extra.
Core owns
the document object model and public facade;
OPC package and OXML part ownership;
generic reading, traversal, editing, formatting, and table primitives, and the table map and plain text as the file stores them;
serialization, byte/story preservation, validation, rollback, and recovery;
measurement of what Hancom draws from stored values (line layout cache, glyph widths, page estimates, equation sizes);
renderer-neutral quality contracts such as
RenderBackend,EditMask, andVisualReport.
Companion layers own
python-hwpx-automation owns conversion, guessing, looks, genre/profile/policy
decisions, office workflows, agent plans, Hancom discovery, and renderer
binding. hwpx-skill owns task judgment, routing, and prompt guidance.
Core must not import either companion package. A new core module that was not
present at the 4.2.0 baseline requires an explicit entry in
module-ownership.json; falling through the generic
core rule is not enough. The modules 7.0 moved are listed under removed there
with removedIn: 7.0.0 and their new owner.
Mixed-module decisions
qualityandtable_patchstay core.renderer-neutral protocols are core; Hancom/backend binding and visual execution belong to
python-hwpx-automation.document diff keeps the generic paragraph diff in core (
hwpx.tools.doc_diff); the reference consistency lint moved (7.0).the plain-text exporter (
hwpx.tools.exporter.export_text, the list and note labels Hancom draws) stays core; Markdown and HTML export moved (7.0).the table map (
doc.tables.map) stays core; finding a cell by its label moved (7.0).the native mail-merge field (
paragraph.add_mail_merge_field) stays core: it writes a field Hancom defines. Batch mail merge moved (7.0).equation conversion (
latex_to_eqedit,eqedit_to_latex) and measurement stay core; drawing equations for a preview (MathML) moved (7.0).tracked-change format primitives stay core; oracle verification moves.
benchmark and conformance campaign runners are repository QA, not product API.
The 5.0 boundary is closed: every non-core disposition (mcp-migrate, split,
dev-only, and undecided) must remain exactly zero. A non-core file fails the
ownership gate even if it would have fit beneath the historical baseline or
carried a self-consistent ledger exception.
The 4.2 path baseline is the repository fixture
module-ownership-baseline-4.2.json, pinned independently by path count and
SHA-256 in the checker, ledger, and tests. The gate never reads Git history, so
the same result is required in full, shallow, single-commit, and gitless source
copies.
Removal is a second, independent invariant. The exact 77 paths removed in 5.0
are recorded in module-ownership-removed-5.0.json at SHA-256
4b8b4da35b3cf44503eb0dba05e335de1894ca5dd0b2fb668692a69e21ae6172.
Every one must remain absent even if an empty file, a new implementation, or a
new ledger exception would otherwise classify as core. Public-artifact hygiene
normalizes both wheel members (hwpx/...) and sdist members
(<archive-root>/src/hwpx/...) back to repository paths and applies the same
zero-resurrection inventory.
Closed import capability
The gate AST-inspects every core Python module. Absolute imports are fail-closed:
the allowed roots are the running Python’s standard library, hwpx, and the
one declared runtime dependency lxml. (Until 7.0 the optional openpyxl,
latex2mathml, langchain_core and llama_index were allowed for mail merge,
the preview and the framework loaders; those features moved, and the extras
xlsx, preview, langchain and llamaindex stay as empty names so existing
install commands keep working.)
Everything else—including the companion products, MCP SDK, PDF/rendering,
numerical, COM, and macOS GUI bindings—is rejected without maintaining a
guessable denylist.
Dynamic loading is capability-gated, not inferred from literal target strings.
Core cannot acquire importlib loaders, importlib.util, find_spec, builtin
__import__, eval, or exec. subprocess and ctypes imports and
os.system/os.popen (including the covered alias and reflective forms) are
also forbidden. The only exceptions are:
one exact
from importlib import resourcesimport used by packaged templates;PackageNotFoundErrorandversionimported directly fromimportlib.metadata, inside_resolve_version()rather than at module scope — a module-level binding leakshwpx.PackageNotFoundErroronto the top-level surface even though it is not in__all__, so keep the import in the function;the code-pinned
importlib.import_module(module_name)call insrc/hwpx/__init__.py(the deprecated-name loader; its map is empty since 5.0).
The lazy call, its line/version-neutral AST fingerprint, the __getattr__ that
holds it, and the 14-entry literal-map inventory (_EXPERIMENTAL_EXPORTS plus
_DEPRECATED_EXPORTS) are pinned. The call also performs a runtime
fail-closed check that the selected module is exactly hwpx or below hwpx.*;
mutating the private map cannot turn it into an external import.
This is an architectural dependency ratchet, not a Python security sandbox. Arbitrary standard-library laundering, native extensions, generated bytecode, and intentionally obfuscated runtime code are outside its threat model. The gate covers normal source imports and the explicitly tested acquisition, aliasing, assignment, and reflection forms; release review and package tests remain responsible for hostile-code scenarios.
Function-level guards
The ownership ledger classifies whole files, so it cannot see application logic inside a core file. A layer leak guard makes that logic visible in review, and a size record makes core growth visible at each release.
Layer leak guard
scripts/layer_leak_guard.py AST-scans every product module under src/hwpx
(not data/, not _moved_modules.py) for two signals:
hangul-regex: the pattern given tore.compile,match,search,fullmatch,sub,findallorfinditercontains Hangul, as a literal or as a module-level string constant passed by name;plan-schema-key: a subscript or.get()with the key"sections"or"blocks", the shape of the automation layer’s document plan.
Every existing hit is listed in tests/data/layer_leak_allowlist.json by file,
qualified name (a function, a method, or the module-level constant a regex is
assigned to), signal and exact count, with a classification and a reason:
format-vocabulary: Hancom format vocabulary or a written convention of Korean documents that any HWPX user needs, such as built-in style names, field-type tokens or heading number forms. It stays.known-leak: genre or policy logic left over from the layer audit. It moves topython-hwpx-automation: known-leak-migration.md is the contract — each group’s automation owner, the neutral primitive core keeps and the replacement entry point. Two of the four groups (the reference rules and the report heading guess) moved with the 7.0 conversion move; for the two left the core names keep working through 6.x, warn in the next major and are removed in the major after it (the owner’s option A).
undetected lists known leaks that neither signal sees (a caption pattern
without Hangul). They are not counted, but each named
function or constant must still exist, so the entry leaves the list when the
code moves.
A new hit fails. Before allowlisting it, apply the feature-placement test of the layer-boundary guardrails (section 4), in order:
Does it work with the library alone, for any HWPX user, without deciding a genre, institution or policy? Core.
Is it a multi-step workflow, a rule about what a document must contain, or something that needs the automation runtime (MCP server, renderer, Hancom)?
python-hwpx-automation.Does it judge user intent, genre or ambiguity, or choose tools? The plugin.
Touching XML does not make a feature core, and knowing a Korean writing
convention does not make it application logic. Only answer 1 belongs in the
allowlist, as format-vocabulary with a reason. A count that drops below its
entry also fails: lower or remove the entry in the same change.
python scripts/layer_leak_guard.py --list # every live hit
python scripts/layer_leak_guard.py # check (tests/test_layer_leak_guard.py)
Size history and import breadth
docs/size-history.json records, per release, the physical lines of every
.py file under src/hwpx, the same per top-level subpackage ("." holds the
top-level modules), how many hwpx modules a bare import hwpx loads in a
fresh python -I interpreter with only the measured tree’s src on the path,
and that import’s median time over three runs on the recording machine. It is
written during release prep (see docs/release-runbook.md), not per pull
request: an exact line lock would conflict between every pair of parallel
branches. tests/test_size_ratchet.py only checks that the file is well formed
and that its newest entry is not newer than the pyproject.toml version.
The module count is also an upper-bound ratchet in
tests/data/import_breadth.json. A change that makes import hwpx load more
modules fails; import new modules lazily where they are used, or raise the
bound in the same change and say why. A lower count passes with a warning;
tighten the bound with --lower-bound when convenient. Import time is never
gated.
python scripts/size_ratchet.py # working tree vs last release, per package
python scripts/size_ratchet.py --record 6.8.0 # release prep: append the working tree
python scripts/size_ratchet.py --record 6.0.0 --ref v6.0.0 # measure a tag via git archive
python scripts/size_ratchet.py --lower-bound # tighten the module bound