DOCS/ideas/250916_HWP-PDF_변환_전략_분석.md

파이썬 기반 HWP-PDF 변환 방법론에 대한 전략적 분석

1. Executive Summary

본 보고서는 파이썬(Python) 환경에서 한글(HWP) 문서를 PDF로 변환하는 다양한 기술적 접근법을 심층적으로 분석하고, 각 방법론의 장단점과 비용 구조를 비교하여 최적의 솔루션 선택을 위한 전략적 가이드라인을 제공한다. 분석 결과, 높은 완성도를 보장하는 순수 파이썬 오픈소스 라이브러리는 현재 존재하지 않는다는 결론에 도달했다.

[현재 프로젝트 상태] skill-rag-file은 HWP 파일을 지원하지 않음 (app/core/config.py의 ALLOWED_EXTENSIONS에 .hwp 누락, TextExtractor에 HWP 처리 로직 없음, Dockerfile에 LibreOffice 미설치).

HWP 파일 변환의 핵심 과제는 한글과컴퓨터(Hancom Inc.)가 개발한 HWP 포맷의 독점적(proprietary) 특성에서 비롯된다. 공개된 명세가 없는 이 기술적 장벽은 외부 애플리케이션이나 서비스를 활용하는 간접적인 해결책을 강제한다. 따라서 개발자는 단순히 '라이브러리'를 찾는 것이 아니라, 주어진 요구사항에 가장 적합한 '기술적 가교'를 선택하는 문제에 직면하게 된다.

본 보고서는 실질적으로 구현 가능한 세 가지 핵심 전략을 제시하고 분석한다.

• COM 자동화 (COM Automation): pywin32 라이브러리를 사용하여 윈도우(Windows)에 설치된 한컴오피스를 프로그래밍 방식으로 제어한다. 원본과 동일한, 완벽한 품질의 변환을 보장한다.
• 클라우드 기반 REST API: 외부 전문 변환 서비스(예: CloudConvert)에 HWP 파일을 전송하여 PDF 결과물을 받는 방식이다. 플랫폼에 독립적이며 확장성이 뛰어나다.
• 명령줄 인터페이스(CLI) 래퍼: 파이썬 스크립트 내에서 리브레오피스(LibreOffice)와 같은 외부 커맨드라인 도구를 호출하여 변환을 수행한다. 무료이며 여러 운영체제에서 사용 가능하지만, 변환 품질의 일관성은 보장되지 않는다.

최종적으로, 각 전략은 특정 사용 사례에 맞춰 권장된다. 높은 보안이 요구되는 기업 환경에서는 COM 자동화가, 다양한 플랫폼을 지원해야 하는 웹 애플리케이션에는 클라우드 API가, 그리고 비용 제약이 있는 내부 프로젝트에는 CLI 래퍼 방식이 가장 적합한 솔루션으로 평가된다.

2. HWP 변환의 기술적 과제: 근본 원인 분석

파이썬 생태계에서 HWP를 PDF로 직접 변환하는 라이브러리를 찾기 어려운 이유는 파이썬 언어의 한계가 아닌, HWP 포맷 자체의 본질적인 특성에 기인한다.

2.1. 독점적 파일 포맷의 장벽

HWP는 한글과컴퓨터가 개발하고 소유한 독점적 파일 포맷이다. DOCX나 ODT와 같이 공개된 표준과 달리, HWP 파일의 내부 구조와 데이터 명세는 외부에 공개되어 있지 않다.¹ 이로 인해 제3자 개발자들이 HWP 파일의 내용을 정확하게 해석하고 시각적으로 재현(rendering)하는 파서(parser)를 만드는 것은 기술적으로 매우 어렵다.

2.2. 파이썬 생태계에 미치는 영향

이러한 독점적 특성은 파이썬 오픈소스 커뮤니티에서 HWP 지원 라이브러리가 발전하지 못하는 직접적인 원인이 되었다. 파이썬은 pypdf³, PyMuPDF⁴, pikepdf⁵ 등 PDF 문서를 생성하고 조작하는 강력한 라이브러리들을 다수 보유하고 있다. 하지만 이 라이브러리들은 이미 구조화된 PDF를 다루는 데 특화되어 있을 뿐, HWP 파일의 원시 데이터를 읽어 들여 해석하는 기능은 전무하다.

