<양식 1>

<양식 2>

<양식 3>

<양식 4>

Team Jakal

jakal-hwpx 기반 HWPX 문서 자동화 연구

Team Jakal

This report investigates jakal-hwpx, a Python library for opening, editing, validating, and saving ZIP-based HWPX documents. The study reviews the HWPX/OWPML standard background, the public API surface of jakal-hwpx, template-preserving editing strategies, table and image automation, validation workflows, and operational risks. A template HWPX form was edited only through the jakal-hwpx Python API and saved with validation enabled.

Key Words : jakal-hwpx, HWPX, OWPML, Python, 문서 자동화, 검증 저장

Ⅰ. 서론

한국의 교육기관, 공공기관, 연구기관에서 HWPX 문서는 여전히 실무 양식의 핵심 형식이다. 보고서와 공문은 제목, 초록, 다단 본문, 표, 그림, 인용문헌처럼 고정 서식을 요구하므로 단순 텍스트 생성만으로는 충분하지 않다. 자동화가 실제 업무에 들어가려면 양식의 쪽 설정과 문단 모양을 보존하면서 내용만 교체해야 한다.

HWPX는 국가표준 KS X 6101의 OWPML에 기반한 개방형 문서 포맷이며, 기존 HWP의 바이너리 중심 구조와 달리 ZIP 패키지 안에 XML 파일과 바이너리 데이터를 배치한다[1][2]. 이 구조는 문서 내용, 서식, 이미지의 위치가 명시적으로 분리된다는 장점을 갖지만, 직접 XML을 수정하면 참조 무결성과 한/글 호환성이 쉽게 흔들릴 수 있다.

본 보고서의 목적은 jakal-hwpx를 단순한 텍스트 치환 도구가 아니라 HWPX 양식 자동화를 위한 객체 기반 편집 계층으로 평가하는 것이다. 특히 기존 양식을 유지한 채 문단, 표, 그림, 메타데이터를 수정하고 save(validate=True)로 저장하는 절차가 어느 정도 실무적인 안정성을 제공하는지 검토하였다.

Ⅱ. 연구 방법

2.1 조사 대상과 자료 수집 기준

본 연구는 공식 문서와 공개 저장소를 우선 자료로 삼았다. HWPX 포맷의 기초 구조는 한컴테크의 HWPX 포맷 구조 설명, e-나라 표준인증의 KS X 6101 표준 정보, 한컴의 머신리더블 포맷 안내를 기준으로 정리하였다[1][2][3].

jakal-hwpx의 기능 범위는 PyPI의 패키지 설명과 GitHub 저장소 README를 대조하였다. PyPI 안정 버전 0.2.0은 HWPX 열기, 수정, 검증, 저장에 초점을 둔다. GitHub main 문서에는 실험적인 HWP 브리지와 더 넓은 API가 설명되어 있어, 본문에서는 안정 버전과 개발 문서의 차이를 분리해 해석하였다[4][5].

2.1.1 공신력 기준

포맷 설명은 제품 공급사 문서만으로 끝내지 않고 국가표준 페이지와 교차 확인하였다. e-나라 표준인증은 KS X 6101의 표준명, 제정일, 최종 개정 확인일, 적용 범위를 제시한다. 이 자료는 HWPX가 단순한 사유 확장자가 아니라 개방형 워드프로세서 문서 구조의 구현체라는 사실을 확인하는 기준점이 된다[2].

라이브러리 설명은 패키지 배포 페이지와 소스 저장소를 병행했다. PyPI는 설치 명령, 요구 Python 버전, 안정 릴리스, 주요 API를 확인하는 데 유리하고, GitHub는 소스 구조, 지원 범위, 테스트 절차, 향후 실험 기능을 확인하는 데 유리하다[4][5].

인용문헌과 공개 저장소를 기준으로 볼 때, HWPX 자동화의 핵심은 “문서를 문자열 파일로 보는 것”이 아니라 “문단·표·그림·참조를 가진 패키지 객체로 보는 것”이다.

이 관점에서는 XML을 직접 열어 바꾸는 단기 편의보다, 라이브러리의 공개 API를 통해 문서 객체와 컨트롤 참조를 보존하는 절차가 더 중요하다.

