hwpapi

Pythonic automation for HWP (ํ•œ์ปด์˜คํ”ผ์Šค ํ•œ๊ธ€)

hwpapi

A slim Python facade over HWPโ€™s COM automation โ€” with dict-like collections, context-managed formatting, and a documented escape hatch to the raw action layer. 

pip install hwpapi

Sample output โ€” generated by tests/generate_v2_doc_artifacts.py running real HWP

5-minute tour

from hwpapi import App

# 1. Open a file โ€” `App` owns lifecycle only.
with App() as app:
    app.open("report.hwp")

    # 2. Everything document-scoped lives under `app.doc`.
    app.doc.insert_text("Hello, ํ•œ๊ธ€!\n")

    # 3. Collections are dict-like.
    app.doc.fields["author"] = "ํ™๊ธธ๋™"
    for name in app.doc.fields.names():
        print(name, "->", app.doc.fields[name].value)

    # 4. Formatting is a context scope.
    from hwpapi.context import charshape_scope
    with charshape_scope(app, bold=True, size=14, color="#C0392B"):
        app.doc.insert_text("important line\n")

    # 5. Need a raw action? Drop into `hwpapi.low`.
    from hwpapi.low import actions
    # e.g. actions._Action("MovePos")(...)

    app.save_as("report.pdf")

The blocks above are marked eval: false because they drive the HWP COM server on Windows. Every other code block on the site that does not need HWP runs at render time.

Whatโ€™s in the box

Two-layer API

App โ†’ app.doc for everyday scripts. hwpapi.low.* for raw actions and ParameterSet manipulation when you need it.

Guide โ†’

Dict-like collections

fields, bookmarks, hyperlinks, images, styles, paragraphs, tables โ€” every collection supports [], in, for, len, filter, names.

Guide โ†’

Context-managed formatting

charshape_scope, parashape_scope, styled_text snapshot the cursorโ€™s shape on enter and restore it on exit โ€” even if your code raises.

Guide โ†’

Friendly units

hwpapi.units.mm(210), pt(12), inch(8.27) โ€” no more HWPUNIT arithmetic.

Guide โ†’

Real exceptions

Every public call wraps pywintypes.com_error as an HwpApiError subclass with a useful message.

Reference โ†’

Escape hatch, documented

hwpapi.low.actions, hwpapi.low.parametersets, hwpapi.low.engine โ€” the 900+ action wrappers and 130+ ParameterSet classes, cleanly namespaced.

Guide โ†’

Where to next

Back to top