How to Generate PDF Reports from HTML Templates in Python

Context

자체 호스팅 PDF 라이브러리(wkhtmltopdf, weasyprint)는 프로세스 관리 오버헤드, 메모리 소비(50~150MB), 2~4초 렌더링 시간, 그리고 대량 생성 시 병렬 처리 불가능이라는 한계가 있다. 월 1,000건 이상의 PDF 생성(청구서, 영수증, 명세서)이 필요한 경우 CPU 비용이 급증한다.

Technical Solution

• HTML 템플릿을 Jinja2 또는 Django 템플릿 엔진으로 렌더링해 HTML 문자열로 변환
• 렌더링된 HTML을 PageBolt API의 /v1/pdf 엔드포인트로 POST 요청해 PDF 바이너리 응답 수신
• Django 뷰에서 FileResponse를 통해 다운로드 가능한 파일로 즉시 반환
• ThreadPoolExecutor를 사용해 5~10개 워커로 병렬 PDF 생성(100개 파일 ~10초)
• 429(레이트 제한), Timeout, RequestException에 대한 재시도 로직 구현(최대 3회, exponential backoff)

Impact

• 월 50건 이상 생성 환경에서 API 사용이 자체 호스팅보다 비용 효율적
• 월 100건: API 비용 $3~5 vs 자체 호스팅 인프라 비용
• 월 1,000건: API 비용 $15~25 vs 자체 호스팅 CPU 스파이크
• 100개 PDF 병렬 생성 시 약 10초 완료(자체 호스팅 대비 대폭 단축)

Key Takeaway

HTML 템플릿 렌더링과 PDF 변환을 분리해 HTTP API 기반으로 처리하면, 프로세스 관리 복잡도를 제거하면서도 비용과 성능 모두에서 이득을 얻을 수 있다. 특히 월 50~1,000건 규모의 대량 보고서 생성 환경에서 API 기반 접근이 실질적으로 저렴하고 안정적이다.