한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리
한국어 | English
한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고 파이썬이 도는 ChatGPT 채팅 안에서도 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다. 새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
일반 ChatGPT 대화 — 양식 .hwpx를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.
ChatGPT에서 그대로 따라 하기 — ChatGPT 채팅의 파이썬 환경은 PyPI 접근이
막혀 있으므로 최신 Release에서
python_hwpx-*.whl 하나를 받아 문서와 함께 올리고 이렇게 부탁합니다:
첨부한 python_hwpx-*.whl 을 pip 로 설치한 다음(pip install /mnt/data/python_hwpx-*.whl),
이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다. 자세한 절차와 에이전트용 지시문은 AI 채팅 환경에서 쓰기에, AI 도구가 정확한 API를 배우도록 llms.txt도 제공합니다.
| 저장소 | 역할 | |
|---|---|---|
| 📦 | python-hwpx |
HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
| 🔌 | python-hwpx-automation |
저작·양식 채움 워크플로, hwpx CLI, 선택형 MCP 서버 |
| 🎯 | hwpx-plugins |
에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
pip install python-hwpx # Python 3.10+from hwpx import HwpxDocument
doc = HwpxDocument.new()
doc.add_heading("2026 운영계획", level=1)
doc.add_paragraph("가. 추진 배경", style="개요 2")
doc.save_to_path("계획.hwpx")스타일은 이름으로 지정하고, 오타는 저장이 아니라 그 줄에서 잡힌다.
기존 문서를 고치려면 HwpxDocument.open("보고서.hwpx")로 시작하면 된다.
문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
python-hwpx-automation을
함께 설치하세요.
기존 설치 명령 호환을 위해
pip install "python-hwpx[visual]"도 계속 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 — 그 역할은python-hwpx-automation[oracle]이 맡습니다.
- 읽기·추출 — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
- 편집 — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
- 양식 채우기 — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
- 생성·일괄 처리 — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
- 검증·안전 — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(
MutationReport)
자세한 내용: 5분 퀵스타트 · 사용 가이드 · API 레퍼런스 · 예제
doc = HwpxDocument.open("신청서.hwpx")
values = {
"성명 > right": "홍길동",
"소속 > right": "플랫폼팀",
}
result = doc.tables.fill_by_path(values)
if result["failed_count"] or result["applied_count"] != len(values):
raise ValueError(result["failed"])
report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback="error", return_report=True)중복·누락 라벨은 실패로 확인하고 저장을 중단합니다. patch는 미수정 ZIP 파트의 바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이 필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 안전한 쓰기 계약을 따르세요.
report = doc.save_to_path("결과.hwpx", return_report=True)
print(report.actual_mode) # "patch" 또는 "rebuild" — 실제 저장 등급
print(report.preservation.untouched_part_payloads.to_dict())
# {"verified": 17, "changed": 0}mode="patch", fallback="error"는 보존 등급 미달 시 출력하지 않습니다.
기본 auto는 달성 가능한 등급을 선택합니다. report.ok는 요청 반영이나 시각
검증 완료를 뜻하지 않습니다.
전체 규칙: 안전한 쓰기 계약.
예제 중 독립 실행 예제 표시가 없는 블록은 여러분의 기존 문서를 입력으로 쓰는 조각입니다. 예제별 Python 블록 판정은 실행 ledger에 동결돼 있습니다.
만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다 스택과 날짜를 병기합니다:
- 한컴 열림 120/120 · 렌더 검증 120/120 — 현행 스택(5.7.0 · 실한컴
12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
있어
jq한 줄로 재현됩니다 - 한컴 열림 476/476 — 전수 동결 코퍼스(N=497) 측정 (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
- 미수정 영역 바이트 보존 497/497 · 개인정보 유출 0
- 렌더 검증 416/476 — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
- 전체 수치와 주의사항: 실측 코퍼스 메트릭 · 기능별 등급: 지원 매트릭스
ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.
현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
| 환경 | 무엇을 하면 되나 |
|---|---|
| 일반 ChatGPT 대화 | .hwpx와 Release wheel을 함께 올리고 오프라인 설치 후 편집해 되받기 — 안내 |
| 로컬·서버 파이썬 | pip install python-hwpx — 스크립트·배치·CI |
| 파이썬 자동화 (MCP 없이) | pip install python-hwpx-automation — 저작·양식 채움·검증 워크플로를 그냥 파이썬으로 |
| ChatGPT MCP 앱 | python-hwpx-automation의 MCP adapter를 커넥터로 등록 |
| Codex 마켓플레이스 플러그인 | hwpx-plugins 설치 |
| Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 (python-hwpx-automation) |
ChatGPT 채팅의 파이썬 환경은 현재 PyPI 접근이 막혀 있습니다. 매 릴리스의
GitHub Release에 첨부되는 py3-none-any wheel을 문서와 함께 올리면 오프라인
설치로 같은 여정이 됩니다. wheel의 유일한 의존성은 lxml이며, 실행 환경에
없으면 lxml wheel도 함께 올립니다. 같은 wheel을 GitHub Actions artifact
python-hwpx-wheel로도 유지하므로, artifact를 가져올 수 있는 에이전트는 첨부
없이 설치할 수 있습니다(실험 경로, 안내). 파이썬 실행
가능 여부와 업로드 경로는 플랜·설정에 따라 다릅니다.
| python-hwpx | pyhwpx | pyhwp | |
|---|---|---|---|
| 대상 포맷 | .hwpx (OWPML/OPC) |
.hwpx |
.hwp (v5 바이너리) |
| 한/글 설치 | 불필요 | 필요 (Windows COM) | 불필요 |
| 크로스 플랫폼 | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
| 편집/생성 API | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
| AI 에이전트 연동 (MCP) | ✅ companion 경유 | ❌ | ❌ |
HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
add_shape()/add_control()은 저수준 탈출구라, 그대로 저장하면 한/글이 열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은add_line()/add_rectangle()/add_ellipse()를 쓰세요.- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
- 암호화된 HWPX는 지원하지 않습니다.
help wanted · 로드맵 · Discussions · CONTRIBUTING
HWPX 내부 구조가 처음이라면 내부 실전 가이드부터 — 실제 한/글 동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다. 공개 API의 안정 범위는 안정 API 표면, 계층 간 소유권은 제품 경계 문서에 있습니다.
아래 공개 표준·프로젝트에 빚지고 있습니다.
- OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101) — HWPX가 기반하는 한국 산업 표준
- hancom-io/hwpx-owpml-model — OWPML 요소 구조 참조 모델 · neolord0/hwpxlib — 오라클 샘플 코퍼스
- edwardkim/rhwp — 멱등성·검증 게이트 설계 영감
- 범정부오피스 — 공무 문서 편집 워크플로 아이디어
Apache-2.0 (LICENSE · NOTICE) — Kohkyuhyun @airmang · kokyuhyun@hotmail.com