Skip to content
JayyoPublic

About

Fill and edit Korean HWPX/HWP (한글) documents from Python on Linux: label-based form filling and LibreOffice previews

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

30 Commits

Folders and files

Repository files navigation

hwpx-fill

리눅스에서 한글 문서(HWPX, HWP)를 파이썬으로 만들고, 고치고, 양식을 채우는 도구입니다. 한컴오피스 없이 동작하고, 결과는 LibreOffice로 PDF·PNG를 뽑아 바로 확인할 수 있습니다.

English summary below.

빈 양식과 채운 결과

왼쪽은 hwpx-fill sample이 만든 빈 양식, 오른쪽은 hwpx-fill fill로 채운 결과입니다. 둘 다 이 도구의 render 명령으로 LibreOffice에서 렌더했습니다.

왜 만들었나

제가 내는 지원사업 서류는 거의 한글 양식입니다. 처음 손댄 건 2025년 10월, hwp 표를 엑셀로 뽑는 일이었습니다. 2026년 2월에는 사업계획서 작업에서 hwp 내용을 읽는 데 막혔고, 3월에는 DOCX로 바꿔 작업했지만 표가 깨지고 파일 손상 메시지가 떴습니다. 6월에 HWPX로 방향을 바꿔 이 패키지의 첫 버전을 만들었고, 지금은 기존 문서에서 표와 그림을 골라 새 양식에 옮기는 데도 씁니다.

HWPX는 ZIP 안의 XML이라 python-hwpx로 열고 저장할 수 있지만, 실제 양식을 채우다 보면 자잘한 문제가 계속 나옵니다.

  • 라벨이 성 명, 생 년 월 일처럼 띄어 쓰여 있어서 성명으로는 칸을 못 찾는다.
  • {{신청일}}을 써 두어도 한글이 글자 모양 단위로 run을 쪼개 저장해서 문자열 치환이 안 된다.
  • 병합 셀이 섞인 표에 행을 넣으면 표가 깨진다.
  • 줄바꿈, 가로 용지, 위첨자를 넣었는데 LibreOffice에서는 반영되지 않는다(쓰는 쪽 XML 문제였다).
  • 채운 파일 안의 미리보기(Preview/PrvText.txt)에 이전 내용이 그대로 남는다.

hwpx-fill은 python-hwpx 위에서 이런 부분을 처리하는 양식 채우기·문서 편집 API와 명령줄 도구입니다. 업무에서 쓰던 코드를 정리해서 공개했습니다.

설치

Python 3.10 이상이 필요합니다. PyPI에는 올리지 않았습니다.

pip install git+https://github.com/Jayyo/hwpx-fill
# 또는
git clone https://github.com/Jayyo/hwpx-fill && cd hwpx-fill && pip install -e .

python-hwpx는 테스트한 6.8.x로 제한했습니다.

문서를 만들고 채우는 데는 이것만으로 충분합니다. 결과를 PDF/PNG로 보고 싶다면 아래 렌더링을 설정하세요.

빠른 시작

hwpx-fill sample form.hwpx --data data.json    # 예제 양식과 채울 값
hwpx-fill inspect form.hwpx                     # 표, 칸 주소, 자리표시자 확인
hwpx-fill fill form.hwpx data.json -o filled.hwpx
hwpx-fill render filled.hwpx --png              # filled.pdf, filled-1.png

.hwp 파일도 그대로 넣고 받을 수 있습니다(fill form.hwp data.json -o filled.hwp). HWP 5 변환은 python-hwpx가 합니다.

inspect는 양식에 어떤 라벨이 있는지 보여 줍니다.

form.hwpx: 2 table(s)

table 1: 4 x 4
  A1 성    명  |  B1 ·  |  C1 생 년 월 일  |  D1 ·
  A2 소    속  |  B2 ·  |  C2 직    위  |  D2 ·
  A3 연 락 처  |  B3 ·  |  C3 이 메 일  |  D3 ·
  A4 주    소  |  B4:D4 ·