따라서 본 문서 생성 실험도 HWPX 압축 내부를 직접 편집하지 않고, HwpxDocument.open(), set_paragraph_text(), insert_paragraph(), Table.set_cell_text(), Picture.bind_binary_item(), save(validate=True) 같은 jakal-hwpx 공개 API만 사용하였다.

2.1.2 편집 실험 설계

실험 대상은 사용자가 제공한 졸업논문 연구 양식 HWPX 파일이다. 기존 양식은 B5 용지, 다단 본문, 그림 캡션, 표 캡션, 인용문헌 영역을 포함하고 있어 템플릿 보존형 자동화의 시험 사례로 적합하다.

편집 절차는 네 단계로 구성하였다. 첫째, 원본 HWPX를 열어 검증 오류가 없는지 확인하였다. 둘째, 제목·초록·본문 문단을 양식의 기존 문단 모양 위에 교체하였다. 셋째, 표 셀과 그림 바이너리를 객체 API로 갱신하였다. 넷째, 최종 파일을 save(validate=True)로 저장하고 다시 열어 검증하였다.

2.2 평가 프레임워크

평가 항목은 자동화 업무에서 실제로 실패가 발생하는 지점에 맞추었다. 구체적으로 포맷 호환성, 양식 보존, 표 편집, 그림 삽입, 검증 저장, 실행 환경, 버전 성숙도, 운영 리스크를 검토하였다.

그림은 한컴테크가 공개한 HWPX와 HWP 구조도를 사용하였다. 해당 이미지는 포맷의 차이를 시각적으로 설명하는 데 직접적인 가치가 있으므로, 본 양식의 기존 그림 자리에는 인터넷에서 수집한 구조도를 삽입하였다[1].

Figure 1. HWPX 패키지 구조도. 출처: 한컴테크[1].

Figure 1은 HWPX가 mimetype, version.xml, settings.xml, Contents, BinData, META-INF, Preview, Scripts 등으로 나뉘는 패키지임을 보여준다. jakal-hwpx가 문서 전체를 하나의 바이너리 덩어리로 취급하지 않고, 문단·표·그림 같은 요소를 객체로 노출할 수 있는 배경이 바로 이 패키지 구조다.

2.3 재현 가능한 편집 파이프라인

재현 가능한 문서 자동화는 세부 명령보다 단계 분리가 중요하다. 첫 단계는 원본 양식을 보존하는 것이다. 양식 파일을 기준점으로 삼고, 신규 문서를 빈 문서에서 만들지 않으면 쪽 설정, 다단, 표 테두리, 캡션 위치, 글자 모양을 다시 설계할 필요가 줄어든다.

둘째 단계는 문단 인덱스와 템플릿 문단을 분리해 다루는 것이다. get_document_text()는 검색과 미리보기에는 유용하지만 편집 대상 문단 인덱스와 반드시 1:1로 대응하지 않는다고 문서가 주의한다[4]. 따라서 실제 편집에서는 양식의 문단 위치를 확인하고, 안전한 텍스트 문단만 치환해야 한다.

셋째 단계는 컨트롤이 들어 있는 문단을 일반 문단처럼 덮어쓰지 않는 것이다. 그림, 표, 헤더, 다단 설정이 들어 있는 문단을 set_paragraph_text()로 덮으면 컨트롤이 삭제될 수 있다. 본 실험에서는 그림은 Picture API, 표는 Table API, 다단 제어문이 있는 문단은 replace_text()를 사용해 제어문을 보존하였다.

넷째 단계는 저장 전후 검증이다. validation_errors()와 reference_validation_errors()는 구조적 오류를 조기에 발견하는 데 쓰이고, save(validate=True)는 저장 시 검증을 강제한다. 자동화 결과물을 대량으로 만들 때 이 검증 단계를 생략하면 오류가 누적된 파일을 배포할 위험이 커진다.

2.4 분석 범위와 한계

본 연구는 HWPX 양식 편집을 중심으로 한다. 즉, 문서가 이미 HWPX로 존재하고, 그 안의 문단과 표와 그림을 교체하는 상황을 전제로 한다. 오래된 HWP 바이너리 문서를 완전히 동일한 HWPX로 변환하거나, 모든 한/글 컨트롤을 무에서 생성하는 문제는 별도 연구 과제이다.

또한 인터넷 자료의 해석은 공식 문서와 공개 저장소를 기준으로 제한하였다. 오픈소스 저장소의 main 브랜치 설명은 릴리스 버전보다 앞선 기능을 포함할 수 있으므로, 실무 적용 시에는 pip로 설치되는 버전의 API와 문서를 우선 확인해야 한다.

