Skip to main content

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 supported document operations. Conversion is one way: editing produces HWPX. See the input and loss policy below.

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

Artifact Platform Needs
cp39-abi3-manylinux_2_28_x86_64 Linux x86_64 glibc 2.28 or newer
cp39-abi3-manylinux_2_28_aarch64 Linux aarch64 glibc 2.28 or newer
cp39-abi3-macosx_11_0_arm64 macOS arm64 macOS 11 or newer
cp39-abi3-macosx_10_12_x86_64 macOS x86_64 macOS 10.12 or newer
cp39-abi3-win_amd64 Windows x64 —
hwpforge-<version>.tar.gz source distribution Rust 1.92 and maturin

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 HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX).

Document methods

Method Returns Characteristic failures
inspect(*, styles=False) InspectReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
outline() OutlineReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
fields() FieldsReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
validate() ValidateReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX) (an invalid document reports, not raises)
read(*, section, paras, table, field) ReadReport READ_TARGET_REQUIRED, READ_PARAS_INVALID, READ_PARA_RANGE_INVALID, TABLE_NOT_FOUND
diff(revised) DiffReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
stamp_plan() StampPlanReport HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
to_json(*, styles=True) TextResult[ToJsonReport] HWP5_DECODE_FAILED (malformed HWP5) or DECODE_FAILED (malformed HWPX)
export_section(*, section, styles=True) TextResult[ExportSectionReport] SECTION_OUT_OF_RANGE
to_md(*, mode="styled") TextResult[ToMdReport] ENCODE_FAILED (mode="lossless": see the note below)
to_pdf(*, font_dirs, discovery, degraded, partial_cache_reject) BytesResult[ToPdfReport] PDF_RENDER_FAILED
fill(values) DocumentResult[FillReport] FIELD_NOT_FOUND, FIELD_NOT_FILLABLE, EMPTY_FIELD_VALUE
set_cell(*, table, at, right_of, below, text, specs) DocumentResult[SetCellReport] TABLE_NOT_FOUND, CELL_NOT_FOUND, INPUT_ENTRIES_NOT_CARRIED
patch(*, section, patch) DocumentResult[PatchReport] JSON_PARSE_FAILED, PATCH_FAILED, PROTECTED_FIELD_RANGE
insert_para(*, section, anchor, text, before=False) DocumentResult[StructuralReport] PARAGRAPH_OUT_OF_RANGE, INPUT_ENTRIES_NOT_CARRIED
delete_para(*, section, indexes) DocumentResult[StructuralReport] PARAGRAPH_OUT_OF_RANGE, INPUT_ENTRIES_NOT_CARRIED
stamp(request, *, manifest=True) DocumentResult[StampReport] INPUT_ENTRIES_NOT_CARRIED, ENCODE_SEMANTIC_LOSS
restyle(*, preset) DocumentResult[RestyleReport] PRESET_NOT_FOUND, ENCODE_SEMANTIC_LOSS

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. The lossless text is a machine-oriented view for checking that scope: convert_md refuses it (MD_DECODE_FAILED), and round-trip edits go through to_json/from_json.

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

Function Returns Characteristic failures
convert_md(text, *, preset="default", base_dir=None) DocumentResult[ConvertMdReport] PRESET_NOT_FOUND
from_json(text, *, base=None) DocumentResult[EncodeReport] JSON_PARSE_FAILED
convert_hwp5(data, *, carry_layout_cache=True) DocumentResult[ConvertHwp5Report] HWP5_DECODE_FAILED
templates() TemplatesReport —
schema(*, kind="document") SchemaReport —

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

Documentation

License

MIT OR Apache-2.0.

0.18 error migration

Operation codes now use the canonical OpsCode vocabulary across Python, CLI and MCP. Read target failures use SECTION_OUT_OF_RANGE, TABLE_NOT_FOUND and FIELD_NOT_FOUND.

File I/O raises HwpForgeIOError (HwpForgeError and OSError), or HwpForgeFileNotFoundError for an absent input (also FileNotFoundError). Codes are FILE_READ_FAILED, FILE_WRITE_FAILED, and FILE_NOT_FOUND; the size cap remains INPUT_TOO_LARGE. OS fields and copy/pickle reconstruction are preserved. Exact type checks and except PermissionError need updating. Document.save to a missing parent directory now raises HwpForgeIOError (FILE_WRITE_FAILED), not FileNotFoundError. Change except FileNotFoundError around save to except HwpForgeIOError or except OSError. Install matching native and Python package versions.

HWP5 input and loss acceptance

Document.open("form.hwp") and Document.from_bytes(data) accept HWP5 input. inspect, outline, read, fields, validate, diff (both inputs), stamp_plan, to_md, to_json, export_section, and the five edits convert through the shared HWP5-to-HWPX path. Outputs are HWPX.

fill, set_cell, insert_para, delete_para, and stamp default to accept_conversion_loss=False. Semantic conversion loss raises HWP5_CONVERSION_LOSS with rejected warnings in error.details["warnings"]. Review them before explicitly passing accept_conversion_loss=True. The order is conversion, existing operation, then conversion-loss refusal; existing editing admission checks remain in force. Reads report warnings.

Existing warnings are unchanged. HWP5 input adds a separate report key: conversion = {"source_format": "hwp5", "warnings": [...]}. Each warning has stage, code, message, and optional location. Diff reports converted roles under conversion.base and conversion.revised. JSON and Markdown payloads contain no conversion metadata.