table 2: 3 x 4
  A1 대 여 품 목  |  B1:D1 ·
  A2 수    량  |  B2 ·  |  C2 대 여 기 간  |  D2 ·
  A3 사 용 목 적  |  B3:D3 ·

placeholders: {{신청일}}, {{신청인}}

채울 값은 JSON으로 줍니다. 값은 모두 문자열이어야 합니다(전화번호 앞자리 0 같은 것이 사라지지 않도록 숫자는 받지 않습니다).

{
  "cells": {
    "성명": "홍길동",
    "주소": "서울특별시 중구 예시로 12, 3층",
    "사용 목적": "학과 세미나 발표 및 질의응답\n(3일간, 공학관 201호)"
  },
  "placeholders": {
    "신청일": "2026년 10월 22일"
  },
  "tables": {
    "2": { "수량": "각 1대" }
  }
}
  • cells: 라벨 경로 → 값. 모든 표에서 라벨을 찾습니다.
  • placeholders: 본문·표·머리말의 {{이름}}을 바꿉니다. 키에는 중괄호를 쓰지 않습니다.
  • tables: 같은 라벨이 여러 표에 있을 때 표 번호(inspect에 나오는 번호, 1부터)로 범위를 좁힙니다.
  • 값의 \n은 칸 안 줄바꿈이 됩니다.

하나라도 찾지 못하거나 애매한 키가 있으면 이유를 출력하고 아무것도 쓰지 않습니다. --allow-missing을 주면 양식에 없는 라벨·자리표시자만 건너뛰고 나머지를 채웁니다. --dry-run은 어느 칸에 들어갈지만 보여 줍니다.

$ cat bad.json
{"cells": {"성명": "홍길동", "이름": "김철수"}}
$ hwpx-fill fill form.hwpx bad.json -o out.hwpx
hwpx-fill: not_found: '이름': no cell reads '이름'
hwpx-fill: 1 of 2 cell keys resolved; nothing was written

라벨 경로

키 뜻
성명 라벨 성명 칸의 오른쪽 칸
주소 > down 라벨 아래 칸
금액 > right > right 오른쪽으로 두 칸
2분기 > 아래 오른쪽·왼쪽·위·아래도 됩니다
  • 라벨은 먼저 공백을 하나로 줄여서 비교하고, 맞는 칸이 없으면 공백을 모두 빼고 비교합니다. 그래서 성명이 성 명을 찾습니다. 끝의 :는 무시합니다. 부분 일치나 비슷한 말은 찾지 않습니다.
  • 이동은 한글에서 커서를 옮기는 것처럼 병합 셀을 건너뜁니다.
  • 모든 키를 먼저 찾은 뒤에 씁니다. 라벨이 없거나(not_found), 여러 칸에 있거나(ambiguous), 두 키가 같은 칸에 쓰거나 다른 키의 라벨을 덮어쓰는 경우(conflict)는 보고하고 쓰지 않습니다.
  • 표나 그림, 누름틀이 들어 있는 칸에는 쓰지 않습니다(not_plain). 글자를 쓰면 그것들이 지워지기 때문입니다.
  • 문서에 넣을 수 없는 제어 문자가 든 값(bad_value)도 쓰기 전에 걸러냅니다. 값의 \r\n은 줄바꿈으로 바뀝니다.
  • 이미 글자가 있는 칸을 덮어쓰면 알려 줍니다.

파이썬에서 쓰기

import hwpx_fill as hf

doc = hf.open("form.hwpx")          # .hwp도 됩니다
result = hf.fill(
    doc,
    {"성명": "홍길동", "주소": "서울특별시 중구 예시로 12, 3층"},
    placeholders={"신청일": "2026년 10월 22일"},
)
if not result.written:              # 문제가 하나라도 있으면 문서를 바꾸지 않습니다
    for p in result.problems:
        print(p.kind, p.key, p.detail)
    if result.placeholders and result.placeholders.missing:
        print("양식에 없는 자리표시자:", result.placeholders.missing)
    raise SystemExit(1)