결과적으로, HWP를 PDF로 변환하려는 개발자는 HWP 포맷을 공식적으로 지원하는 외부 소프트웨어에 의존하는 우회적인 방법을 선택할 수밖에 없다.

• pywin32는 한컴오피스로의 '가교' 역할을 하고,⁶
• HTTP 요청은 클라우드 API 서버로의 '가교' 역할을 하며,¹
• subprocess 모듈은 리브레오피스라는 외부 프로그램으로의 '가교' 역할을 하는 것이 바로 그 증거이다.

즉, 문제는 PDF 생성이 아니라 HWP 해석에 있다.

2.3. 텍스트 추출과 완전한 변환의 차이

일부 라이브러리는 HWP 파일에서 텍스트를 '추출'하는 기능을 제공하지만, 이는 완전한 '변환'과는 명백히 다르다. 예를 들어, olefile 라이브러리는 HWP 파일이 사용하는 OLE(Object Linking and Embedding) 컨테이너 구조를 분석하여 PrvText(미리보기 텍스트)나 BodyText(본문 텍스트)와 같은 원시 텍스트 스트림을 읽어올 수 있다.⁷

그러나 이 방식은 글꼴, 서식, 이미지, 표, 차트 등 문서의 시각적 레이아웃 정보를 전혀 해석하지 못한다. 따라서 단순한 텍스트 마이닝이나 데이터 분석 목적을 넘어, 원본 문서의 시각적 형태를 그대로 보존해야 하는 PDF 변환 요구사항은 충족시킬 수 없다.

3. COM 자동화를 통한 고품질 변환 (Windows 환경)

Windows 환경에서 가장 안정적이고 높은 품질의 변환 결과를 얻을 수 있는 방법은 COM(Component Object Model) 자동화를 통해 로컬에 설치된 한컴오피스를 직접 제어하는 것이다.

3.1. 메커니즘 및 아키텍처

COM은 마이크로소프트 윈도우의 핵심 기술로, 서로 다른 애플리케이션 간의 상호 운용성을 지원하는 표준 인터페이스이다. 한컴오피스는 외부 프로그램이 자신을 제어할 수 있도록 COM 인터페이스를 제공한다. 파이썬의 pywin32 라이브러리(win32com으로도 알려짐)는 이 COM 인터페이스에 접근할 수 있는 다리 역할을 수행한다.⁶

변환 프로세스는 다음과 같은 순서로 진행된다.

1. 파이썬 스크립트가 win32.gencache.EnsureDispatch("HWPFrame.HwpObject") 코드를 통해 한컴오피스 애플리케이션 객체를 생성한다.⁶
2. 생성된 객체의 Open 메서드를 호출하여 대상 HWP 파일을 연다.
3. SaveAs 메서드를 호출하면서 두 번째 인자로 "PDF"를 지정하여 문서를 PDF 포맷으로 저장한다.⁶
4. 변환이 완료되면 Quit 메서드를 호출하여 한컴오피스 애플리케이션을 종료한다.

3.2. 구현 가이드

사전 요구사항:

• Windows 운영체제
• 한컴오피스 소프트웨어 설치 및 정품 라이선스
• pywin32 라이브러리 설치 (pip install pywin32)⁸

코드 예제:

import os
import win32com.client as win32