마지막으로 페이지 수는 한/글 렌더링 엔진, 로컬 글꼴 대체, 이미지 표시 방식에 따라 달라질 수 있다. 본 문서는 B5·다단 양식 기준으로 약 10쪽 분량이 되도록 본문과 표와 그림을 확장하였지만, 최종 제출 전에는 한/글에서 실제 쪽수를 확인하는 절차가 필요하다.

Ⅲ. 연구 결과

HWPX의 구조적 개방성은 문서 자동화에서 뚜렷한 장점을 만든다. 한컴테크 설명에 따르면 HWPX는 XML 파일들이 ZIP 구조로 구성되어 있으며, 주요 파일이 XML이기 때문에 데이터 추출이 용이하다[1]. 하지만 “추출이 쉽다”는 사실이 곧 “아무 방식으로 수정해도 안전하다”는 뜻은 아니다.

표준 문서는 문서 구조, 호환성 평가, 메타데이터 확장과 같은 범위를 다루며, HWPX 문서의 각 부품은 서로 참조 관계를 갖는다[2]. 따라서 표면적으로는 텍스트 파일 편집처럼 보여도, 실무 자동화에서는 참조 ID와 컨트롤 보존 여부를 검증할 수 있는 편집 계층이 필요하다.

Table 1. HWPX와 jakal-hwpx 조사 요약.

항목	관찰 내용	보고서 해석
포맷 구조	HWPX는 ZIP 패키지와 XML 구성요소, BinData 바이너리로 구성된다.	텍스트·표·이미지의 기계적 접근성이 높다.
핵심 객체
검증 흐름	validation_errors(), reference_validation_errors(), save(validate=True)	자동 생성 문서의 손상 여부를 저장 전후에 확인한다.
적용 범위	기존 HWPX 열기, 본문 수정, 표 셀 수정, 그림 바이너리 교체	반복 보고서·공문·연구 양식 자동화에 적합하다.
주의점	HWP와 완전 동일한 왕복 변환을 목표로 하지 않는다고 명시되어 있다.	포맷 변환기가 아니라 HWPX 중심 편집기로 보는 것이 정확하다.

Table 1은 조사 결과를 HWPX 구조, jakal-hwpx API, 검증 흐름, 적용 범위, 주의점으로 요약한다. 핵심은 이 라이브러리를 만능 변환기가 아니라 기존 HWPX 양식을 안전하게 읽고 갱신하는 편집기로 보는 것이다.

3.2 jakal-hwpx의 문서 객체 모델

jakal-hwpx에서 대부분의 작업은 HwpxDocument에서 시작한다. 문서를 여는 open(), 새 문서를 만드는 blank(), 메타데이터를 읽고 쓰는 metadata()와 set_metadata(), 문서 텍스트를 가져오는 get_document_text(), 특정 문단을 교체하는 set_paragraph_text(), 문단을 추가하는 append_paragraph()가 기본 흐름을 이룬다[4].

표는 Table과 TableCell 객체로 접근한다. 이 방식의 장점은 셀 안의 문자열을 문서 전체 검색·치환과 분리하여 다룰 수 있다는 점이다. 예를 들어 연구 결과표의 각 셀을 API로 채우면 셀 병합, 테두리, 배경색 같은 기존 양식 속성을 유지할 가능성이 높아진다.

그림은 Picture 객체로 접근한다. 본 실험에서는 기존 그림 개체를 새로 만들지 않고, 인터넷에서 수집한 구조도 이미지를 BinData에 추가한 뒤 그림 개체를 새 바이너리 항목에 바인딩했다. 이 전략은 위치와 크기와 캡션 틀을 보존하면서 이미지만 바꾸기 때문에 신규 삽입보다 안전하다.

SectionSettings는 페이지 크기와 여백을 제어할 수 있지만, 본 문서에서는 사용자가 제공한 양식을 깨뜨리지 않기 위해 쪽 설정을 변경하지 않았다. 양식 자동화에서는 “할 수 있는 편집”과 “해야 하는 편집”을 구분해야 하며, 쪽 설정은 특별한 요구가 없으면 보존하는 편이 낫다.