hf.save_as(doc, "filled.hwpx")

새 문서를 만들 때는 워드프로세서 용어로 다룹니다. charPr/paraPr id나 XML은 직접 만지지 않습니다.

doc = hf.new()
hf.set_page(doc, size="A4", orientation="LANDSCAPE")
hf.add_paragraph(doc, "분기 보고", align="CENTER", bold=True, size_pt=18)
hf.add_paragraph(doc, "본문은 자간 -5%, 장평 95%.", reset=True, spacing=-5, ratio=95, line_spacing=160)

tbl = hf.add_table(doc, 3, 3, data=[["구분", "1분기", "2분기"], ["매출", "100", "150"], ["비고", "", ""]])
hf.merge_cells(doc, tbl, "B3:C3")
for cell in ("A1", "B1", "C1"):
    hf.set_cell_style(doc, tbl, cell, shading="#E8EEF7", h_align="CENTER")
hf.set_cell(tbl, "B3", "첫 줄\n둘째 줄")

hf.save_as(doc, "report.hwpx")

다른 문서에서 표·그림 가져오기

해마다 양식이 바뀌는 신청서는 작년에 낸 파일에 표와 그림이 이미 다 들어 있습니다. copy_blocks는 그 문단·표·그림을 올해 양식의 정해진 자리로 옮깁니다. 한글에서 복사해 붙이면 글자 모양 번호가 꼬이거나 그림이 빠지는 일이 있어서 파일 단위로 처리합니다.

hwpx-fill blocks 2025_제출본.hwpx        # 문단 번호, 종류(text/table/picture), 그림 id
hf.copy_blocks("2026_양식.hwpx", "작업본.hwpx", [
    # '□ 추진 실적'부터 '□ 향후 계획' 앞까지를 양식의 '(작성)' 문단 자리에
    {"src": "2025_제출본.hwpx", "select": {"from": "□ 추진 실적", "to": "□ 향후 계획"},
     "replace": "(작성)"},
    # '가입자'가 들어 있는 표를 양식의 빈 성과표 자리에
    {"src": "2025_제출본.hwpx", "select": {"table_contains": "가입자"}, "replace_table": "성과지표"},
])
hf.replace_image("작업본.hwpx", "작업본.hwpx", "image3", "새_차트.png")   # 자리와 너비는 그대로
  • 고르는 방법: 문단 번호(5, "5-9", [5, 7]), 글자 범위({"from": ..., "to": ...}, to 문단은 빼고), 표 안 글자(table_contains), 그림 id(image).
  • 넣는 자리: after, before, replace(문단), replace_table(표), replace_range(범위). 아무것도 없으면 문서 끝에 붙입니다. 기준 문단이 표 칸 안에 있으면(본문 전체를 큰 칸 하나에 넣은 양식) 그 칸 안에 넣습니다.
  • replace_table은 표가 혼자 있는 문단이면 문단째 바꾸고, 같은 문단에 글자나 다른 개체가 있으면 표만 바꿉니다(이때는 표 하나만 골라야 합니다). 구역 첫 문단을 바꾸면 그 문단이 갖고 있던 쪽 설정·단·머리말·꼬리말·쪽 번호는 새로 들어온 첫 문단으로 옮겨 둡니다.
  • 옮기면서 하는 일: 글자·문단 모양, 테두리/배경, 탭, 글꼴, 번호/글머리표를 대상 문서 header에 새 번호로 복제하고, 스타일은 이름으로 맞추고, 그림 파일을 복사해 등록하고, 표·그림 id를 새로 매기고, 줄 배치 캐시(linesegarray)를 지워 한글이 다시 배치하게 합니다. 원본의 쪽 설정·머리말·쪽 번호는 옮기지 않습니다. 파일 안에 없고 링크만 걸린 그림은 복사하지 않고 오류를 냅니다.
  • 너비: 원본 본문 폭과 대상 자리(본문 폭 또는 칸 안쪽 폭)가 다르면 표와 그림을 그 비율로 줄이거나 늘립니다. 그림은 가로세로 비율을 유지합니다. "fit": False로 끌 수 있습니다.
  • replace_image는 그림의 틀과 위치를 두고 내용만 바꿉니다. 원본 픽셀 크기(orgSz, imgClip)를 새 그림에 맞춰 다시 써서 한글에서 잘리거나 작아지지 않게 하고, 더 이상 쓰이지 않는 옛 그림 파일은 지웁니다. PNG, JPEG, GIF, BMP.

