hwpforge

Tongs — Read, edit and generate Korean HWP/HWPX documents from Python.

본 제품은 한컴의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다. (Developed with reference to Hancom's public HWP file format documents: https://www.hancom.com/etc/hwpDownload.do.)

hwpforge wraps the HwpForge Rust library: a document model for the HWPX (OWPML) format, an HWP5 reader, a Markdown bridge and a PDF renderer. The Python package is a thin layer over that library, so it performs the same operations, with the same meaning, as the command line tool and the MCP server. What each frontend calls them differs: method names, argument spellings and some failure codes are Python's own public contract, and the other two keep theirs.

What it reads and writes

Reads .hwpx, and .hwp (HWP5) through hwpforge.convert_hwp5. That conversion is one way: the result is an HWPX document, and the original .hwp is never written back.

Writes .hwpx only. There is no .hwp output, and Hancom Office opens .hwpx natively. Documents also export to Markdown, JSON and PDF. A PDF needs the document's own fonts present on the host and named through font_dirs or discovery: by default a face that cannot be resolved fails the render rather than being guessed at. to_pdf(degraded=True) relaxes that and renders the missing face with a fallback, which changes how the page looks.

Rendering replays a layout stored in the document, so to_pdf needs a document that carries one. Two do: an HWPX Hancom saved, and an HWPX converted from HWP5, which carries the layout across by default — hwpforge.convert_hwp5(data).document.to_pdf(...). A document this library generated from Markdown or JSON carries no layout and is refused with PDF_RENDER_FAILED.

A paragraph whose line starts cannot be carried over exactly loses its layout and is reported as LAYOUT_CACHE_DROPPED; convert_hwp5(data, carry_layout_cache=False) leaves the layout out.

Install

pip install hwpforge

With uv: uv add hwpforge in a project, or uv pip install hwpforge in an environment.

Pin with ~= rather than ==. A Python-only fix ships as X.Y.Z.N, and an exact pin never receives it.

What is published

One abi3 wheel per platform covers CPython 3.9 and newer. Free-threaded builds are not supported, because the stable ABI does not cover them.

Hosts without an index

The wheel is a zip file and the package declares no runtime dependencies, so it can be unpacked and imported without pip. The requirement is glibc 2.28 or newer, not a particular distribution — on any Linux x86_64 host with CPython 3.9+ (Debian 10/11/12, Ubuntu 20.04 and later; the file name below is the x86_64 wheel):

python3 -c "import zipfile; zipfile.ZipFile('hwpforge-<version>-cp39-abi3-manylinux_2_28_x86_64.whl').extractall('/opt/hf')"
PYTHONPATH=/opt/hf python3 -c "import hwpforge; print(hwpforge.__version__)"

GitHub Releases are immutable once published, so wheels are never attached there after the fact. Every wheel and the source distribution instead live on PyPI's files page, with the same bytes and sha256 that pip sees, so an air-gapped host can download a file straight from that page and unpack it the same way as above. A Python-only fix, versioned X.Y.Z.N, is published to PyPI alone and has no Release of its own.

Example

import hwpforge

doc = hwpforge.Document.open("proposal.hwpx")
print(doc.outline()["outline"]["title"])
doc = doc.fill({"applicant": "홍길동", "date": "2026-09-17"}).document
doc.save("proposal-filled.hwpx")

Document is immutable. Every editing method returns a new document in a result object alongside the operation's report, and leaves the receiver unchanged, so the re-assignment above is not optional.

Operations

A failure raises HwpForgeError, whose code is the stable string to branch on. The codes below are the ones each operation raises for its own characteristic failure; any operation that has to decode the document first can also raise DECODE_FAILED.

Document methods

to_md(mode="lossless") keeps what the preservation scope lists, raises ENCODE_FAILED for an object the scope lists as refused, and may leave out anything else (paragraph styles, headers and footers …) without an error — the scope is the "Lossless 보존 범위" section of the Markdown bridge guide.

Constructors and accessors beside these: Document.open(path) (bounded at 100 MB, raising INPUT_TOO_LARGE beyond it), Document.from_bytes(data) (no bound — the caller already holds the bytes), to_bytes(), save(path), and len() / == / hash() over the bytes.

set_cell, insert_para, delete_para and stamp re-encode the whole package, so they refuse a document Hancom saved with INPUT_ENTRIES_NOT_CARRIED or INPUT_NOT_ROUNDTRIP_SAFE rather than drop the entries it carries. fill and patch work on such a document.

Module functions

Every report but templates() and schema() carries a warnings key, which is always present and worth reading before saving the result.

Documentation

• Guide: https://ai-scream.ai/HwpForge/guide/python.html
• Project: https://github.com/ai-screams/HwpForge

License

MIT OR Apache-2.0.