def convert_hwp_to_pdf_com(hwp_path, pdf_path):
    """
    COM 자동화를 사용하여 HWP 파일을 PDF로 변환합니다.
    :param hwp_path: 원본 HWP 파일의 전체 경로
    :param pdf_path: 저장할 PDF 파일의 전체 경로
    """
    hwp = None
    try:
        hwp = win32.gencache.EnsureDispatch("HWPFrame.HwpObject")
        hwp.RegisterModule("FilePathCheckDLL", "SecurityModule") # 보안 모듈 등록

        hwp.Open(hwp_path)
        
        # PDF 저장 설정 (필요시 사용)
        # 예: hwp.HAction.GetDefault("FileSaveAsPdf", hwp.HParameterSet.HFileOpenSave.HSet)
        # hwp.HParameterSet.HFileOpenSave.filename = pdf_path
        # hwp.HParameterSet.HFileOpenSave.Format = "PDF"
        # hwp.HAction.Execute("FileSaveAsPdf", hwp.HParameterSet.HFileOpenSave.HSet)
        
        hwp.SaveAs(pdf_path, "PDF")
        print(f"'{hwp_path}' -> '{pdf_path}' 변환 성공")
        
    except Exception as e:
        print(f"변환 중 오류 발생: {e}")
    finally:
        if hwp:
            hwp.Quit()

# 사용 예시
# hwp_file = "C:\path\to\document.hwp"
# pdf_file = "C:\path\to\document.pdf"
# convert_hwp_to_pdf_com(hwp_file, pdf_file)

중요 고려사항: 보안 승인 모듈 자동화 스크립트로 한컴오피스를 제어할 때, "한글을 이용하여 위 파일에 접근하려는 시도가 있습니다"와 같은 보안 경고 팝업이 발생할 수 있다.⁶ 완전한 자동화를 위해서는 이 팝업을 비활성화해야 한다. 이를 위해 한컴에서 제공하는 보안 승인 모듈을 다운로드하고 레지스트리에 등록하는 과정이 필요하다.⁹ 이는 무인 환경에서 스크립트가 중단 없이 실행되기 위한 필수적인 절차이다.

3.3. 장점 및 단점 분석

• 장점:

  • 최상의 변환 품질: HWP 문서를 만든 네이티브 애플리케이션이 직접 변환을 수행하므로, 모든 요소가 원본과 동일하게 보존된다.
  • 세부적인 제어 기능: PDF의 세부 속성을 프로그래밍 방식으로 제어할 수 있다.¹⁰
  • 높은 보안성: 모든 변환 과정이 로컬에서 이루어져 데이터 유출 위험이 없다.

• 단점:

  • 플랫폼 종속성: 오직 윈도우 운영체제에서만 작동한다.
  • 소프트웨어 의존성: 한컴오피스 전체 버전이 설치되어 있어야 한다.
  • 자원 소모 및 프로세스 관리: 상당한 시스템 자원을 소모하며, 견고한 예외 처리가 필요하다.

3.4. 비용 구조 분석

이 솔루션은 한컴오피스 소프트웨어 라이선스 구매 비용이 발생한다.

• 구독형 모델: '한컴독스' 기업용 플랜은 1인당 월 8,250원¹⁷ 또는 월 7.00 달러¹⁹ 수준이다.
• 영구 라이선스: '한컴오피스 2024 기업용'은 약 46만 원 ~ 51만 원.²⁰
• 볼륨 라이선스 (ALA): 다수 사용자 대상 연간 계약.²⁰

총 소유 비용(TCO)에는 윈도우 서버 라이선스 및 유지보수 비용도 포함되어야 한다.

4. 클라우드 기반 REST API를 이용한 플랫폼 독립적 변환

운영체제에 구애받지 않고 유연하게 HWP 변환 기능을 구현해야 할 경우, 외부 전문 서비스를 활용하는 클라우드 기반 REST API가 효과적인 대안이 될 수 있다.

4.1. 메커니즘 및 아키텍처

클라이언트(파이썬 스크립트)가 HTTP 요청으로 HWP 파일을 API 서버에 전송하면, 서버가 PDF로 변환하여 결과를 응답으로 돌려주는 방식이다.

4.2. 주요 서비스 제공업체 및 구현

• CloudConvert: HWP to PDF 변환을 지원하는 대표적인 서비스.¹ requests 라이브러리로 연동 가능하다.
• CoolUtils: 온라인 변환 서비스 및 데스크톱/서버용 소프트웨어 판매.²⁴
• 기타 서비스: Allinpdf,²⁶ FreeConvert²⁸ 등.

4.3. 장점 및 단점 분석