명령 정리

CLI

명령 하는 일
sample OUT [--data JSON] 예제 양식(장비 대여 신청서)과 채울 값을 만든다
inspect FILE [--json] 표 번호, 칸 주소와 내용, 병합 범위, 자리표시자
blocks FILE [--all] [--json] 본문 문단·표·그림 목록 (copy_blocks에 쓸 번호와 그림 id)
fill FORM DATA -o OUT JSON으로 양식을 채운다. --dry-run, --allow-missing, --json, --force
export FILE [-f text|markdown|html] 텍스트로 내보내기 (python-hwpx의 exporter)
render FILE [--png] [--pages 1-3] [--dpi N] LibreOffice로 PDF, 필요하면 PNG
setup-render [--oxt PATH] [--reset] 렌더용 H2Orestart 설치
doctor [--probe] 설치 상태 확인, --probe는 실제로 렌더해 본다
hancom setup|convert|text Windows의 한컴오피스로 변환 (선택 기능, 아래 참고)

FILE, FORM, OUT은 .hwpx와 .hwp 모두 됩니다. 이미 있는 파일은 --force 없이 덮어쓰지 않습니다.

종료 코드: 0 성공, 2 잘못된 입력, 3 찾지 못한 키·애매한 키, 4 렌더링이 준비되지 않음, 5 변환 실패.

Python API (import hwpx_fill as hf)

분류 함수
파일 new, open, save_as, verify
양식 fill, fill_fields, list_tables, find_placeholders, replace_text
글자·문단 add_paragraph, set_char(범위 지정 가능), set_para
쪽 set_page, set_columns, add_header_footer(쪽 번호 포함), set_page_border, add_section
문서 간 재사용 list_blocks, copy_blocks, replace_image (.hwpx 파일 단위)
표 add_table, set_cell, merge_cells, split_cell, set_cell_style, set_table_border, set_column_widths, add_table_row, del_table_row, add_table_col, del_table_col
그 밖 insert_image, add_bullet_list, add_numbered_list, add_hyperlink, add_bookmark, add_footnote, add_endnote, add_memo, add_page_break, add_column_break, list_styles, export, iter_runs
모듈 hf.render (to_pdf, to_png, setup, probe), hf.hancom (convert, text)

글자 모양 인자: bold, italic, size_pt, color, highlight, underline(+underline_shape), strike, outline, shadow, emboss, engrave, sup, sub, spacing(자간), ratio(장평), rel_sz, offset, sym_mark, font_hangul/font_latin/font_hanja. 문단 모양 인자: align, line_spacing(+line_spacing_type), space_before, space_after, left_margin, right_margin, first_indent(음수는 내어쓰기), border, fill_color, break_latin, break_nonlatin, widow_orphan, keep_with_next.

렌더링

LibreOffice는 HWP/HWPX를 직접 읽지 못합니다. H2Orestart 확장이 그 역할을 하는데, 이 확장은 Java로 되어 있어서 Java 런타임이 필요합니다.