HeaderFooterBlock, Bookmark, Field, Note, Equation 같은 객체가 공개 API에 포함된다는 점도 중요하다[5]. 이는 향후 공문서 자동화에서 머리말, 꼬리말, 계산 필드, 상호 참조를 다룰 수 있는 확장 가능성을 뜻한다. 다만 모든 컨트롤을 동일한 안정도로 다룰 수 있다고 단정해서는 안 된다.

3.3 검증 저장의 의미

문서 자동화에서 검증 저장은 단순한 옵션이 아니라 품질관리 장치이다. 사람이 한/글을 열어 편집할 때는 화면에서 즉시 깨짐을 발견할 수 있지만, 서버나 스크립트가 수백 개 파일을 생성할 때는 저장 직전 검증 없이는 손상된 산출물이 뒤늦게 발견된다.

jakal-hwpx 문서는 validate=True가 제어문 보존 검사까지 포함한다고 설명한다[4][5]. 이는 특히 양식 문서에 중요하다. 표나 그림 같은 컨트롤은 본문 텍스트와 달리 문서 내부 참조를 갖기 때문에, 텍스트 덮어쓰기 과정에서 컨트롤이 사라지면 파일은 열리더라도 제출 양식으로서 가치를 잃을 수 있다.

본 실험에서 원본 템플릿은 validation_errors() 기준 오류가 없었다. 편집 후에도 save(validate=True)를 통과하도록 문단 치환과 객체 치환을 분리하였다. 이 결과는 jakal-hwpx의 검증 저장 기능이 양식 보존형 워크플로에서 실용적인 방어선으로 작동할 수 있음을 보여준다.

검증이 모든 호환성 문제를 해결하는 것은 아니다. 한/글 렌더링 엔진에서 줄바꿈과 이미지 클리핑이 다르게 보일 수 있고, 특정 버전의 한/글에서만 발생하는 표시 문제가 있을 수 있다. 따라서 검증 저장은 “필수 조건”이지 “충분 조건”은 아니다.

3.4 표 자동화 결과

본 보고서의 Table 1과 Table 2는 기존 양식에 들어 있던 표 개체를 유지하고, 셀 내용만 Table.set_cell_text()로 갱신하였다. 이 방식은 표를 새로 그리는 것보다 훨씬 안전하다. 셀 너비, 테두리, 배경, 캡션 위치 같은 서식이 이미 양식에 있기 때문이다.

Table 1은 요약형 표로, 라이브러리의 주요 기능과 해석을 세 열로 정리했다. Table 2는 비교형 표로, jakal-hwpx와 COM 자동화, Java/Rust 계열 파서의 차이를 업무 기준으로 비교했다. 표 본문은 절대적인 성능 순위가 아니라 선택 기준을 제공한다.

표 자동화에서 주의할 점은 템플릿 행에 북마크나 필드 같은 보존 컨트롤이 들어 있을 때다. jakal-hwpx 문서는 append_row()가 보존 컨트롤이 있는 템플릿 행에서 빠르게 실패하도록 설계되었다고 설명한다[5]. 이는 조용히 깨진 파일을 만드는 것보다 낫다.

실무에서는 표 행을 무조건 추가하기보다 충분한 행을 가진 표를 양식에 미리 배치하고, 필요한 범위만 채우는 방식이 안정적이다. 행 수가 가변적이라면 별도의 fixture 문서를 만들어 행 추가 동작을 회귀검사해야 한다.

3.5 그림 자동화 결과

그림 자동화는 텍스트 자동화보다 까다롭다. 그림은 BinData의 바이너리 파일, manifest 항목, 본문 그림 객체의 참조가 함께 맞아야 한다. 본 실험에서는 한컴테크 공식 글의 HWPX 구조도와 HWP 구조도를 다운로드한 뒤, 기존 그림 객체에 새 바이너리 항목을 연결하였다[1].

이 방식은 템플릿의 그림 위치, 캡션 간격, 다단 배치를 유지하면서 실제 이미지 내용만 바꾼다. 다만 원본 그림 객체에 클리핑이 설정되어 있으면 새 이미지도 그 클리핑의 영향을 받는다. 따라서 이미지의 내용이 클리핑 영역 안에 오도록 사전 처리하는 과정이 필요하다.

본 보고서의 그림은 원본 양식의 크롭 영역을 고려해 1200×792 크기의 BMP 캔버스 안에 공식 구조도를 배치한 후 삽입하였다. 이는 XML을 직접 수정하지 않고도 기존 그림 개체의 시각적 틀을 보존하기 위한 절충이다.

