hwp-converter-ai 0.2.0

Python으로 HWP/HWPX 파일 생성·파싱·변환. HWP 문서를 Markdown으로, Markdown을 HWP/HWPX로.

HWP Converter AI

Python으로 HWP/HWPX 파일을 생성·파싱·변환합니다.

웹에서 바로 체험하기: https://www.hwpsome.com

설치

pip install hwp-converter-ai

빠른 시작

Markdown → HWP (한글 97~2024)

from hwp_converter_ai import HwpWriter

HwpWriter().from_markdown("# 업무 보고\n\n내용입니다.", "report.hwp")

Markdown → HWPX (한글 2014+)

from hwp_converter_ai import HwpxGenerator

HwpxGenerator().from_markdown("# 제목\n\n**볼드** 텍스트", output_path="report.hwpx")

HWP → Markdown

from hwp_converter_ai import HwpParser

ir = HwpParser.parse("document.hwp")
print(ir.to_markdown())

HWPX → Markdown

from hwp_converter_ai import HwpxParser

ir = HwpxParser().parse("document.hwpx")
print(ir.to_markdown())

지원 기능

Markdown 변환

기능	HWP	HWPX
텍스트/문단	✅	✅
제목 (H1~H3)	✅	✅
볼드/이탤릭	✅	✅
밑줄/취소선 (파싱 방향)	✅	✅
표 (테두리 포함)	✅	✅
표 병합 셀 (세로/가로 병합 구조 보존)	✅	✅
수식 (한컴 수식 스크립트 ↔ LaTeX)	✅	✅
이미지 추출	✅	✅
리스트/글머리표 감지	✅	✅
다단(N단) 레이아웃 생성	✅	✅
긴 문서	✅	✅

IR(JSON)로 보존되는 서식

Markdown이 표현하지 못하는 서식은 중간 표현 DocumentIR에 보존됩니다. IR을 직접 사용하면 뷰어 렌더링·HWP 재생성 시 아래 서식이 유지됩니다.

• 문단 정렬(왼쪽·가운데·오른쪽·배분), 문단 여백·줄간격
• 글자 자간·장평, 글꼴 크기·색상
• 용지 크기·여백 (PAGE_DEF)
• 표 열 너비, 셀 배경색, 셀 테두리 스타일
• 머리말·꼬리말·쪽 번호
• 기본 도형(GSO — 직선·사각형 등)과 도형 내 텍스트
• 하이퍼링크

v0.2.0 변경사항

• 표 병합 셀: 세로/가로 병합(rowspan·colspan) 구조 보존 — 병합 라벨이 Markdown 표의 올바른 행에 연결
• 수식: 한컴 수식 스크립트 ↔ LaTeX 변환 모듈 추가 (eq_to_latex / latex_to_eq), HWPX hp:equation 개체 생성
• 머리말·꼬리말·쪽 번호: HWP/HWPX 파싱 지원
• 밑줄·취소선: 파싱 지원 (Markdown 출력 시 보존)
• 글머리표(bullet) 문단: HWP 바이너리 파싱 지원
• 다단(N단) 레이아웃: Markdown → HWP 생성 시 단 수 지정(columns), 단 나누기 처리
• 문단 여백·테두리(BORDER_FILL)·셀 스타일 등 파싱 충실도 전반 개선
• 실적: 이 변환 코어로 법령·행정규칙·공문서 등 실문서 3,700여 건을 변환해 RAG 검색 서비스에 운영 중
• v0.2.0 회귀 검증: 공공기관 결재 문서 30건 + 공문서 서식 9종 파싱, MD→HWP/HWPX→MD 왕복 테스트 통과

예제

볼드/이탤릭 포함 문서

from hwp_converter_ai import HwpWriter

md = """# 업무 보고서

일반 텍스트 **볼드 강조** 그리고 *이탤릭 참고*.

| 항목 | 상태 |
|------|------|
| 변환 | 완료 |
| 교정 | 진행중 |
"""

HwpWriter().from_markdown(md, "report.hwp")

HWP 파싱 후 텍스트 추출

from hwp_converter_ai import HwpParser

ir = HwpParser.parse("input.hwp")

# Markdown으로
print(ir.to_markdown())

# 순수 텍스트로 (검색/인덱싱용)
print(ir.to_plain_text())

IR(중간 표현) 직접 조작

from hwp_converter_ai import HwpWriter, DocumentIR, BlockNode, InlineNode, BlockType, InlineType

ir = DocumentIR(title="보고서")
ir.blocks.append(BlockNode(
    type=BlockType.HEADING, level=1,
    children=[InlineNode(type=InlineType.TEXT, text="제목")]
))
ir.blocks.append(BlockNode(
    type=BlockType.PARAGRAPH,
    children=[
        InlineNode(type=InlineType.TEXT, text="일반 "),
        InlineNode(type=InlineType.BOLD, text="강조"),
    ]
))

HwpWriter().from_ir(ir, "custom.hwp")

요구사항

• Python 3.10+
• olefile (자동 설치)
• 이미지 리사이즈가 필요하면: pip install hwp-converter-ai[images] (Pillow)

웹 서비스

코드 없이 브라우저에서 바로 변환해 보려면:

https://www.hwpsome.com

스펙 기반

한컴 공식 HWP 5.0 문서 파일 구조 및 OWPML(KS X 6101) 표준을 기반으로 구현되었습니다.

본 제품은 한글과컴퓨터의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.

라이선스

MIT License