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 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

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 DECODE_FAILED.

Document methods

Method Returns Characteristic failures
inspect(*, styles=False) InspectReport DECODE_FAILED
outline() OutlineReport DECODE_FAILED
fields() FieldsReport DECODE_FAILED
validate() ValidateReport DECODE_FAILED (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 DECODE_FAILED
stamp_plan() StampPlanReport DECODE_FAILED
to_json(*, styles=True) TextResult[ToJsonReport] DECODE_FAILED
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.

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.

Metadata

Release files for hwpforge 0.18.0

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.18.0
File Size Uploaded Provenance Actions
hwpforge-0.18.0.tar.gz 4.3 MB Without provenance Details for hwpforge-0.18.0.tar.gz

Built distributions (wheels)

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

Total release size: 38.7 MB

Release files / hwpforge-0.18.0.tar.gz

Download URL hwpforge-0.18.0.tar.gz
Size 4.3 MB
Tags Source
SHA-256 checksum
How to use checksums
0e9d1906ec82cc6c77319aacccef696614b5ca25bdc352e5695b88b64fabf26c
BLAKE2b-256 checksum
How to use checksums
b94be4cc6340ca5e6126ce7b130043dc4192b9e288d28f419e94c6a1e7559d58
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL hwpforge-0.18.0-cp39-abi3-win_amd64.whl
Size 7.4 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
3f97ae16e6ced97462a56dc459b25bd0f0c378c9844f88c22c49e68ae69d7275
BLAKE2b-256 checksum
How to use checksums
d588e5c1682d495aa20ebc8d44e15ad8277c2764c551aeb77fafbc3f01527a14
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL hwpforge-0.18.0-cp39-abi3-manylinux_2_28_x86_64.whl
Size 7.1 MB
Tags CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
50c967a2fb2abff36b37fa63b86ec2258cbf0d97aab5a1a12e3a75b9610c522c
BLAKE2b-256 checksum
How to use checksums
0e6cc54d1b177907ae964e7bffd2fd51341cc6fe198b1ba35320a12b0078515e
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL hwpforge-0.18.0-cp39-abi3-manylinux_2_28_aarch64.whl
Size 6.6 MB
Tags CPython 3.9 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
9b1c38d61df8fb2ab50ac767fa7f7fa566300f2dd91c4323efa7214777bf1a87
BLAKE2b-256 checksum
How to use checksums
50de0a2a3d907406cdc49175715606d3c09743da8931e3bcb99dc81869ba4748
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL hwpforge-0.18.0-cp39-abi3-macosx_11_0_arm64.whl
Size 6.4 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
2834fe65c12ee14581c0a4b30a58942de5cb147135ca856654addff48b3d7bb4
BLAKE2b-256 checksum
How to use checksums
7353df9474955d586bdea190f1efb3662c139bac395753342586fec13823f661
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL hwpforge-0.18.0-cp39-abi3-macosx_10_12_x86_64.whl
Size 6.8 MB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
b2eec7eab3d72c0347f4e416d8e9dc06287a8947e7e3cd263137d20a9def2333
BLAKE2b-256 checksum
How to use checksums
816a9e2164b91a0f60818d8667e5c8a44ab31969c88f13e47943ed4b1f46fa3f
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":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for hwpforge 0.18.0

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