Skip to content
PDF Oxide

Миграция с pypdf на PDF Oxide

Полное руководство по переходу с pypdf на PDF Oxide. Охватывает все используемые API и способы их замены.

Зачем переходить с pypdf?

Четыре веских причины для миграции:

  1. В 15 раз быстрее — PDF Oxide обрабатывает страницу в среднем за 0,8 мс, pypdf — за 12,1 мс. Обработка 500-страничного документа занимает 0,4 секунды вместо 6.
  2. 100% надёжность — PDF Oxide проходит 100% тестов PDF-набора. pypdf терпит неудачу на 1,6% файлов (98,4% успешных), то есть примерно каждый 60-й документ обрабатывается с ошибками.
  3. Встроенные Markdown и HTML — pypdf извлекает только простой текст. PDF Oxide конвертирует страницы в Markdown (с сохранением таблиц и структуры) и HTML — критично для LLM- и RAG-пайплайнов.
  4. Встроенные OCR и рендеринг — pypdf не поддерживает OCR и рендеринг страниц. PDF Oxide включает PaddleOCR для сканированных документов и рендеринг страниц в изображения без внешних зависимостей.

Шаг 1: Установка

pip install pdf_oxide
pip uninstall pypdf  # необязательно

Шаг 2: Замена импортов

# Было
from pypdf import PdfReader, PdfWriter, PdfMerger

# Стало
from pdf_oxide import PdfDocument, Pdf

Шаг 3: Таблица соответствия API

Задача pypdf PDF Oxide
Открыть PDF PdfReader("file.pdf") PdfDocument("file.pdf")
Количество страниц len(reader.pages) doc.page_count()
Извлечь текст reader.pages[0].extract_text() doc.extract_text(0)
Извлечь изображения reader.pages[0].images doc.extract_image_bytes(0)
Поля форм reader.get_fields() doc.get_form_fields()
Метаданные reader.metadata doc.metadata()
Зашифрованный PDF reader.decrypt("pw") PdfDocument("file.pdf", password="pw")
Объединить PDF PdfMerger() + .append() doc.merge_from("doc2.pdf")
Разделить страницы PdfWriter() + .add_page() doc.extract_pages([0,1,2,3,4], "out.pdf")
В Markdown Не поддерживается doc.to_markdown(0)
Рендеринг Не поддерживается doc.render_page(0)
OCR Не поддерживается doc.extract_text_ocr(0)

Шаг 4: Типовые изменения в коде

Извлечение текста

# pypdf
from pypdf import PdfReader
reader = PdfReader("report.pdf")
for page in reader.pages:
    print(page.extract_text())

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    print(doc.extract_text(i))

Объединение PDF

pypdf требует создания объекта-слияния и последовательного добавления файлов. PDF Oxide делает это за один вызов:

# pypdf
from pypdf import PdfMerger
merger = PdfMerger()
merger.append("doc1.pdf")
merger.append("doc2.pdf")
merger.write("merged.pdf")

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("doc1.pdf")
doc.merge_from("doc2.pdf")
doc.save("merged.pdf")

Разделение / извлечение страниц

# pypdf — ручное постраничное копирование
from pypdf import PdfReader, PdfWriter
reader = PdfReader("report.pdf")
writer = PdfWriter()
for page in reader.pages[0:5]:
    writer.add_page(page)
writer.write("first_5_pages.pdf")

# PDF Oxide — один вызов
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
doc.extract_pages([0, 1, 2, 3, 4], "first_5_pages.pdf")

Зашифрованные PDF

# pypdf — два шага: open + decrypt
from pypdf import PdfReader
reader = PdfReader("encrypted.pdf")
reader.decrypt("password")
text = reader.pages[0].extract_text()

# PDF Oxide — пароль в конструкторе
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Конвертация в Markdown (новая возможность)

pypdf не поддерживает Markdown. PDF Oxide позволяет легко передавать PDF в LLM-пайплайны:

from pdf_oxide import PdfDocument

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

Извлечение изображений

# pypdf
from pypdf import PdfReader
reader = PdfReader("report.pdf")
for image in reader.pages[0].images:
    with open(image.name, "wb") as f:
        f.write(image.data)

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
images = doc.extract_image_bytes(0)
for i, img in enumerate(images):
    with open(f"image_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

Шаг 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}")

Другие руководства по миграции

Связанные страницы