HWPX section0.xml 구조 예제 — hp:p, hp:run, hp:t, hp:tbl 파싱 코드와 함정
기존 HWP(5.0) 파일이 바이너리(OLE/CFB) 구조였다면, HWPX는 국가 표준(KS X 6101) OWPML(Open Word-Processor Markup Language) 기반의 ZIP 압축 XML 포맷입니다. 확장자를 .zip으로 바꾸어 압축을 해제하면 누구나 내부 XML 트리를 열어볼 수 있습니다.
하지만 막상 Python 등으로 HWPX 파서를 직접 구현해 보면 hp:p, hp:run, hp:t, hp:tbl 태그의 중첩 구조와 병합 셀 좌표 계산 때문에 텍스트 순서가 뒤섞이거나 표가 망가지는 문제를 마주하게 됩니다. 이 글에서는 실제 HWPX 패키지 구조와 Contents/section0.xml 샘플, Python 표준 라이브러리 파싱 예제 및 대표적인 함정을 단계별로 살펴봅니다.
1. HWPX ZIP 내부 파일 구조 (mimetype, header.xml, section0.xml)
HWPX 압축 파일을 열면 다음과 같은 표준 디렉터리 구조가 나타납니다.
sample.hwpx (ZIP 컨테이너) ├── mimetype # 'application/hwp+zip' 식별 문자열 (비압축 저장) ├── version.xml # OWPML 포맷 및 생성 애플리케이션 버전 ├── META-INF/ │ ├── container.xml # 패키지 루트 파일(content.hpf) 위치 지정 │ └── manifest.xml └── Contents/ ├── content.hpf # 패키지 내 XML 및 첨부 파일(BinData) 목록 ├── header.xml # 문서 전역 스타일(charPr, paraPr, style, borderFill) 정의 └── section0.xml # 1구역 본문(문단, 표, 그림 등). 구역이 나뉘면 section1.xml 추가
① mimetype 파일의 역할
ZIP 아카이브의 첫 번째 엔트리로 저장되는 20바이트 안팎의 일반 텍스트 파일이며, 내부에는 정확히 application/hwp+zip 문자열이 들어 있습니다. 파서나 백엔드 검증 로직에서는 확장자만 보지 않고 이 mimetype 엔트리를 읽어 정상적인 HWPX(OWPML) 문서인지 1차 판별할 수 있습니다.
② Contents/header.xml 스타일 참조 구조
section0.xml에는 "이 문단은 제목1이고 글자 크기는 16pt이며 굵게 표시한다"라는 스타일 상세 값이 직접 들어 있지 않습니다. 대신 header.xml 내부에 번호표(id) 형태로 정의된 **글자 모양(hh:charPr), 문단 모양(hh:paraPr), 스타일 목록(hh:style), 테두리/배경(hh:borderFill)**을 본문 태그의 속성(charPrIDRef, paraPrIDRef, styleIDRef)으로 참조합니다. 따라서 제목(Heading) 위계를 정확히 구분하려면 header.xml의 스타일 매핑을 함께 조회해야 합니다.
2. 실제 Contents/section0.xml 구조 샘플 코드
본문 텍스트와 병합 표는 Contents/section0.xml에 아래의 네임스페이스 및 계층 구조로 기록됩니다.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <hs:sec xmlns:hs="http://www.hancom.co.kr/hwpml/2011/section" xmlns:hp="http://www.hancom.co.kr/hwpml/2011/paragraph" xmlns:hc="http://www.hancom.co.kr/hwpml/2011/core"> <!-- 1) 일반 문단: hp:p -> hp:run -> hp:t 계층 --> <hp:p id="101" paraPrIDRef="3" styleIDRef="1"> <hp:run charPrIDRef="5"> <hp:t>1. 사업 개요 및 추진 목적</hp:t> </hp:run> </hp:p> <!-- 2) 표(hp:tbl)는 독립 루트 요소가 아니라 문단(hp:p) 안의 hp:run 내부에 중첩됨 --> <hp:p id="102" paraPrIDRef="0" styleIDRef="0"> <hp:run charPrIDRef="0"> <hp:tbl id="2001" rowCnt="2" colCnt="2"> <hp:tr> <hp:tc borderFillIDRef="3"> <!-- 병합 정보는 hp:tc 속성이 아니라 자식 태그 hp:cellSpan에 위치 --> <hp:cellSpan colSpan="2" rowSpan="1"/> <hp:cellAddr colAddr="0" rowAddr="0"/> <hp:subList> <hp:p id="103" paraPrIDRef="0" styleIDRef="0"> <hp:run charPrIDRef="5"> <hp:t>구분 및 세부 평가 기준 (2열 가로 병합 헤더)</hp:t> </hp:run> </hp:p> </hp:subList> </hp:tc> </hp:tr> <hp:tr> <hp:tc borderFillIDRef="3"> <hp:cellSpan colSpan="1" rowSpan="1"/> <hp:cellAddr colAddr="0" rowAddr="1"/> <hp:subList> <hp:p id="104"><hp:run><hp:t>기술성 평가</hp:t></hp:run></hp:p> </hp:subList> </hp:tc> <hp:tc borderFillIDRef="3"> <hp:cellSpan colSpan="1" rowSpan="1"/> <hp:cellAddr colAddr="1" rowAddr="1"/> <hp:subList> <hp:p id="105"><hp:run><hp:t>80점</hp:t></hp:run></hp:p> </hp:subList> </hp:tc> </hp:tr> </hp:tbl> <hp:t/> </hp:run> </hp:p> </hs:sec>
위 샘플에서 반드시 눈여겨봐야 할 구조는 두 가지입니다.
<hp:tbl>은 섹션의 최상위 자식이 아니라 반드시 어떤 문단(<hp:p>)과 런(<hp:run>)의 자식으로 들어간다는 점입니다.- 표의 각 셀(
<hp:tc>) 안에는 다시<hp:subList>와<hp:p>가 재귀적으로 중첩됩니다.
3. Python 표준 라이브러리(zipfile + ElementTree) 파싱 예제
별도 외부 패키지 없이 Python 기본 내장 모듈인 zipfile과 xml.etree.ElementTree만으로 mimetype 검증부터 section0.xml의 문단과 표 셀 병합 정보를 읽는 기본 구조는 다음과 같습니다.
import zipfile import xml.etree.ElementTree as ET HP_NS = "http://www.hancom.co.kr/hwpml/2011/paragraph" HS_NS = "http://www.hancom.co.kr/hwpml/2011/section" NS = {"hp": HP_NS, "hs": HS_NS} def tag(name: str) -> str: return f"{{{HP_NS}}}{name}" def extract_paragraph_text(p_elem: ET.Element) -> str: """표(hp:tbl) 내부 텍스트를 제외한 순수 문단 텍스트만 추출""" parts = [] for run in p_elem.findall("./hp:run", NS): for child in run: if child.tag == tag("t") and child.text: parts.append(child.text) elif child.tag == tag("lineBreak"): parts.append("\n") return "".join(parts).strip() def parse_hwpx_basic(hwpx_path: str): with zipfile.ZipFile(hwpx_path, "r") as zf: # 1. mimetype 검사 if "mimetype" in zf.namelist(): mime = zf.read("mimetype").decode("utf-8").strip() if mime != "application/hwp+zip": raise ValueError(f"유효하지 않은 HWPX mimetype: {mime}") # 2. 구역 파일 순회 (section0.xml, section1.xml ...) sections = sorted( f for f in zf.namelist() if f.startswith("Contents/section") and f.endswith(".xml") ) for sec_file in sections: root = ET.fromstring(zf.read(sec_file)) # 구역 최상위 hp:p만 순회해야 표 안쪽의 hp:p를 중복 추출하지 않음 for p_elem in root.findall("./hp:p", NS): text = extract_paragraph_text(p_elem) if text: print("[문단]", text) # 문단 내 run에 포함된 표(hp:tbl) 처리 for tbl in p_elem.findall("./hp:run/hp:tbl", NS): print("[표 시작]") for r_idx, tr in enumerate(tbl.findall("./hp:tr", NS)): row_cells = [] for tc in tr.findall("./hp:tc", NS): span = tc.find("./hp:cellSpan", NS) col_span = int(span.attrib.get("colSpan", "1")) if span is not None else 1 row_span = int(span.attrib.get("rowSpan", "1")) if span is not None else 1 # 셀 내부 문단들 결합 cell_texts = [ "".join(t.text for t in cell_p.findall(".//hp:t", NS) if t.text) for cell_p in tc.findall(".//hp:p", NS) ] cell_val = " ".join(t.strip() for t in cell_texts if t.strip()) row_cells.append(f"{cell_val} (c:{col_span}, r:{row_span})") print(f" Row {r_idx}:", row_cells)
4. 실무 개발 시 마주치는 HWPX 파싱 함정 4가지
예제 코드처럼 단순 순회만으로는 공공기관 문서나 조달청 입찰 공고문에서 바로 오류를 겪게 됩니다. 실제 파서 엔진에서 반드시 방어해야 하는 함정들입니다.
① root.findall('.//hp:p') 전체 검색으로 인한 텍스트 중복·순서 꼬임
ElementTree나 lxml에서 경로 전체 검색(.//hp:p)을 사용하면 표(hp:tbl) 안쪽의 셀 문단까지 바깥쪽 문단으로 한 번 더 추출됩니다. 결과적으로 본문에 표 텍스트가 나열된 뒤 표 안에서 또 중복 출력되는 현상이 발생합니다. 반드시 루트 직계 문단인지, 혹은 조상 노드에 hp:tbl이 존재하는지 판별해 분리해야 합니다.
② 세로 병합(rowSpan > 1) 발생 시 다음 행의 열 좌표(colAddr) 밀림
2행 이상 세로로 병합된 셀이 있는 경우, 다음 행(<hp:tr>)의 XML에는 병합으로 덮인 셀의 <hp:tc> 자체가 존재하지 않습니다. 단순히 <hp:tr> 순서대로 파이프(|)를 붙여 마크다운 표를 만들면 오른쪽 열의 수치가 왼쪽 열로 한 칸씩 밀려 치명적인 데이터 왜곡이 발생합니다. 2차원 그리드 행렬을 구성하고 cellAddr 또는 점유 추적 배열로 빈 슬롯을 채워 넣어야 정확한 열 정렬을 유지할 수 있습니다.
③ 글자·문단 중첩 및 표 안의 표(Nested Table)
공공기관 공고문이나 과업지시서는 표 셀(hp:tc) 내부에 또 다른 하위 표(hp:tbl)가 들어가는 중첩 표 구조가 매우 흔합니다. 마크다운 파이프 테이블(| ... |)은 문법상 다중 중첩 표를 직접 지원하지 않으므로, 레이아웃 목적의 외부 프레임 표인지 데이터 표인지 구분하거나 내부 텍스트 평탄화 정책을 적용해야 합니다.
④ 레이아웃용 1칸 표(박스 테두리)의 일반 인용구 처리
한글 문서 작성 시 안내 문구나 유의사항 박스를 그리기 위해 1행 1열짜리 표를 사용하는 경우가 많습니다. 이를 무조건 마크다운 표로 변환하면 AI가 데이터 테이블로 오해할 수 있으므로, 1열 표나 폼 서식은 인용구(>) 또는 문단으로 구조화하는 판별 로직이 필요합니다.
5. 복잡한 병합 표와 예외 처리를 직접 구현하지 않고 바로 변환하려면?
header.xml 스타일 위계 매핑, 다중 rowSpan/colSpan 2차원 그리드 복원, 표 안의 표 예외 처리와 레거시 .hwp 바이너리(OLE)까지 직접 파싱하고 유지보수하는 작업은 LLM·RAG 프로젝트 본연의 개발 일정보다 훨씬 큰 비용을 요구합니다.
MDChange는 실전 공공기관 고시문·제안요청서(RFP)·법규 문서에서 검증된 전용 HWP·HWPX 구조화 파싱 엔진을 제공합니다.
- 웹에서 샘플 문서를 바로 테스트해 보시려면 👉 HWP 마크다운 변환기
- 사내 RAG 파이프라인 REST API 연동 또는 기관·기업 온프레미스(망분리) 구축이 필요하시다면 👉 API·엔터프라이즈 도입 문의