save returns None. After a successful write, a save that converts raw HWP5 emits its conversion warnings, including accepted loss and non-loss warnings, as standard UserWarnings with the code and any known location. Python's warning filters apply: the default filter shows repeats once, and an error filter raises after the file is written. For the full list, use the conversion report of a read or edit, or warnings.catch_warnings(record=True) with warnings.simplefilter("always") inside it.

save rejects .hwp (case insensitive) with INVALID_EXTENSION. Saving raw HWP5 converts to HWPX and also requires accept_conversion_loss=True if lossy. The identity of the file read by Document.open is retained through instance edits. Saving over that HWP5 file, including symlink and hard-link aliases, raises INVALID_OUTPUT_PATH even after its original path is deleted or replaced. Protection applies to the file read at open time, not the file currently at that path. The file is identified by device and inode, so a new file that received the deleted source's inode is refused too; save to another path in that case. Only the output identity is looked up when saving; lookup failures other than an absent output raise FILE_WRITE_FAILED. New targets and HWPX in-place saves remain allowed. Output paths must remain stable while saving.

Bytes-only constructors and the generating functions convert_hwp5, convert_md, and from_json have no source file identity to protect; callers must keep outputs separate from their original files. Bytes/text results perform no writes. Automatic HWP5 conversion for from_json(base=...), patch, and restyle is out of scope: they still raise HWP5_INPUT; explicitly convert their input first.

Metadata

Release files for hwpforge 0.19.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for hwpforge 0.19.1
File Size Uploaded Provenance Actions
hwpforge-0.19.1.tar.gz 3.3 MB Without provenance Details for hwpforge-0.19.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for hwpforge 0.19.1
File Actions
hwpforge-0.19.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for hwpforge-0.19.1-cp39-abi3-win_amd64.whl
hwpforge-0.19.1-cp39-abi3-manylinux_2_28_x86_64.whl CPython 3.9 abi3 Linux glibc 2.28+ x86-64 Details for hwpforge-0.19.1-cp39-abi3-manylinux_2_28_x86_64.whl
hwpforge-0.19.1-cp39-abi3-manylinux_2_28_aarch64.whl CPython 3.9 abi3 Linux glibc 2.28+ ARM64 Details for hwpforge-0.19.1-cp39-abi3-manylinux_2_28_aarch64.whl
hwpforge-0.19.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for hwpforge-0.19.1-cp39-abi3-macosx_11_0_arm64.whl
hwpforge-0.19.1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for hwpforge-0.19.1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 38.4 MB

Release files / hwpforge-0.19.1.tar.gz

Download URL hwpforge-0.19.1.tar.gz
Size 3.3 MB
Tags Source
SHA-256 checksum
How to use checksums
80bca2f2e2ee88653b52628acdd06c55d586cb0312dfffead2b6717ad64e5862
BLAKE2b-256 checksum
How to use checksums
40647e6e59d9a177bace0763d0b08245bb421387a6eaf0a7fd7008901fe9556f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hwpforge-0.19.1-cp39-abi3-win_amd64.whl

Download URL hwpforge-0.19.1-cp39-abi3-win_amd64.whl
Size 7.6 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
39a379d701a695f6d40fba396bf2fef450df53352cfe0c6e466e0cb75b19c4b3
BLAKE2b-256 checksum
How to use checksums
01fe0f5ca8fd35c7a8c6575daa9dff1666484aac1a37cf80187be598302629a4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hwpforge-0.19.1-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL hwpforge-0.19.1-cp39-abi3-manylinux_2_28_x86_64.whl
Size 7.2 MB
Tags CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
e136378be6c127070c748e509d4d2d9fd57c33828f71cc45ec680352061a7fe6
BLAKE2b-256 checksum
How to use checksums
903f7e95441fe5a84712d55790a3d23496e36cef16b33663e2c8e05ec3acdb6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hwpforge-0.19.1-cp39-abi3-manylinux_2_28_aarch64.whl

Download URL hwpforge-0.19.1-cp39-abi3-manylinux_2_28_aarch64.whl
Size 6.7 MB
Tags CPython 3.9 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
d585533b725cc53618cc8866382ae1d7df9e1fd6fe0ba3e193e5a6b92ecc8add
BLAKE2b-256 checksum
How to use checksums
fb7e1750306bd475e529b264a6bba2422f3d3d6fae285d929400764ec18409c5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hwpforge-0.19.1-cp39-abi3-macosx_11_0_arm64.whl

Download URL hwpforge-0.19.1-cp39-abi3-macosx_11_0_arm64.whl
Size 6.6 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
eb2b9765e946882d23c1632def90e20d349bcab1495480e14be026f7700bf0db
BLAKE2b-256 checksum
How to use checksums
1f43dbf0f56d6352d2c9c27ee5fdc9b462d429f7dcbccca1cbb62b985d80c332
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / hwpforge-0.19.1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL hwpforge-0.19.1-cp39-abi3-macosx_10_12_x86_64.whl
Size 7.0 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
0fced47dc4f66b7d337c8a801cc53a4d7270a5cdd746e6b430d397a0de5a9cdd
BLAKE2b-256 checksum
How to use checksums
61a1765d99aa30ca6d85a5a9a5b19b655a6885b90aa659cdbcf4498aa3e77cca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.12.13 {"installer":{"name":"uv","version":"0.12.13","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for hwpforge 0.19.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page