python-hwpx
한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리
한국어 | English
기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제 한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라 Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다.
| 레포 | 역할 | |
|---|---|---|
| 📦 | python-hwpx |
순수 파이썬 HWPX 코어 (이 레포) |
| 🔌 | hwpx-mcp-server |
MCP 클라이언트(Claude Desktop 등)에서 HWPX 조작 |
| 🎯 | hwpx-plugin |
에이전트용 플러그인·스킬 번들 |
시작하기
pip install python-hwpx # Python 3.10+
from hwpx import HwpxDocument
doc = HwpxDocument.open("보고서.hwpx")
doc.add_paragraph("자동화로 추가한 문단입니다.")
doc.save_to_path("보고서-수정.hwpx")
무엇을 하나
- 읽기·추출 — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
- 편집 — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
- 양식 채우기 — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
- 생성 — 조립형 builder, 공문 lint·결재란, 사진대지·명패·조직도, mail merge, 신구대조표
- 변경추적·목차 — redline 저작, 네이티브 목차·상호참조
- 검증·안전 — XSD·패키지 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(
MutationReport)
자세한 내용: 사용 가이드 · API 레퍼런스 · 안정 API 표면 · 예제
양식 채우기 — 서식은 그대로, 값만
doc = HwpxDocument.open("신청서.hwpx")
result = doc.fill_by_path({
"성명 > right": "홍길동",
"소속 > right": "플랫폼팀",
})
doc.save_to_path("신청서-작성완료.hwpx")
라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
저장에는 영수증이 따라옵니다
report = doc.save_to_path("결과.hwpx", return_report=True)
print(report.actual_mode) # "patch" — 문서 재조립 없이 저장됨
print(report.preservation.untouched_part_payloads.to_dict())
# {"verified": 17, "changed": 0}
요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed). 전체 규칙은 안전한 쓰기 계약에 있습니다.
실측으로 말합니다
산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
- 한컴 오픈 476/476 all-pass — 우리가 만든 파일을 실한컴이 전부 엽니다
- 미수정 영역 바이트 보존 497/497 · 개인정보 0-leak
- 렌더 검증 416/476 + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: 실측 코퍼스 메트릭
기능별로 되는 것과 안 되는 것은 지원 매트릭스에 등급으로 명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
위 수치는 생성물 수용률 축입니다(만든 파일을 실한컴이 받는가). 문서 파싱 recall과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
비교
| python-hwpx | pyhwpx | pyhwp | |
|---|---|---|---|
| 대상 포맷 | .hwpx (OWPML/OPC) |
.hwpx |
.hwp (v5 바이너리) |
| 한/글 설치 | 불필요 | 필요 (Windows COM) | 불필요 |
| 크로스 플랫폼 | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
| 편집/생성 API | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
| AI 에이전트 연동 (MCP) | ✅ | ❌ | ❌ |
HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
알려진 제약
add_shape()/add_control()은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다.<hp:pic>그림 개체의 완전 자동 생성은 제공하지 않습니다.- 암호화된 HWPX는 지원하지 않습니다.
기여하기
help wanted · 로드맵 · Discussions · 내부 실전 가이드 · CONTRIBUTING
HWPX 내부 구조가 처음이라면 내부 실전 가이드부터 — 실제 한/글 동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
감사의 말
아래 공개 표준·프로젝트에 빚지고 있습니다.
- OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101) — HWPX가 기반하는 한국 산업 표준
- hancom-io/hwpx-owpml-model — OWPML 요소 구조 참조 모델 · neolord0/hwpxlib — 오라클 샘플 코퍼스
- edwardkim/rhwp — 멱등성·검증 게이트 설계 영감
- 범정부오피스 — 공무 문서 편집 워크플로 아이디어
License · Maintainer
Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file python_hwpx-4.2.0.tar.gz.
File metadata
- Download URL: python_hwpx-4.2.0.tar.gz
- Upload date:
- Size: 1.0 MB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
fb7e624b16ffe6c0752f5b083b681d74660ba4bdc9c78c87cb34d41266364d44
|
|
| MD5 |
133dc79361ff335e9b625594c97713b2
|
|
| BLAKE2b-256 |
1a4d26ec9fedee6fd15629780c7b8eb5ac4ca00c3d63798efaec5eecf360b476
|
Provenance
The following attestation bundles were made for python_hwpx-4.2.0.tar.gz:
Publisher:
release.yml on airmang/python-hwpx
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
python_hwpx-4.2.0.tar.gz -
Subject digest:
fb7e624b16ffe6c0752f5b083b681d74660ba4bdc9c78c87cb34d41266364d44 - Sigstore transparency entry: 2216793337
- Sigstore integration time:
-
Permalink:
airmang/python-hwpx@f6b79f010d40a190fa6a8391eb212835022b3851 -
Branch / Tag:
refs/tags/v4.2.0 - Owner: https://github.com/airmang
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f6b79f010d40a190fa6a8391eb212835022b3851 -
Trigger Event:
push
-
Statement type:
File details
Details for the file python_hwpx-4.2.0-py3-none-any.whl.
File metadata
- Download URL: python_hwpx-4.2.0-py3-none-any.whl
- Upload date:
- Size: 808.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e36fbbcdb798bb308a156713e08a482c4a16489a3d5ed6e2f6928b3c9297e8a6
|
|
| MD5 |
1d58f06b90956f99dc6b65c675549df8
|
|
| BLAKE2b-256 |
a8f7af9d5dbd2a072ab9f110243091bb597dd3b1f5c1d16b6953773ff2f96796
|
Provenance
The following attestation bundles were made for python_hwpx-4.2.0-py3-none-any.whl:
Publisher:
release.yml on airmang/python-hwpx
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
python_hwpx-4.2.0-py3-none-any.whl -
Subject digest:
e36fbbcdb798bb308a156713e08a482c4a16489a3d5ed6e2f6928b3c9297e8a6 - Sigstore transparency entry: 2216793797
- Sigstore integration time:
-
Permalink:
airmang/python-hwpx@f6b79f010d40a190fa6a8391eb212835022b3851 -
Branch / Tag:
refs/tags/v4.2.0 - Owner: https://github.com/airmang
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@f6b79f010d40a190fa6a8391eb212835022b3851 -
Trigger Event:
push
-
Statement type:
