unhwp
High-performance Python library for extracting HWP/HWPX Korean word processor documents to Markdown.
Installation
pip install unhwp
Quick Start
import unhwp
# Simple conversion
markdown = unhwp.to_markdown("document.hwp")
print(markdown)
# Extract plain text
text = unhwp.extract_text("document.hwp")
# Full parsing with images
with unhwp.parse("document.hwp") as result:
print(result.markdown)
print(f"Sections: {result.section_count}")
# Save images
for img in result.images:
img.save(f"output/{img.name}")
Handling Failures
UnhwpError.kind says why a call failed, so you can react to the reason instead of
matching on message text:
from unhwp import ErrorKind, ParseError
try:
with unhwp.parse(path) as result:
print(result.markdown)
except ParseError as err:
if err.kind in (ErrorKind.OLE_CONTAINER, ErrorKind.ZIP_ARCHIVE):
print("The file is damaged.")
elif err.kind in (ErrorKind.UNKNOWN_FORMAT, ErrorKind.UNSUPPORTED_FORMAT):
print("Not a supported HWP/HWPX document.")
elif err.kind in (ErrorKind.ENCRYPTED, ErrorKind.DISTRIBUTION_RESTRICTED):
print("The document cannot be opened without authorization.")
else:
# Also the right branch for a reason this build has no name for.
print(f"Extraction failed ({err.kind}): {err}")
The numbers behind ErrorKind are a stable ABI contract: a new reason takes the next free
number and existing ones are never renumbered. Always keep a final else — an
unrecognised value arrives as a plain int rather than an ErrorKind, so that a newer
native library stays usable. kind is ErrorKind.OTHER for failures raised by the wrapper
itself, and never ErrorKind.NONE (which means success).
Features
- Fast: Native Rust library with zero-copy parsing
- Complete: Extracts text, tables, images, and document structure
- Clean Output: Optional cleanup pipeline for polished Markdown
- Format Support: HWP 5.0, HWPX, and HWP 3.x (legacy)
API Reference
Functions
to_markdown(path) -> str
Convert an HWP/HWPX document to Markdown.
markdown = unhwp.to_markdown("document.hwp")
to_markdown_with_cleanup(path, cleanup_options=None) -> str
Convert and run the cleanup pipeline over the Markdown — standard cleanup when
cleanup_options is omitted.
markdown = unhwp.to_markdown_with_cleanup(
"document.hwp",
cleanup_options=unhwp.CleanupOptions.aggressive()
)
extract_text(path) -> str
Extract plain text content.
text = unhwp.extract_text("document.hwp")
parse(path, render_options=None) -> ParseResult
Parse a document with full access to content and images. result.markdown is rendered
with render_options; parse_bytes(data, render_options=None) does the same for a
document in memory.
with unhwp.parse("document.hwp") as result:
print(result.markdown)
print(result.text)
for img in result.images:
print(img.name, len(img.data))
detect_format(path) -> int
Detect the document format.
fmt = unhwp.detect_format("document.hwp")
if fmt == unhwp.FORMAT_HWP5:
print("HWP 5.0 format")
elif fmt == unhwp.FORMAT_HWPX:
print("HWPX format")
Classes
ParseResult
What parse() and parse_bytes() return; use it as a context manager or call close().
markdown,text,plain_text,json- The document renderedsection_count,image_count,title,author- About the documentimages,iter_images()- Embedded imagesget_tables(tsv=False)- Every table as CSV (RFC 4180), or tab-separated withtsv=True, in reading order:{"section", "index", "text"}— the section's number (from 1), the table's place among that section's tables (from 1), and the text. A merged cell's text is in its top-left position and the positions it covers are empty, so every record has the same number of fields:pandas.read_csv(io.StringIO(t["text"]))reads one.
RenderOptions
Options for Markdown rendering. Every field reaches the native library, and the defaults are the library's own.
opts = unhwp.RenderOptions(
include_frontmatter=True,
image_path_prefix="images/",
table_fallback="html",
cleanup=unhwp.CleanupOptions.default(),
)
with unhwp.parse("document.hwp", render_options=opts) as result:
print(result.markdown)
| Field | Default | Meaning |
|---|---|---|
image_path_prefix |
"assets/" |
Prefix of the image paths in the Markdown |
table_fallback |
"markdown" |
A table with merged cells: "markdown" (a merged cell's text in its first cell) or "html" (rowspan/colspan kept) |
max_heading_level |
4 |
Deepest heading level written (1-6) |
include_frontmatter |
False |
Document metadata as YAML frontmatter |
preserve_line_breaks |
True |
Line breaks inside a paragraph as Markdown hard breaks; False joins the lines |
include_empty_paragraphs |
False |
Keep empty paragraphs as blank lines |
list_marker |
"-" |
Marker of an unordered list item (one character) |
paragraph_spacing |
True |
A blank line after each paragraph |
escape_special_chars |
True |
Escape text that would read as Markdown syntax |
section_markers |
"none" |
"comment" writes <!-- section N --> before each section |
cleanup |
None |
A CleanupOptions to run over the output |
refine |
False |
The lossless shape-refinement pass (table shape, list numbering, link/image paths, frontmatter, section anchors) |
A value the library cannot honour — an unknown table_fallback, a max_heading_level
outside 1-6 — raises RenderError with kind == ErrorKind.INVALID_ARGUMENT when the
Markdown is produced.
CleanupOptions
The cleanup pipeline: string normalization, line cleaning (page numbers, repeated headers and footers), structural filtering, whitespace normalization.
opts = unhwp.CleanupOptions.minimal() # normalization only
opts = unhwp.CleanupOptions.default() # every stage ("standard")
opts = unhwp.CleanupOptions.aggressive() # every stage, headers and footers removed more eagerly
opts = unhwp.CleanupOptions.disabled() # no cleanup
opts = unhwp.CleanupOptions(preset="aggressive")
Constants
FORMAT_UNKNOWN- Unknown formatFORMAT_HWP5- HWP 5.0 binary formatFORMAT_HWPX- HWPX XML formatFORMAT_HWP3- HWP 3.x legacy format
Platform Support
- Windows (x64)
- Linux (x64)
- macOS (x64, ARM64)
Native library
The package ships the native library for your platform. To load another build of it — one
you compiled from the Rust crate, say — set UNHWP_LIB_PATH to that file. A path that names no file
is an error: importing raises OSError naming the path, rather than quietly loading the
packaged library instead.
License
MIT License - see LICENSE for details.
Links
Metadata
Release files for unhwp 0.23.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| unhwp-0.23.1.tar.gz | 8.8 MB | Without provenance | Details for unhwp-0.23.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| unhwp-0.23.1-py3-none-any.whl | Python 3 | none | any | Details for unhwp-0.23.1-py3-none-any.whl |
Total release size: 17.5 MB
Release files / unhwp-0.23.1.tar.gz
| Download URL | unhwp-0.23.1.tar.gz |
|---|---|
| Size | 8.8 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b40cee0cd794a27030b6305e186d2ebd424602ab2766c176f5f54fd364c38bf3
|
|
BLAKE2b-256 checksum How to use checksums |
5485cd6fcbfe06ca25655328c12830b55432210d0b05c25bbdfe575d31573fbb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / unhwp-0.23.1-py3-none-any.whl
| Download URL | unhwp-0.23.1-py3-none-any.whl |
|---|---|
| Size | 8.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aab0fdb92af5ab67d94b2698acb7ca4bbcbb6591de2a15f2c952927f02338957
|
|
BLAKE2b-256 checksum How to use checksums |
5375e0d664f6006459be2f5de2b83dfebf2c2332e690fe6b895f64cf4179f38f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for unhwp 0.23.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.