Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

jakal-hwpx

jakal-hwpx is a Python library for reading, editing, and writing both HWPX and HWP documents.

The package exposes a shared document API and format-specific implementations:

  • Document: the shared document API (HancomDocument remains a compatibility alias)
  • Beta DOCX addon WordDocument(Document): retains Word details and dispatches shared edits to a Word backend
  • 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 Document.

from jakal_hwpx import Document

doc = Document.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 Document

doc = Document.open("input.hwp")
doc.append_paragraph("Review complete")
doc.save("build/output.hwpx")

DOCX addon (beta)

Install the bundled DOCX addon with pip install "jakal-hwpx[docx]". Its implementation lives in jakal_hwpx.addons.docx and shares the same release as the core library. The default HWP/HWPX installation does not require python-docx; the addon and its backend load only when requested. The DOCX surface is released as a beta API in 1.1.0b1; behavior and fidelity may change based on feedback before the stable 1.1.0 release. Document.open("input.docx") returns a WordDocument, which retains the complete original DOCX package alongside its common model view.

from jakal_hwpx import Document
from jakal_hwpx.addons.docx import WordDocument

doc = Document.open("input.docx")
assert isinstance(doc, WordDocument)
doc.append_paragraph("Review complete")
doc.replace_text("Old text", "New text")
doc.save("build/output.docx")
doc.save("build/output.hwpx")  # Python conversion through the common model
doc.save("build/output.hwp")   # Python conversion through the common model

with doc.edit_word() as word:
    word.paragraphs[0].runs[0].bold = True

Untouched DOCX output is byte-identical. Shared edits preserve unrelated parts, and Word-specific details can be edited through the python-docx backend. HWP/HWPX output is generated in Python without Hancom Office. The common model retains supported content and formatting; unsupported Word features produce UserWarning messages during conversion. An external converter remains opt-in. The existing from jakal_hwpx import WordDocument import remains supported. See the DOCX addon and WordDocument for supported edits, requirements, and visual limits.

HWP and HWPX can also be exported to editable Word documents in Python:

Document.open("input.hwpx").save("build/from_hwpx.docx")
Document.open("input.hwp").save("build/from_hwp.docx")
word = Document.open("input.hwpx").to_docx_document()  # WordDocument

The low-level HwpxDocument and HwpDocument classes also provide save_as_docx() and to_docx_document(). This maps supported shared content and formatting; native equations and unsupported embedded objects require an explicit external converter. See the DOCX export limits.

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
Document 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.1.0b1

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.1.0b1
File Size Uploaded Provenance Actions
jakal_hwpx-1.1.0b1.tar.gz 463.0 kB Without provenance Details for jakal_hwpx-1.1.0b1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jakal-hwpx 1.1.0b1
File Interpreter ABI Platform Actions
jakal_hwpx-1.1.0b1-py3-none-any.whl Python 3 none any Details for jakal_hwpx-1.1.0b1-py3-none-any.whl

Total release size: 821.5 kB

Release files / jakal_hwpx-1.1.0b1.tar.gz

Download URL jakal_hwpx-1.1.0b1.tar.gz
Size 463.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b6211072cf3105ebdc5b770b177b698aac1e818262a3fd567f8888edf8528d9a
BLAKE2b-256 checksum
How to use checksums
5c97ac73f17b76d1e5a1fb4a1bf1633b107fb8234912bde1ae4ba6bb8136cc87
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.1.0b1-py3-none-any.whl

Download URL jakal_hwpx-1.1.0b1-py3-none-any.whl
Size 358.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
15a63825b5c58e571cc3954c7dce1fc9d04ef34299b5a2425dc399406a2678f5
BLAKE2b-256 checksum
How to use checksums
cb42b8d80d7c7dd6ad12f1f24418db6fc5da77d9b03b0fc3f8c91275dd19d039
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.1.0b1

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