• 장점:

  • 크로스 플랫폼 호환성: 모든 OS에서 작동한다.
  • 로컬 의존성 없음: 별도 소프트웨어 설치가 불필요하다.
  • 높은 확장성: 인프라 관리가 필요 없다.

• 단점:

  • 데이터 프라이버시 및 보안: 민감 정보를 외부 서버에 업로드해야 한다.
  • 지속적인 운영 비용: 사용량 기반 또는 구독 모델로 비용이 계속 발생한다.
  • 네트워크 의존성 및 지연 시간: 인터넷 연결이 필수이며, 속도 저하가 발생할 수 있다.
  • 제한적인 제어: API가 제공하는 범위 내로 기능이 한정된다.

4.4. 비용 구조 분석

• CloudConvert: '변환 크레딧'이라는 과금 체계를 사용한다.¹
• CoolUtils: 주로 소프트웨어 라이선스 형태로 판매 (서버 라이선 $750).²⁵

클라우드 API 선택은 리스크 관리 및 규정 준수(compliance)에 대한 결정이기도 하다. 서비스 제공업체의 보안 정책, ISO 27001 인증¹, 데이터 처리 계약(DPA) 등을 검토하는 '신뢰 비용(Trust Tax)'이 발생할 수 있다.

5. 오픈소스 대안: CLI 도구 활용

비용을 최소화하면서 크로스 플랫폼을 지원해야 하는 경우, 파이썬에서 외부 명령줄 인터페이스(CLI) 도구를 호출하는 방식이 대안이 될 수 있다.

5.1. 메커니즘 및 아키텍처

파이썬의 subprocess 모듈을 사용하여 리브레오피스(LibreOffice)와 같은 외부 프로그램을 실행하고 파일 변환을 오케스트레이션한다.

5.2. 주요 도구: 리브레오피스 (LibreOffice)

리브레오피스는 HWP 파일 가져오기 기능을 일부 지원한다. 아래 명령어로 변환을 수행할 수 있다.

soffice --headless --convert-to pdf <입력파일.hwp> --outdir <출력경로>

--headless 플래그는 GUI 없이 백그라운드에서 작업을 수행하게 한다.³⁰

파이썬 코드 예제:

import subprocess
import os

