한글 문서 작성자 (HWPX Writer)
개요
Python python-hwpx 라이브러리를 기반으로 HWPX 형식의 문서를 생성합니다. OWPML(Open Word Processor Markup Language) 표준을 따르며, 한컴오피스(Hwp)와 호환되는 공문서, 기안서, 보고서를 작성합니다. 기존 HWP 파일을 HWPX로 변환하거나 텍스트를 추출할 수 있습니다.
트리거 키워드
한글, hwpx, 아래한글, 한컴, 공문서, 기안서, HWP 변환, 한글 문서 생성, HWPX 편집
워크플로우
1단계: 문서 요구사항 분석
사용자 요청 분석 후 작업 유형 결정:
- 신규 HWPX 생성: 공문서, 기안서, 보고서, 회의록
- HWP → HWPX 변환: 구버전 한글 파일 최신 포맷 변환
- 텍스트 추출: 기존 HWPX에서 내용 추출
- 양식 채우기: 템플릿 레이아웃 보존 후 내용만 수정
2단계: 의존성 확인
# 필수 라이브러리 설치
pip install python-hwpx lxml
# 선택 사항 (HWP 바이너리 처리)
pip install olefile
3단계: python-hwpx로 문서 생성
from hwpx import HwpxDocument
hwp = HwpxDocument()
# 단락 추가, 표 삽입, 서식 적용
hwp.save("output.hwpx")
4단계: OWPML 구조 검증
생성된 HWPX 파일이 OWPML 스펙을 준수하는지 검증하고, 한컴오피스에서 정상 열리는지 확인합니다.
사용 예시
- "공문서 양식으로 협조 요청 한글 파일을 만들어줘"
- "기존 HWP 파일을 HWPX로 변환해줘"
- "아래한글 기안서 형식으로 품의서를 작성해줘"
- "HWPX 파일에서 텍스트를 추출해줘"
- "한글 문서 내용이 올바른 OWPML 구조인지 검증해줘"
출력 형식
- 파일 형식:
.hwpx(한컴오피스 2010+ 표준) - 표준: OWPML 1.5 (Open Word Processor Markup Language)
- 압축: ZIP 기반 (XML + 리소스 파일)
- 한글 호환: 한컴오피스 2014, 2018, 2020에서 정상 열림
주의사항
안정 기능 vs 제한 기능
| 기능 | 상태 | 비고 |
|---|---|---|
| 단락 추가 | 안정 | 기본 기능 |
| 볼드/이탤릭/밑줄 | 안정 | lxml 패치 자동 적용 |
| 테이블 | 안정 | 행/열 제한 없음 |
| 머리글/바닥글 | 안정 | - |
| 각주/미주 | 안정 | - |
| 북마크 | 안정 | - |
| 텍스트 치환 | 안정 | - |
| 도형 (선/사각/타원) | 제한 | 한글에서 오류 경고 발생 가능 |
| 이미지 삽입 | 제한 | 불완전한 pic 요소 생성 |
| 다단 설정 | 제한 | 한글에서 오류 경고 발생 가능 |
한컴오피스 환경
HWPX 파일은 한컴오피스에서 최적으로 열립니다. 한컴오피스가 설치되지 않은 환경에서는 docx-generator 스킬 사용을 권장합니다.
폰트 호환성
한컴 전용 폰트(HY헤드라인, HY견고딕 등)는 한컴오피스 설치 환경에서만 정상 표시됩니다. 배포 시 폰트 내장 또는 PDF 변환을 권장합니다.
HWP 변환 제한
HWP 파일 버전(2010/2014/2018 등)에 따라 변환 제한이 있을 수 있습니다. 구버전 HWP는 텍스트 추출만 가능할 수 있습니다.
문제 해결
| 상황 | 해결 방법 |
|---|---|
| 파일 생성 실패 | python-hwpx 및 lxml 설치 여부 확인: pip install python-hwpx lxml. 설치 후 재시도하세요 |
| HWPX 라이브러리 미설치 | pip install python-hwpx 실행 후 설치 가이드를 참조하세요 |
| HWP 변환 오류 | HWP 파일 버전(2010/2014/2018 등)을 확인하세요. 구버전은 변환 제한이 있을 수 있습니다 |
| OWPML 구조 오류 | validate.py 스크립트로 검증 후 오류 내용을 공유해 주시면 수정을 도와드립니다 |
| 폰트 깨짐 | 한컴 전용 폰트(HY헤드라인, HY견고딕 등)는 한컴오피스 설치 환경에서만 정상 표시됩니다 |
| 한글에서 열리지 않음 | OWPML 네임스페이스를 확인하고 xml 헤더가 올바른지 검증하세요 |
관련 스킬
moai-office:docx-generator- DOCX(Word) 문서 생성moai-office:pptx-designer- 발표용 PPT 슬라이드 생성moai-office:xlsx-creator- 엑셀 데이터 시트 생성
기술 참조
- python-hwpx GitHub: https://github.com/airmang/python-hwpx
- OWPML 스펙: 한글과컴퓨터 OWPML 1.5 명세서
- 한컴오피스 API: HwpObject 프로그래밍 가이드