sudo apt install libreoffice-writer libreoffice-java-common default-jre poppler-utils
hwpx-fill setup-render     # H2Orestart 0.7.14를 받아 SHA-256 확인 후 설치
hwpx-fill doctor --probe
  • 렌더는 hwpx-fill 전용 LibreOffice 프로필(~/.local/share/hwpx-fill/libreoffice, HWPX_FILL_LO_PROFILE로 변경)에서 돌립니다. 평소 쓰는 LibreOffice 프로필은 건드리지 않고, LibreOffice 창이 열려 있어도 상관없습니다.
  • 확장 설치는 setup-render에서만 합니다. render나 verify가 몰래 설치하거나 고치는 일은 없습니다. 확장이 없으면 그렇다고 알려 주고 끝납니다.
  • 같은 프로필을 쓰는 렌더는 하나씩 돌고, 시간이 지나면 자기가 띄운 LibreOffice 프로세스만 정리합니다.
  • 다른 버전을 쓰려면 hwpx-fill setup-render --oxt H2Orestart.oxt. Ubuntu/Debian의 libreoffice-h2orestart 패키지(0.6.x)도 쓸 수는 있지만 테스트는 0.7.14로 했습니다. 0.8.0은 레이아웃이 조금 달라서 아직 기본값으로 두지 않았습니다.

LibreOffice 렌더는 미리보기일 뿐 한글과 같은 화면은 아닙니다. 확인한 차이는 이렇습니다.

  • 표 행 높이: 한글은 내용에 맞춰 행을 늘리지만 LibreOffice는 저장된 높이로 그립니다. 칸에 긴 값을 넣으면 LibreOffice 미리보기에서만 글자가 칸을 넘칠 수 있습니다. 그래서 add_table은 높이를 안 주면 행마다 약 7mm를 잡습니다.
  • 칸 안 여백(cellMargin)을 그리지 않습니다.
  • 각주·미주 본문과 메모는 그리지 않습니다(hf.LO_UNRENDERED_FEATURES).
  • 함초롬 글꼴이 없으면 다른 한글 글꼴로 바뀌어서 줄이 바뀌는 위치가 달라집니다.

정확한 결과가 필요하면 한글에서 열어 보거나 아래 Windows 변환기를 쓰세요.

지원하지 않는 것

  • .hwp는 python-hwpx 6.8의 HWP 5 변환기로 읽고 씁니다. 읽을 때 python-hwpx가 옮기지 못한 부분을 알려 주면 CLI가 경고로 출력합니다. 한글이 만든 파일과 똑같다는 보장은 없으니 제출할 문서는 한글에서 한 번 열어 보세요.
  • 도형, 글상자, 수식, 차트, 바탕쪽, 변경 추적은 만들지 않습니다. python-hwpx 6.8에 일부 API가 있지만 LibreOffice로 확인할 방법이 없어서 감싸지 않았습니다.
  • 누름틀(필드)은 채우지 않습니다. 표 라벨과 {{자리표시자}}만 다룹니다. 누름틀은 python-hwpx의 doc.fields를 직접 쓰면 됩니다.
  • 병합 셀을 가로지르는 행·열 추가와 삭제는 거부합니다. split_cell로 병합을 먼저 풀어야 합니다.
  • 저장할 때 미리보기 그림(Preview/PrvImage.png)은 빈 그림으로 바뀝니다. 다음에 한글에서 저장하면 다시 생깁니다. save_as(..., refresh_preview=False)로 끌 수 있습니다.
  • 테스트는 코드로 만든 문서와 한글 저장 형태를 흉내 낸 XML로 합니다. 실제 기관 양식은 저장소에 넣지 않았습니다.

Windows 한컴오피스로 변환 (선택, 실험적)

한글 레이아웃 그대로의 PDF나 한글이 직접 저장한 .hwp가 필요할 때, 한컴오피스 2024와 pyhwpx가 설치된 Windows PC에 SSH로 파일을 보내 변환합니다.

한글의 COM 서버는 로그인한 사용자의 데스크톱 세션에서만 동작하고, SSH 세션에서 바로 부르면 0x80080005로 실패합니다. 그래서 작업을 큐 폴더에 넣고, Windows에 한 번 등록해 둔 예약 작업("사용자가 로그온한 경우에만 실행")이 데스크톱 세션에서 com_worker.py를 돌리게 했습니다.

