한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리
한국어 | English
한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고 파이썬이 도는 ChatGPT 채팅 안에서도 그대로 동작합니다. 기존 문서는 손댄 곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는 형태로 만들어집니다.
일반 ChatGPT 대화 — 양식 .hwpx를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.
ChatGPT에서 그대로 따라 하기 — 문서를 올리면서 이렇게 부탁하면 됩니다:
이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
(pip install python-hwpx 로 설치하면 돼)
양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
| 저장소 | 역할 | |
|---|---|---|
| 📦 | python-hwpx |
HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
| 🔌 | python-hwpx-automation |
저작·양식 채움 워크플로, hwpx CLI, 선택형 MCP 서버 |
| 🎯 | hwpx-plugins |
에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
pip install python-hwpx # Python 3.10+from hwpx import HwpxDocument
doc = HwpxDocument.open("보고서.hwpx")
doc.add_paragraph("자동화로 추가한 문단입니다.")
doc.save_to_path("보고서-수정.hwpx")백지에서 시작할 때는 HwpxDocument.new()로 만들어 같은 API로 문단·표·머리말을
채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
python-hwpx-automation을
함께 설치하세요.
기존 설치 명령 호환을 위해
pip install "python-hwpx[visual]"도 계속 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 — 그 역할은python-hwpx-automation[oracle]이 맡습니다.
- 읽기·추출 — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
- 편집 — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
- 양식 채우기 — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
- 생성·일괄 처리 — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
- 검증·안전 — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(
MutationReport)
자세한 내용: 사용 가이드 · 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). 전체 규칙: 안전한 쓰기 계약.
예제 중 독립 실행 예제 표시가 없는 블록은 여러분의 기존 문서를 입력으로 쓰는 조각입니다. 예제별 Python 블록 판정은 실행 ledger에 동결돼 있습니다.
만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서 그대로 공개합니다:
- 한컴 열림 476/476 — 우리가 만든 파일을 실한컴이 전부 엽니다
- 미수정 영역 바이트 보존 497/497 · 개인정보 유출 0
- 렌더 검증 416/476 — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
- 전체 수치와 주의사항: 실측 코퍼스 메트릭 · 기능별 등급: 지원 매트릭스
ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.
현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
| 환경 | 무엇을 하면 되나 |
|---|---|
| 일반 ChatGPT 대화 | .hwpx를 올리고 pip install python-hwpx 후 파이썬으로 편집해 되받기 |
| 로컬·서버 파이썬 | 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 대화에 .hwpx를 올리고 설치를 부탁했을 때 PyPI 설치와
편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
오프라인 설치로 같은 여정이 됩니다.
| 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 · [email protected]