실무에서 그림이 자주 바뀌는 문서라면 그림 자리마다 명확한 이름과 같은 비율의 placeholder를 두는 것이 좋다. 그래야 자동화 코드가 어느 그림을 어떤 이미지로 교체해야 하는지 안정적으로 판단할 수 있다.

3.6 버전 성숙도와 공급망 고려

PyPI 페이지는 jakal-hwpx 0.2.0을 2026년 4월 9일 릴리스된 안정 버전으로 표시하고, Python 3.11 이상을 요구한다고 제시한다[4]. 같은 페이지의 릴리스 이력에는 0.3.0b 계열 사전 릴리스도 보인다. 버전 선택은 자동화 안정성에 직접 영향을 준다.

공개 저장소 README는 Python 3.11, 3.12, 3.13 지원과 ZIP 기반 HWPX 패키지의 열기, 수정, 검증, 컴파일, 저장을 지원 범위로 제시한다[5]. main 브랜치 문서는 사전 릴리스 기능을 반영할 수 있으므로, 운영 코드는 버전을 고정하고 해당 버전의 API만 사용해야 한다.

PyPI 패키지는 편리하지만 공급망 리스크가 없는 것은 아니다. 자동화 서버에서는 requirements 파일에 버전을 고정하고, 가능하면 해시 검증과 내부 패키지 미러를 사용해야 한다. 문서 자동화는 공문·개인정보·연구자료를 다룰 수 있으므로 일반 스크립트보다 배포 통제가 중요하다.

본 실험은 설치된 jakal-hwpx와 lxml을 사용하되, 문서 내부 XML을 직접 수정하지 않았다. 이는 사용자 요구 조건을 만족하기 위한 선택인 동시에, 라이브러리 공개 API를 벗어난 편집이 향후 버전에서 깨질 가능성을 줄이는 선택이다.

3.7 다른 자동화 접근과의 비교

pyhwpx나 pywin32 기반 한/글 COM 자동화는 실제 한/글 프로그램을 제어하기 때문에 화면에서 가능한 작업을 비교적 충실히 재현할 수 있다. 그러나 Windows, 한/글 설치, 보안 모듈, 프로세스 상태에 의존한다. 서버 환경과 리눅스 컨테이너에서는 운영 부담이 크다.

Java 기반 hwpxlib나 Rust 기반 HWPX 라이브러리는 파싱과 변환, 대량 추출에서 장점을 가질 수 있다. 다만 본 보고서의 요구처럼 기존 HWPX 양식 위에 내용을 채우고 검증 저장하는 업무에서는 Python으로 바로 호출 가능한 객체 편집 API가 더 간단하다.

결국 도구 선택은 “무엇을 자동화하는가”에 따라 달라진다. 한/글 UI의 모든 기능을 재현해야 한다면 COM 자동화가 유리하다. 대량 텍스트 추출이 목적이면 전용 파서가 유리할 수 있다. 양식 기반 HWPX 생성과 갱신이 목적이면 jakal-hwpx가 적절한 균형점을 제공한다.

Table 2는 이 판단을 정리한 의사결정 표이다. 한 가지 도구를 모든 상황에 적용하기보다, 원본 문서 형식, 실행 환경, 검증 요구, 서식 보존 수준을 기준으로 선택해야 한다.

3.8 양식 보존 관점의 평가

본 양식은 제목, 저자, 영문 초록, 키워드, 장 제목, 절 제목, 소절 제목, 인용문, 표, 그림, 인용문헌을 모두 포함한다. 이 요소들이 하나의 파일 안에서 함께 유지되어야 졸업논문 연구 양식으로서 기능한다.

jakal-hwpx의 template_index 기반 문단 삽입은 기존 문단 모양을 복제하는 데 유용했다. 새 본문 문단은 본문 예시 문단을 템플릿으로 삼아 삽입했고, 절 제목은 절 제목 예시 문단을 템플릿으로 삼았다. 이 방식은 글자 크기와 장평, 들여쓰기 같은 서식을 다시 계산하지 않아도 된다.

단, 컨트롤이 들어 있는 문단을 템플릿으로 삼거나 덮어쓰는 것은 피해야 한다. 그림 문단, 표 문단, 다단 설정 문단은 보존 대상이지 일반 텍스트 문단이 아니다. 본 실험에서는 이 문단들에 대해 객체 API 또는 텍스트 치환 API를 선별 사용하였다.