export HWPX_FILL_HANCOM_HOST=winpc        # ~/.ssh/config 별칭도 됨
export HWPX_FILL_HANCOM_USER=me
# 선택: HWPX_FILL_HANCOM_PORT, HWPX_FILL_HANCOM_DIR (기본 C:\Users\<user>\hwpx-fill), HWPX_FILL_HANCOM_TASK

hwpx-fill hancom setup                    # 워커를 복사하고, Windows에서 한 번 실행할 schtasks 명령을 출력
hwpx-fill hancom convert filled.hwpx filled.hwp
hwpx-fill hancom convert filled.hwpx filled.pdf
  • 설정은 환경 변수로만 받고 기본 호스트나 계정은 없습니다.
  • SSH는 키 인증만 씁니다(BatchMode). 비밀번호는 저장하지도 보내지도 않습니다.
  • 작업마다 폴더가 따로 생기고 끝나면 지웁니다. 워커는 정해진 변환 동작만 하고, 작업 폴더 안의 정해진 파일 이름만 다룹니다. 클라이언트가 시간 초과로 포기한 작업의 폴더는 다음에 워커가 실행될 때 하루 이상 지난 것부터 지웁니다.
  • 한글이 멈추면 예약 작업도 계속 실행 중으로 남습니다. 그때는 작업 스케줄러에서 작업을 끝내 주세요.
  • 공개 전 버전은 실제 Windows PC에서 써 왔지만, 공개하면서 인증 방식과 큐 구조를 바꿨고 바뀐 부분은 아직 가짜 ssh/scp와 가짜 pyhwpx로만 테스트했습니다.

개발

pip install -e '.[test]'
pytest                                   # 렌더 환경이 없으면 렌더 테스트는 건너뜀
HWPX_FILL_REQUIRE_RENDER=1 pytest        # 건너뛰지 말고 실패로 처리

확인한 환경: Ubuntu 24.04, Python 3.10/3.12, python-hwpx 6.8.0, LibreOffice 24.2, H2Orestart 0.7.14.

English summary

I started this in October 2025 to get tables out of HWP files for my own grant applications, and moved to HWPX in June 2026 after converting to DOCX kept breaking tables. hwpx-fill creates, edits and fills Korean 한글 documents (HWPX, and HWP 5 through python-hwpx's converter) from Python on Linux, without Hancom Office. It is built on python-hwpx. It finds labels that forms space out for justification (성 명), replaces {{placeholders}} that Hancom splits across runs, inserts and deletes rows and columns in tables with merged cells, writes line breaks and landscape pages in the form LibreOffice renders, and rebuilds the stale preview text a filled file would otherwise carry. copy_blocks moves paragraphs, tables and pictures from one HWPX file into a slot of another (last year's application into this year's form), cloning the style definitions they refer to, copying images and scaling to the target width; replace_image swaps a picture while keeping its frame.

pip install git+https://github.com/Jayyo/hwpx-fill
hwpx-fill sample form.hwpx --data data.json
hwpx-fill inspect form.hwpx
hwpx-fill fill form.hwpx data.json -o filled.hwpx
hwpx-fill setup-render && hwpx-fill render filled.hwpx --png

Every key is resolved before anything is written. If a label is missing or ambiguous, two keys collide, or a target cell contains a table, picture or field, nothing is written (in the CLI and in hf.fill). Rendering uses LibreOffice with the H2Orestart import filter in a LibreOffice profile owned by hwpx-fill, installed only by setup-render. An optional, experimental client converts files through Hancom Office on a Windows PC over SSH. Python 3.10+, python-hwpx 6.8.x.

라이선스

MIT. 의존하는 python-hwpx는 Apache-2.0입니다. H2Orestart(GPL-3.0)는 이 저장소에 들어 있지 않고, setup-render가 GitHub 릴리스에서 받아 설치합니다.

About

Fill and edit Korean HWPX/HWP (한글) documents from Python on Linux: label-based form filling and LibreOffice previews

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages