Mac에서 FastAPI로 .docx 파일 불러오기

Mac에서 FastAPI로 .docx 파일 불러오기

 

Mac 환경에서 FastAPI를 사용해 .docx 형식의 파일을 업로드하고 처리해야 하는 경우가 종종 있습니다. 이번 포스팅에서는 파이썬의 python-docx 패키지를 이용해 .docx 파일을 불러오고 내용에 접근하는 방법을 소개해드리겠습니다.

---

1. python-docx 패키지란?

 

python-docx는 파이썬에서 Word(.docx) 문서를 생성하거나, 이미 존재하는 .docx 파일의 텍스트를 읽고 조작할 수 있게 해주는 라이브러리입니다.

 

대표적으로 할 수 있는 일은 다음과 같습니다.

• .docx 파일에서 텍스트 추출

• .docx 파일을 새로 생성 및 수정

• 문단(paragraph), 표(table), 글머리기호 등의 서식 정보에 접근

 

python-docx는 파이썬 버전 3.6 이상에서 지원됩니다.

 

---

2. 개발 환경 준비

 

2.1 파이썬 & FastAPI 설치

 

맥 환경(MacOS)에서 FastAPI를 사용하기 위해서는 먼저 파이썬 환경과 FastAPI가 설치되어 있어야 합니다. 보통 가상환경(Virtual Environment)을 사용하는 것을 권장합니다.

# 예시) Python3.9 버전 설치되어 있다고 가정
python3 -m venv venv
source venv/bin/activate

# FastAPI, Uvicorn(서버)를 설치
pip install fastapi uvicorn

 

2.2 python-docx 설치

 

이제 .docx 파일을 다루기 위한 python-docx를 설치해야 합니다.

pip install python-docx

---

3. FastAPI 예제 코드

 

아래 코드는 .docx 파일을 업로드받은 뒤, 문서 내 텍스트를 추출해 간단히 반환하는 예제입니다.

# 파일명 예: main.py
from fastapi import FastAPI, UploadFile, File
import docx

app = FastAPI()

@app.post("/upload-docx")
async def upload_docx(file: UploadFile = File(...)):
    # 업로드된 파일을 읽어옵니다.
    contents = await file.read()
    
    # python-docx에서는 파일 경로 뿐만 아니라 바이너리 스트림(메모리)도 처리할 수 있습니다.
    from io import BytesIO
    doc = docx.Document(BytesIO(contents))
    
    # 문서 내 모든 문단(paragraph)의 텍스트를 추출
    full_text = []
    for para in doc.paragraphs:
        full_text.append(para.text)
    
    # 텍스트를 연결해서 반환
    return {
        "filename": file.filename,
        "file_text": "\n".join(full_text)
    }

 

• uvicorn main:app --reload 옵션을 사용하면 코드를 수정할 때마다 서버가 자동으로 재시작됩니다.

• 서버가 정상적으로 구동되면, http://127.0.0.1:8000/docs 주소에 접속해서 FastAPI가 제공하는 자동 문서화 인터페이스(Swagger UI)를 확인할 수 있습니다.

• /upload-docx 경로에서 .docx 파일을 업로드해보면, JSON 형태로 텍스트가 반환되는 것을 확인할 수 있습니다.

---

4. 코드 동작 원리

1. UploadFile

• FastAPI에서 업로드된 파일을 처리할 때 사용되는 클래스입니다.

• .file, .filename, .content_type, .read() 등의 속성과 메서드를 제공합니다.

2. python-docx

• .docx 파일을 Document 객체로 변환하여, 문단/표 등 다양한 요소에 접근할 수 있게 해줍니다.

• 바이너리 스트림(메모리)을 다룰 수 있으므로, BytesIO를 통해 업로드된 파일 내용을 직접 처리할 수 있습니다.

3. 파일 내용 읽기(file.read())

• async 함수를 통해 파일의 전체 내용을 읽어서 contents 변수에 저장합니다.

4. BytesIO(contents)

• .docx 파일을 메모리에서 직접 열기 위해, contents를 BytesIO로 감싸서 docx.Document에 넘겨줍니다.

5. 문단 반복(doc.paragraphs)

• doc.paragraphs에서 텍스트를 추출해 리스트에 저장하고, 마지막에 하나의 문자열로 합칩니다.

---

5. 마무리

 

맥OS 환경에서 FastAPI를 사용해 .docx 파일을 업로드받고 처리하려면, python-docx 패키지를 사용하면 간단합니다. 위 예시는 파일의 텍스트를 추출하는 가장 기본적인 흐름이지만, 이를 확장하여 문단에 스타일을 적용하거나, 테이블 정보를 분석해 JSON 형태로 변환하는 작업도 가능해집니다.

 

사용 예시:

• 문서 분석 자동화

• 웹에서 사용자가 업로드한 리포트를 자동으로 요약해 PDF로 변환

• .docx 템플릿 기반으로 레포트 생성 및 다운로드 기능 제공

 

실무나 개인 프로젝트에서 Word 문서를 다루어야 할 때, 꼭 한 번 시도해보시길 바랍니다.

---

참고

• FastAPI 공식 문서

• python-docx PyPI

 

이 포스팅이 도움이 되었다면, 댓글이나 공감 부탁드립니다! 궁금한 점이 있다면 언제든 질문 남겨주세요.