양식 보존의 최종 판단은 파일이 저장되는지뿐 아니라 한/글에서 열었을 때 문단 흐름, 그림 위치, 표 크기, 인용문헌 영역이 자연스러운지까지 포함한다. 따라서 본 보고서와 같은 자동 생성 문서는 제출 전 시각 검수를 병행해야 한다.

3.9 운영 적용 시나리오

첫 번째 시나리오는 교육기관의 연구 보고서 자동 생성이다. 학생별 실험 데이터, 표, 그림, 참고문헌 목록이 다르지만 양식이 동일하다면, 하나의 HWPX 템플릿을 기준으로 수십 개 보고서를 자동 생성할 수 있다.

두 번째 시나리오는 공공기관의 반복 공문 또는 결과보고서 작성이다. 공문 양식은 머리말, 결재란, 표준 문구가 엄격하게 정해져 있으므로, 빈 문서 생성보다 기존 양식 치환이 적합하다. jakal-hwpx는 HWPX 양식을 직접 열어 수정하는 방식이므로 이 요구와 잘 맞는다.

세 번째 시나리오는 AI 생성 텍스트의 HWPX 배포이다. 대형언어모델은 보통 Markdown이나 평문을 생성하지만, 한국 실무에서는 HWPX 제출물이 요구되는 경우가 많다. 이때 Markdown을 바로 HWPX로 완전 변환하기보다, 승인된 HWPX 템플릿에 AI가 생성한 본문을 배치하는 전략이 더 통제 가능하다.

네 번째 시나리오는 검색·요약·검토용 문서 전처리이다. get_document_text()와 구조화 요소 접근을 이용하면 HWPX 문서에서 텍스트를 추출하고, 필요한 부분만 갱신한 뒤 다시 저장할 수 있다. 다만 평탄화 텍스트가 편집 인덱스와 1:1 대응하지 않는다는 주의는 항상 적용된다[4].

3.10 실패 모드와 대응책

가장 흔한 실패는 컨트롤 삭제이다. 표나 그림이 있는 문단을 일반 텍스트로 덮어쓰면 컨트롤이 사라진다. 대응책은 컨트롤 문단을 직접 덮어쓰지 않고, Table·Picture 같은 전용 객체 API를 사용하는 것이다.

두 번째 실패는 문서 버전 차이다. GitHub main 문서에 보이는 기능이 pip 안정 버전에는 없을 수 있고, 반대로 최신 사전 릴리스 기능은 아직 운영 안정성이 충분히 검증되지 않았을 수 있다. 대응책은 버전 고정, 최소 기능 사용, 문서별 회귀검사다.

세 번째 실패는 이미지 비율과 클리핑 문제다. 기존 그림 자리의 크기와 클립 설정이 새 이미지에 맞지 않으면 이미지가 잘려 보일 수 있다. 대응책은 원본 placeholder의 비율을 표준화하거나, 이미지 전처리로 내용이 보이는 영역에 들어오도록 맞추는 것이다.

네 번째 실패는 글꼴 대체와 쪽수 변동이다. 양식은 HY신명조를 기준으로 하지만 실행 환경에 해당 글꼴이 없으면 렌더링이 달라질 수 있다. 대응책은 최종 제출 환경에서 열어 보고, 필요할 경우 한/글에서 글꼴 포함 또는 표준 글꼴 정책을 확정하는 것이다.

Ⅳ. 분석 및 논의

jakal-hwpx의 장점은 문서 자동화를 “파일을 열어 문자열을 바꾸는 스크립트”에서 “문서 객체를 조작하고 검증하는 파이프라인”으로 끌어올린다는 점이다. PyPI 문서에 제시된 주요 API는 HwpxDocument.open(), blank(), metadata(), set_paragraph_text(), append_paragraph(), replace_text(), section_settings(), tables(), pictures(), validation_errors(), save(path) 등이다[4].

특히 save(validate=True)의 기본 검증은 제어문 보존 검사까지 포함하며, 실패 시 섹션 경로와 누락된 제어문 종류를 예외 메시지에 포함한다는 설명이 공개 문서에 제시되어 있다[4][5]. 이 기능은 양식 문서에서 표, 그림, 필드, 북마크 같은 컨트롤을 실수로 제거하는 위험을 줄이는 데 중요하다.

