Skip to main content

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 work
  • HwpxDocument: direct HWPX package and XML editing
  • HwpDocument: direct native HWP object and binary editing

Module layers

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 control
  • append_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, paragraph
  • eq, equ, equation
  • pic, image, picture
  • table, tbl
  • bookmark, field, hyperlink
  • note, footnote, endnote
  • form, memo, chart, ole, shape
  • autonum, newnum
  • header, 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

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)

Source distribution for jakal-hwpx 1.0
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)

Table of built distributions (wheels) for jakal-hwpx 1.0
File Interpreter ABI Platform Actions
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.

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