목록으로 돌아가기

HWPX 표 파싱 예제 — hp:tbl, hp:tr, hp:tc, cellSpan을 파이썬으로 읽기

기술 분석2026-11-16· 읽기 시간 6분

HWPX 파일에서 표를 꺼내려면 Contents/section0.xml 안의 hp:tbl 요소를 읽으면 됩니다. 이 글은 표 하나가 XML로 어떻게 생겼는지 보여주고, 병합 셀까지 처리하는 파이썬 코드를 처음부터 끝까지 싣습니다. 외부 패키지는 필요 없습니다.

표 하나의 XML 구조

아래는 3행 3열 표의 구조를 줄인 예시입니다. 실제 파일에는 크기, 여백, 테두리 속성이 더 붙지만 내용을 읽는 데 필요한 뼈대는 이것이 전부입니다.

<hp:tbl rowCnt="3" colCnt="3"> <hp:tr> <hp:tc> <hp:subList> <hp:p><hp:run><hp:t>구분</hp:t></hp:run></hp:p> </hp:subList> <hp:cellAddr colAddr="0" rowAddr="0"/> <hp:cellSpan colSpan="1" rowSpan="2"/> </hp:tc> <hp:tc> <hp:subList> <hp:p><hp:run><hp:t>금액</hp:t></hp:run></hp:p> </hp:subList> <hp:cellAddr colAddr="1" rowAddr="0"/> <hp:cellSpan colSpan="2" rowSpan="1"/> </hp:tc> </hp:tr> <!-- 이하 행 생략 --> </hp:tbl>

읽을 때 알아야 할 것은 네 가지입니다.

요소역할
hp:tbl표 전체. rowCnt, colCnt에 행·열 수가 있습니다.
hp:tr행 하나.
hp:tc셀 하나. 글자는 hp:subList 아래 문단(hp:p)에 들어 있습니다.
hp:cellAddr, hp:cellSpan셀의 위치(colAddr, rowAddr)와 병합 크기(colSpan, rowSpan). hp:tc의 자식 요소입니다.

자주 틀리는 지점 세 가지

병합 정보는 속성이 아니라 자식 요소에 있습니다. HTML의 <td colspan="2">에 익숙하면 hp:tc의 속성에서 colSpan을 찾게 됩니다. HWPX에서는 hp:tc 아래의 hp:cellSpan 요소를 읽어야 합니다.

병합된 셀은 XML에 한 번만 나옵니다. 2행을 합친 셀은 첫 행에만 hp:tc가 있고 둘째 행에는 아예 없습니다. 행마다 hp:tc를 순서대로 세면 열이 밀립니다. hp:cellAddr의 좌표를 기준으로 배치해야 안전합니다.

표는 문단 안에 들어 있습니다. hp:tbl은 본문 최상위가 아니라 hp:p → hp:run 아래에 놓입니다. 그리고 셀 안에도 hp:p가 있습니다. 문서의 모든 hp:t를 한 번에 긁으면 본문과 표 내용이 뒤섞이고, 표 내용이 두 번 나오기도 합니다.

전체 예제 코드

import zipfile import xml.etree.ElementTree as ET HP = "http://www.hancom.co.kr/hwpml/2011/paragraph" NS = {"hp": HP} def cell_text(tc): """셀 안의 모든 hp:t 텍스트를 이어 붙인다.""" return " ".join(t.text for t in tc.iter(f"{{{HP}}}t") if t.text).strip() def table_to_grid(tbl): """hp:tbl 하나를 병합이 풀린 2차원 리스트로 바꾼다.""" cells = {} for tr in tbl.findall("hp:tr", NS): for tc in tr.findall("hp:tc", NS): addr = tc.find("hp:cellAddr", NS) span = tc.find("hp:cellSpan", NS) row, col = int(addr.get("rowAddr")), int(addr.get("colAddr")) row_span = int(span.get("rowSpan", "1")) if span is not None else 1 col_span = int(span.get("colSpan", "1")) if span is not None else 1 text = cell_text(tc) for r in range(row, row + row_span): for c in range(col, col + col_span): cells[(r, c)] = text n_rows = max(r for r, _ in cells) + 1 n_cols = max(c for _, c in cells) + 1 return [[cells.get((r, c), "") for c in range(n_cols)] for r in range(n_rows)] def grid_to_markdown(grid): lines = ["| " + " | ".join(grid[0]) + " |", "| " + " | ".join("---" for _ in grid[0]) + " |"] lines += ["| " + " | ".join(row) + " |" for row in grid[1:]] return "\n".join(lines) def extract_tables(hwpx_path): tables = [] with zipfile.ZipFile(hwpx_path) as zf: sections = sorted(n for n in zf.namelist() if n.startswith("Contents/section") and n.endswith(".xml")) for name in sections: root = ET.fromstring(zf.read(name)) for tbl in root.iter(f"{{{HP}}}tbl"): tables.append(table_to_grid(tbl)) return tables if __name__ == "__main__": for grid in extract_tables("sample.hwpx"): print(grid_to_markdown(grid)) print()

위 구조의 표를 넣으면 다음과 같이 나옵니다.

| 구분 | 금액 | 금액 | | --- | --- | --- | | 구분 | 현행 | 개정 | | 중소기업 | 5억 | 10억 |

마크다운 표에는 병합 문법이 없습니다. 그래서 이 코드는 병합된 칸마다 같은 값을 채웁니다. LLM에 넣을 때는 이 방식이 유리합니다. 어느 행을 잘라 읽어도 "구분"과 "금액"이 무엇인지 알 수 있기 때문입니다.

이 코드가 다루지 않는 것

실제 공문서를 넣어 보면 다음 경우에서 손이 더 갑니다.

  • 표 안의 표. root.iter()는 안쪽 표도 따로 찾아내고, 바깥 셀의 텍스트에도 안쪽 표 내용이 섞여 들어갑니다.
  • 셀 안의 줄바꿈과 여러 문단. 위 코드는 공백으로 이어 붙입니다.
  • 레이아웃용 표. 공문서는 제목 상자나 결재란을 표로 그립니다. 이런 표를 데이터 표로 변환하면 결과가 지저분해집니다.
  • 본문과 표의 순서. 표만 뽑으면 "어느 조항 아래의 표인지"가 사라집니다.
  • 구형 .hwp 파일. HWPX가 아닌 바이너리 형식은 구조가 전혀 다릅니다.

몇 건만 처리한다면 위 코드를 고쳐 쓰는 것으로 충분합니다. 문서 종류가 다양하거나 양이 많다면 HWP 마크다운 변환에서 파일을 올려 결과를 바로 확인해 보세요. 대량 처리나 API 연동은 도입 문의로 연락 주시면 됩니다.

병합 표 파싱 및 대량 문서 자동화가 필요하신가요?

MDChange의 B2B·API 연동 및 온프레미스 구축으로 공공·기업 HWP/HWPX 문서의 RAG 전처리를 자동화하세요.

API·B2B 도입 문의하기 HWP 마크다운 변환