반면 한계도 명확하다. PyPI 안정 문서는 legacy HWP 입력과 HWP→HWPX 변환기 번들을 지원 범위 밖으로 둔다[4]. GitHub main 문서는 실험적인 HWP 브리지 기능을 설명하지만, 동시에 Hancom과 동일 fidelity의 완전 변환기를 목표로 하지 않는다고 밝힌다[5]. 운영 환경에서는 이 버전 차이를 혼동하지 말아야 한다.

따라서 jakal-hwpx의 가장 적절한 사용 방식은 “이미 승인된 HWPX 양식을 기준 파일로 두고, 반복되는 본문과 표 데이터와 그림만 API로 교체한 뒤 검증 저장하는 방식”이다. 본 보고서 자체도 이 전략을 따랐다.

table 2. HWPX 자동화 도구 선택 기준.

평가 항목	jakal-hwpx	pyhwpx/COM 자동화	Java/Rust 계열 파서	판단
실행 환경	한/글 설치 없이 HWPX 패키지 직접 처리	Windows와 한/글 COM 환경 의존	도구별로 JVM 또는 별도 런타임 필요 가능	서버·CI 자동화는 jakal-hwpx가 단순하다.
편집 단위	문단, 표 셀, 그림 바이너리, 메타데이터	한/글 UI 명령과 저수준 액션 중심	대체로 추출·변환 또는 자체 문서 모델 중심	양식 보존 편집에는 객체 API가 중요하다.
검증	validate=True 저장과 검증 오류 목록 제공	한/글 프로그램의 열기/저장 성공 여부에 의존	프로젝트마다 검증 방식 상이	검증 API 존재가 운영 안정성을 높인다.
서식 보존	기존 HWPX를 열어 템플릿 문단을 복제하는 방식에 강점	한/글 자체 엔진 사용으로 높은 호환성 기대	생성 품질은 구현 완성도에 좌우	고난도 레이아웃은 실문서 회귀검사가 필요하다.
이미지 처리	Picture 객체의 바이너리 교체와 바인딩 가능	UI 삽입 명령으로 처리 가능	라이브러리별 지원 수준 차이	반복 삽입보다 템플릿 그림 교체가 안전하다.
주요 리스크	버전 성숙도, 복잡한 컨트롤 처리, 문서별 예외	GUI/보안 모듈/프로세스 상태	의존성·배포·호환성	문서 유형별 fixture가 필요하다.
적합 업무
권고	HWPX 원본 양식 유지 + API 편집 + 검증 저장	최종 호환성 검사는 한/글에서 샘플 열람	추출 전용 파이프라인과 분리	자동화 품질은 검증 체계가 결정한다.

Figure 2. 기존 HWP 구조와 HWPX 구조 비교. 출처: 한컴테크[1].

표와 그림이 포함된 HWPX 자동화에서는 큰 객체를 1단 영역에 배치하고 설명 본문을 2단으로 되돌리는 전략이 가독성에 유리하다. 이 양식의 다단 설정은 유지하되, 문단 내용만 교체하여 구조를 보존하였다.

Figure 2는 기존 HWP와 HWPX가 문서 구성요소를 다루는 방식에서 차이를 갖는다는 점을 보완적으로 보여준다. HWP는 레코드와 스트림 분석에 대한 이해가 필요하고, HWPX는 패키지 내부 구성요소가 파일 단위로 분리되어 있어 자동화 라이브러리가 객체 모델을 만들기 쉽다.

Ⅴ. 결론

본 연구는 jakal-hwpx가 HWPX 양식 자동화에서 실용적인 선택지가 될 수 있음을 확인하였다. 핵심 이유는 세 가지다. 첫째, HWPX의 ZIP+XML 패키지 구조를 문서 객체로 감싸기 때문에 문단, 표, 그림, 메타데이터를 각각 다룰 수 있다.

둘째, 기존 양식을 기준으로 열고 수정하는 방식이므로 B5 용지, 다단, 문단 모양, 표와 그림의 위치를 다시 설계할 필요가 적다. 본 보고서의 생성 과정에서도 원본 양식을 유지하고, 안전한 텍스트 문단과 표 셀과 그림 바이너리만 갱신하였다.