def convert_hwp_to_pdf_libreoffice(hwp_path, output_dir):
    """
    LibreOffice CLI를 사용하여 HWP 파일을 PDF로 변환합니다.
    :param hwp_path: 원본 HWP 파일의 경로
    :param output_dir: PDF 파일을 저장할 디렉토리
    """
    if not os.path.exists(hwp_path):
        print(f"오류: 파일이 존재하지 않습니다 - {hwp_path}")
        return

    try:
        # OS별 soffice 경로
        # Windows: "C:\Program Files\LibreOffice\program\soffice.exe"
        # Linux: "libreoffice" or "soffice"
        # macOS: "/Applications/LibreOffice.app/Contents/MacOS/soffice"
        soffice_path = "soffice" # 시스템 PATH에 등록되어 있다고 가정
        
        command = [
            soffice_path,
            "--headless",
            "--convert-to", "pdf",
            hwp_path,
            "--outdir", output_dir
        ]
        
        result = subprocess.run(command, check=True, capture_output=True, text=True)
        print(f"LibreOffice 변환 성공. 출력:
{result.stdout}")
        
    except FileNotFoundError:
        print("오류: 'soffice' 명령을 찾을 수 없습니다. LibreOffice가 설치되어 있고 PATH에 등록되었는지 확인하세요.")
    except subprocess.CalledProcessError as e:
        print(f"LibreOffice 변환 실패. 오류:
{e.stderr}")

# 사용 예시
# hwp_file_path = "/path/to/document.hwp"
# pdf_output_dir = "/path/to/output"
# convert_hwp_to_pdf_libreoffice(hwp_file_path, pdf_output_dir)

5.3. 장점 및 단점 분석

• 장점:

  • 무료: 소프트웨어 라이선스 비용이 없다.
  • 크로스 플랫폼: Windows, Linux, macOS를 모두 지원한다.
  • 일괄 처리 지원: 스크립트를 통한 대량 변환에 용이하다.³²

• 단점:

  • 가변적인 변환 품질: 가장 결정적인 약점. 리버스 엔지니어링 기반이므로 레이아웃이 깨질 수 있다.
  • 무거운 의존성: 리브레오피스 스위트 전체를 서버에 설치해야 한다.
  • 성능: 프로세스를 새로 시작해야 하므로 속도가 느릴 수 있다.

이 접근법은 '품질 대 자유(Fidelity vs. Freedom)'의 트레이드오프를 보여준다. 공식 문서보다는 내용 확인이나 미리보기 생성 등 비핵심 업무에 적합하다.

6. 고려하지 않아야 할 접근법 및 흔한 함정

• olefile은 텍스트 추출 전용: 시각적 구조 렌더링 기능이 없다.⁷
• 유지보수가 중단된 라이브러리 (hwp2pdf): GitHub 저장소에 'unmaintained'로 명시되어 있으며,³³ 프로덕션 사용은 심각한 리스크를 초래한다.
• 범용 PDF 처리 라이브러리 (PyMuPDF, pypdf 등): HWP 소스 파일을 해석하는 기능이 없다.³

7. 솔루션 선택을 위한 비교 프레임워크

최적의 솔루션은 프로젝트의 운영 환경, 예산, 보안 요구사항, 품질 허용 범위에 따라 달라진다.

HWP-PDF 변환 방법론 비교 매트릭스

기능	COM 자동화 (pywin32)	클라우드 API (예: CloudConvert)	CLI 래퍼 (LibreOffice)
OS 호환성	Windows 전용	Windows, macOS, Linux	Windows, macOS, Linux
주요 의존성	한컴오피스 라이선스	인터넷 연결, API 구독	리브레오피스 스위트 설치
변환 품질	매우 높음 (네이티브)	높음 ~ 매우 높음 (독자적 엔진)	중간 ~ 높음 (리버스 엔지니어링)
비용 모델	자본/운영 비용	운영 비용 (사용량 기반)	무료 (숨겨진 유지보수 비용)
성능	높음 (로컬 처리)	네트워크에 의존	중간 (프로세스 오버헤드)
보안/프라이버시	매우 높음 (On-Premise)	낮음 ~ 중간 (외부 업로드)	매우 높음 (On-Premise)
설정 난이도	중간	쉬움	중간
이상적인 사용 사례	보안이 중요한 기업 백오피스	대국민 웹/모바일 서비스	예산 제한적인 내부 도구

8. 전략적 권장사항 및 최종 결론

8.1. 시나리오 1: Windows 기반의 기업 환경

• 권장 솔루션: COM 자동화 (pywin32)
• 근거: 최고의 변환 품질과 완벽한 데이터 보안을 보장한다.

8.2. 시나리오 2: 크로스 플랫폼 웹 또는 모바일 애플리케이션

• 권장 솔루션: 신뢰할 수 있는 클라우드 API (예: CloudConvert)
• 근거: 플랫폼 독립성과 확장성을 제공하는 가장 현실적인 해결책이다. 단, 제공업체에 대한 보안 검토가 필수적이다.

8.3. 시나리오 3: 예산이 제한적이거나 Linux 중심의 개발 환경

• 권장 솔루션: 리브레오피스 CLI 래퍼 (주의하여 사용)
• 근거: 무료로 사용할 수 있는 유일한 크로스 플랫폼 방법이다. 단, 도입 전 충분한 품질 테스트가 반드시 필요하다.

8.4. 최종 결론

HWP를 PDF로 변환하는 '최고의' 단일 방법은 존재하지 않는다. 최적의 선택은 전적으로 주어진 프로젝트의 기술적 아키텍처, 비즈니스 요구사항, 그리고 리스크 허용 범위에 달려있다. 본 보고서는 각 접근법의 전략적 트레이드오프를 명확히 제시함으로써, 개발자와 의사결정권자가 자신의 상황에 가장 부합하는 현명한 결정을 내릴 수 있도록 필요한 분석적 토대를 제공한다.