Skip to content
PDF Oxide

pdfminer.six에서 PDF Oxide로 마이그레이션

pdfminer(pdfminer.six)에서 PDF Oxide로 전환하기 위한 완전한 가이드입니다. 현재 사용 중인 모든 API와 대체 방법을 다룹니다.

왜 pdfminer에서 전환해야 합니까?

마이그레이션해야 하는 4가지 이유가 있습니다:

  1. 약 30배 빠름 — pdfminer는 주요 Python PDF 라이브러리 중 가장 느립니다. PDF Oxide는 페이지당 평균 0.8ms이지만 pdfminer는 수십 밀리초가 걸립니다. 몇 분 걸리던 배치 작업이 몇 초로 단축됩니다.
  2. 활발한 유지보수 — pdfminer.six는 업데이트 빈도가 낮고 미해결 이슈가 많습니다. PDF Oxide는 활발하게 개발되며 정기적으로 릴리스됩니다.
  3. 올인원 라이브러리 — pdfminer는 텍스트 추출만 가능합니다. PDF Oxide는 PDF 생성, 편집, 페이지 렌더링, 이미지 추출, 양식 처리, Markdown/HTML 변환을 모두 지원합니다.
  4. 설정 불필요 — pdfminer는 적절한 결과를 얻기 위해 LAParams(word_margin, line_margin, char_margin)를 수동으로 조정해야 합니다. PDF Oxide는 레이아웃 감지를 자동으로 처리합니다.

1단계: 설치

pip install pdf_oxide
pip uninstall pdfminer.six  # 선택 사항

2단계: 임포트 변경

# 변경 전
from pdfminer.high_level import extract_text, extract_pages
from pdfminer.layout import LAParams

# 변경 후
from pdf_oxide import PdfDocument

3단계: API 매핑 테이블

작업 pdfminer PDF Oxide
텍스트 추출 extract_text("file.pdf") PdfDocument("file.pdf").extract_text(0)
페이지 추출 extract_pages("file.pdf") doc.extract_text(i)로 페이지별 처리
레이아웃 분석 LAParams() 설정 내장 레이아웃 감지
문자 위치 LTChar 객체 doc.extract_chars(0)
암호화 PDF 제한적 (AES-256에서 실패) 완전 지원
Markdown 변환 지원하지 않음 doc.to_markdown(0)
양식 필드 지원하지 않음 doc.get_form_fields()

4단계: 일반적인 패턴 변경

기본 텍스트 추출

pdfminer의 extract_text는 전체 문서를 한 번에 처리합니다. PDF Oxide는 페이지별 제어를 제공합니다:

# pdfminer — 전체 문서를 한 번에 처리
from pdfminer.high_level import extract_text
text = extract_text("report.pdf")
print(text)

# PDF Oxide — 페이지별 제어
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(text)

레이아웃 분석

pdfminer는 LAParams의 수동 설정이 필요합니다. PDF Oxide는 자동으로 처리합니다:

# pdfminer — 수동 레이아웃 설정
from pdfminer.high_level import extract_text
from pdfminer.layout import LAParams

params = LAParams(
    word_margin=0.1,
    line_margin=0.5,
    char_margin=2.0,
    boxes_flow=0.5,
)
text = extract_text("report.pdf", laparams=params)

# PDF Oxide — 자동 레이아웃 감지
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
text = doc.extract_text(0)  # 레이아웃 자동 처리

문자 수준 추출

pdfminer는 복잡한 레이아웃 객체 트리를 사용합니다. PDF Oxide는 플랫 리스트를 반환합니다:

# pdfminer — 레이아웃 트리 순회
from pdfminer.high_level import extract_pages
from pdfminer.layout import LTChar, LTTextBox

for page_layout in extract_pages("report.pdf"):
    for element in page_layout:
        if isinstance(element, LTTextBox):
            for line in element:
                for char in line:
                    if isinstance(char, LTChar):
                        print(f"{char.get_text()} at ({char.x0}, {char.y0})")

# PDF Oxide — 플랫 문자 리스트
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for c in doc.extract_chars(0):
    print(f"{c.char} at ({c.x}, {c.y})")

암호화 PDF

pdfminer는 암호화 지원이 제한적이며 AES-256 암호화 파일에서 실패합니다:

# pdfminer — 많은 암호화 PDF에서 실패
from pdfminer.high_level import extract_text
text = extract_text("encrypted.pdf", password="password")
# AES-256 암호화 파일에서 오류 발생 가능

# PDF Oxide — 완전한 암호화 지원
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)  # 모든 암호화 방식 지원

Markdown 변환 (새로운 기능)

pdfminer는 Markdown을 지원하지 않습니다. PDF Oxide를 사용하면 LLM 파이프라인에 쉽게 투입할 수 있습니다:

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    md = doc.to_markdown(i)
    print(md)

양식 필드 추출 (새로운 기능)

pdfminer는 양식 필드를 추출할 수 없습니다. PDF Oxide는 이를 처리할 수 있습니다:

from pdf_oxide import PdfDocument

doc = PdfDocument("form.pdf")
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

페이지 렌더링 (새로운 기능)

pdfminer에는 렌더링 기능이 없습니다. PDF Oxide는 페이지를 이미지로 렌더링할 수 있습니다:

from pdf_oxide import PdfDocument

doc = PdfDocument("report.pdf")
png_bytes = doc.render_page(0, dpi=150)
with open("page.png", "wb") as f:
    f.write(png_bytes)

주요 차이점

  1. LAParams 조정 불필요 — PDF Oxide는 레이아웃을 자동으로 처리합니다. word_margin, line_margin 등의 설정이 필요하지 않습니다.
  2. 속도 — pdfminer는 Python PDF 라이브러리 중 가장 느립니다. PDF Oxide는 약 30배 빠릅니다.
  3. 올인원 — pdfminer는 추출만 가능합니다. PDF Oxide는 PDF 생성, 편집, 렌더링도 할 수 있습니다.

5단계: 마이그레이션 테스트

기존 테스트 파일을 두 라이브러리로 실행하고 출력을 비교합니다:

from pdf_oxide import PdfDocument

doc = PdfDocument("your-test-file.pdf")

# 텍스트 추출 확인
text = doc.extract_text(0)
print(text[:500])

# 페이지 수 확인
print(f"Pages: {doc.page_count()}")

# 양식 필드 확인 (해당하는 경우)
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

다른 마이그레이션 가이드

관련 페이지