셋째, save(validate=True)를 통한 검증 저장이 자동화 품질관리에 유용하다. 자동 문서 생성은 성공 메시지보다 실패를 빨리 감지하는 기능이 중요하다. 검증이 없으면 깨진 문서가 대량으로 생성되어 뒤늦게 발견될 수 있다.

그러나 jakal-hwpx를 HWP/HWPX 전환의 만능 해결책으로 보는 것은 부정확하다. 안정 버전 문서는 legacy HWP 입력과 HWP→HWPX 변환기 제공을 지원 범위 밖으로 둔다[4]. GitHub main의 실험 기능도 완전 fidelity 변환을 목표로 하지 않는다고 밝힌다[5].

따라서 가장 현실적인 운영 전략은 HWPX 템플릿을 표준화하고, 반복 변경이 필요한 영역만 명시적으로 객체화한 뒤, 버전을 고정한 jakal-hwpx 스크립트로 채우고, 결과물을 검증 저장 및 샘플 시각 검수하는 것이다.

5.1 운영 권고안

첫째, 템플릿 문서를 먼저 설계해야 한다. 자동화 코드는 좋은 양식을 대체하지 못한다. 그림 자리, 표 행 수, 제목 문단, 참고문헌 문단을 미리 확보하면 자동화 코드는 안정적으로 내용만 채울 수 있다.

둘째, 컨트롤 문단과 일반 문단을 분리한 편집 규칙을 문서화해야 한다. 일반 본문은 set_paragraph_text()와 insert_paragraph()를 사용하고, 표는 Table API, 그림은 Picture API, 메타데이터는 set_metadata()를 사용하는 식으로 규칙을 고정한다.

셋째, 저장은 항상 save(validate=True)로 수행해야 한다. 검증 저장을 생략하는 것은 자동화 파이프라인에서 가장 쉽게 발생하는 품질 저하 요인이다. 특히 교육·공공 문서처럼 제출 파일 자체가 결과물인 업무에서는 검증 로그를 남기는 것이 좋다.

넷째, 패키지 버전을 고정하고 문서 fixture를 유지해야 한다. 자동화 스크립트가 성공했다는 사실은 특정 양식과 특정 버전의 조합에서만 의미가 있다. 양식이 바뀌거나 패키지 버전이 바뀌면 최소한 열기, 저장, 주요 문단 확인, 표·그림 확인 테스트를 다시 수행해야 한다.

다섯째, 최종 산출물은 한/글에서 열어 확인해야 한다. jakal-hwpx의 검증은 구조적 안정성을 높여 주지만, 인간 독자가 보는 레이아웃 품질은 별도 검수 대상이다. 자동화의 목표는 사람의 검토를 없애는 것이 아니라 반복 편집 시간을 줄이고 오류 가능성을 낮추는 것이다.

종합하면 jakal-hwpx는 한국어 HWPX 문서 자동화에서 “양식 보존형 편집기”라는 분명한 위치를 갖는다. XML을 직접 수정하지 않고 Python API로 템플릿을 채우고 검증 저장할 수 있다는 점에서, 연구 보고서와 공문 양식 자동화에 실질적 가치가 있다.

인 용 문 헌

김규리. 한/글 문서 파일 형식 : HWPX 포맷 구조 살펴보기, 한컴테크, 2025, https://tech.hancom.com/hwpxformat/

e-나라 표준인증. KS X 6101 개방형 워드프로세서 마크업 언어(OWPML) 문서 구조, 2024, https://standard.go.kr/

한글과컴퓨터. HWP 문서가 PDF 대비 머신 리더블에 취약한가요?, 한컴 지원 FAQ, https://www.hancom.com/support/faqCenter/faq/detail/3131

한컴그룹. 아래아한글 기본문서형식 개방형으로 변환, 한컴그룹 보도자료, https://www.hancomgroup.com/posts/3/174

Python Package Index. jakal-hwpx 0.2.0, PyPI, 2026, https://pypi.org/project/jakal-hwpx/

Ahnd6474. jakal-hwpx: Round-trip safe HWPX reader/editor/writer for Python, GitHub, 2026, https://github.com/Ahnd6474/jakal-hwpx

Hancom Tech. HWPX and HWP format structure images, 2025, https://tech.hancom.com/hwpxformat/

작성자: Team Jakal 주소: 대구광역시, 전화: 000-0000-0000, 이메일: jakalflow@gmail.com

논문접수일: 2026년 4월 22일