파이썬으로 MS Word 문서 작성하기(python-docx)

이전 회사에서 실제로 구현했던 python-docx를 활용한 Word 보고서 자동화 방법을 정리해보려고 한다.

보고서 내용에는 데이터에 대한 여러 정보들을 정형화된 틀(template)에 작성하여 docx 문서로 만든 후 pdf로 사용자에게 전달하는 방식을 선택했다.

 

---

1. python-docx란?

python-docx는 Python에서 Microsoft Word 문서(.docx)를 생성하고, 수정할 수 있도록 도와주는 라이브러리이다. 보고서 자동화, 템플릿 기반 문서 생성, 문서 파싱 등 다양한 용도로 활용된다.

---

2. python-docx의 기본 구조

Word 문서 계층 구조

Document
├── Paragraph (본문 문단)
│   └── Run (문장/단어 스타일 단위)
├── Table (표)
│   ├── Row (행)
│   │   └── Cell (셀)
│   │       └── Paragraph

🔹 핵심 객체 설명

 

📄 Document

• 문서 전체를 대표하는 객체
• .docx 파일을 열거나 새로 생성할 때 사용

📑 Paragraph

• 하나의 문단 (한 줄의 텍스트)
• 내부는 여러 Run 객체로 구성

✍️ Run

✅ 스타일 단위로 텍스트가 나뉘기 때문에 치환 시 run.text를 사용해서 부분 수정할 수 있음

• Paragraph 안의 텍스트 단위
• 텍스트 스타일(굵게, 기울임, 색상 등)이 바뀔 때마다 Run이 끊김

📊 Table, Row, Cell

• Word 내 표를 구성하는 기본 단위
• Cell 내부도 Paragraph로 구성되어 있음

---

3. 자동화 기본 구조

1. 템플릿 문서(.docx)에 키워드 삽입 ([TITLE], [STATUS], [SCREENSHOT] 등)

2. Python 코드에서 키워드에 대응되는 데이터를 불러옴

3. 키워드를 텍스트 또는 이미지로 치환

4. 최종 .docx → .pdf 변환 (옵션)

 

---

 

4. 실습

🔧 설치

pip install python-docx

 

📄 템플릿 문서 작성

보고서 포맷에 따라 텍스트 치환 포인트([키워드])와 이미지 삽입 위치([SCREENSHOT])를 넣어

 

1) 코드 작성

실제론 DB 에서 데이터를 가져왔지만, 관계상 Dictionary로 대체한다.

from docx import Document

# 데이터 정의
data = {
    '[URL]': 'https://naver.com',
    '[WEB_RISK]': '5%',
    '[TITLE]': 'NAVER',
    '[STATUS]': '200',
    '[SCREENSHOT]': './www.naver.com_.png',  # 이미지 경로
}

# 템플릿 로드
doc = Document('./report_base.docx')

 

2) 표 안에 텍스트 치환

✅ paragraph.clear()로 기존 텍스트만 제거하고, 기본 스타일은 유지

for table in doc.tables:
    for row in table.rows:
        for cell in row.cells:
            cell_text = cell.text.strip()
            if cell_text in data:   # data key와 텍스트 일치 여부 확인
                # 셀 안의 paragraph 전체 clear 후 치환 텍스트로 대체
                for paragraph in cell.paragraphs:
                    paragraph.clear()  # 스타일 유지됨 (기본 스타일)
                    paragraph.add_run(data[cell_text])

 

3) 이미지 삽입

[SCREENSHOT] 텍스트 자리에 이미지 삽입

✅ Inches(5)는 이미지 너비를 5인치(약 12.7cm)로 설정

from docx.shared import Inches

for paragraph in doc.paragraphs:
    if paragraph.text == '[SCREENSHOT]':
        paragraph.clear()
        paragraph.add_run().add_picture(data['[SCREENSHOT]'], width=Inches(5))

 

4) 결과 저장

doc.save('./output.docx')

 

결과

 

 

---

5. 마무리

이렇게 python-docx를 활용하면 Word 문서를 정형화된 템플릿 기반으로 손쉽게 자동화할 수 있다.

보고서, 점검표, 분석 리포트 등 반복되는 문서 자동화에 사용하면 좋을것으로 생각된다.