jakal-hwpx
jakal-hwpx is a Python library for reading, editing, and writing both HWPX and HWP documents.
The package exposes three main layers:
HancomDocument: a format-neutral document model for most authoring and conversion workHwpxDocument: direct HWPX package and XML editingHwpDocument: direct native HWP object and binary editing
Installation
Requires Python 3.11 or newer.
python -m pip install --upgrade pip
python -m pip install jakal-hwpx
For local development:
python -m pip install -e .[dev]
Package name on PyPI is jakal-hwpx. Import path is jakal_hwpx.
Quick start
For most application code, start with HancomDocument.
from jakal_hwpx import HancomDocument
doc = HancomDocument.blank()
doc.metadata.title = "Quarterly report"
doc.append_paragraph("Sales summary")
doc.append_table(
rows=2,
cols=2,
cell_texts=[["Item", "Value"], ["Q1", "120"]],
)
doc.write_to_hwpx("build/report.hwpx")
doc.write_to_hwp("build/report.hwp")
Reading an existing document uses the same model:
from jakal_hwpx import HancomDocument
doc = HancomDocument.open("input.hwp")
doc.append_paragraph("Review complete")
doc.save("build/output.hwpx")
Direct HWPX authoring
Use HwpxDocument when you want explicit control over paragraphs, runs, controls, package parts, or validation.
from jakal_hwpx import HwpxDocument
doc = HwpxDocument.blank()
doc.append_paragraph("Inline math:")
doc.append_inline("equ", "x+y", width=3200, height=1800)
doc.append_inline("text", " = z")
doc.append_block("equ", "a+b", width=2800, height=1700)
doc.strict_validate()
doc.save("build/direct.hwpx")
There are now two authoring styles for controls:
append_block(kind=..., content=..., **kwargs): insert a block-level controlappend_inline(kind=..., content=..., **kwargs): reuse the target paragraph instead of creating a new one
Examples:
doc.append("equ", "x+y")
doc.append_inline("equ", "x+y")
doc.append_inline("text", " + z")
doc.append_block("table", [["A", "B"], ["1", "2"]])
Supported type aliases include:
text,paragrapheq,equ,equationpic,image,picturetable,tblbookmark,field,hyperlinknote,footnote,endnoteform,memo,chart,ole,shapeautonum,newnumheader,footer
The older explicit APIs still exist and remain the lowest-level stable surface:
append_equation()append_inline_equation()append_picture()append_shape()append_ole()append_table()
Choosing the right layer
| Layer | Use it for |
|---|---|
HancomDocument |
format-neutral authoring, conversion, block-level editing |
HwpxDocument |
direct HWPX package editing, XML placement, validation, control surgery |
HwpDocument |
direct native HWP object editing and low-level HWP inspection |
HwpBinaryDocument |
record tree, streams, DocInfo, and section model inspection |
Additional public API documentation lives in HWPX_MODULE.md.
Validation and release checks
Basic test run:
python -m pytest tests/test_document_model.py tests/test_hancom_document.py -q
Packaging and release validation:
python -m build
python -m twine check dist/*
python scripts/check_release.py --profile ci
On the Windows release machine, run the full Hancom gate as well:
python scripts/check_release.py --profile release
Documentation
- HWPX_MODULE.md: public module and API index
- docs/README.md: docs directory index
- docs/hancom-document.md:
HancomDocument - docs/hwpx-document.md:
HwpxDocument - docs/hwp-document.md:
HwpDocument - docs/bridge-and-binary.md: bridge and binary internals
- RELEASING.md: release checklist
License
Released under the MIT License.
Metadata
Release files for jakal-hwpx 1.0
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 |
|---|---|---|---|---|
| jakal_hwpx-1.0.tar.gz | 371.5 kB | Without provenance | Details for jakal_hwpx-1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jakal_hwpx-1.0-py3-none-any.whl | Python 3 | none | any | Details for jakal_hwpx-1.0-py3-none-any.whl |
Total release size: 671.2 kB
Release files / jakal_hwpx-1.0.tar.gz
| Download URL | jakal_hwpx-1.0.tar.gz |
|---|---|
| Size | 371.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1953dbec0307f645da3921c63bc6bec729cd4713c258988365c261428452f0d8
|
|
BLAKE2b-256 checksum How to use checksums |
af70138c8ba92fbe8058ce0590c94a932035912824ef66fa7eaf699e161e50c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / jakal_hwpx-1.0-py3-none-any.whl
| Download URL | jakal_hwpx-1.0-py3-none-any.whl |
|---|---|
| Size | 299.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b1fe145f8e4c3c5f1fe6f4fcbf5b8848d5244793223e1999e0192d898a54dbd9
|
|
BLAKE2b-256 checksum How to use checksums |
74bff2df72ea61cf01128e7f5facfb4a75368bdc581351ee77feaf130cb79ab5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for jakal-hwpx 1.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.