Hwpx Writer

한글 문서 작성자 (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.new()
# 단락 추가, 표 삽입, 서식 적용 (상세는 scripts/create_hwpx.py 참조)
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 파일은 한컴오피스에서 최적으로 열립니다. 한컴오피스가 설치되지 않은 환경에서는 moai-office: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 헤더가 올바른지 검증하세요 |

관련 스킬 / 자체 검수

한글 문서 생성이 끝나면 산출된 .hwpx 파일을 다시 열어 플레이스홀더 잔존·OWPML 구조·한글 인코딩 깨짐·표 깨짐을 자체 검수하고, 문제가 있으면 자동 수정 후 재생성하며 최종 PASS/FAIL 결과를 보고합니다.

• 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 프로그래밍 가이드