Skip to content
PDF Oxide

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

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

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

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

  1. В 29 раз быстрее — PDF Oxide обрабатывает страницу в среднем за 0,8 мс, pdfplumber — за 23,2 мс. 100-страничный документ обрабатывается за 80 мс вместо 2,3 секунды.
  2. Поддержка зашифрованных PDF — pdfplumber вообще не может открывать зашифрованные PDF. PDF Oxide прозрачно обрабатывает все методы шифрования, включая AES-256.
  3. Извлечение изображений — pdfplumber не умеет извлекать изображения. PDF Oxide извлекает встроенные изображения за один вызов.
  4. Вывод в Markdown — pdfplumber возвращает таблицы в виде списков Python, которые нужно форматировать вручную. PDF Oxide выдаёт структурированный Markdown с сохранением таблиц, готовый для LLM.

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

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

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

# Было
import pdfplumber

# Стало
from pdf_oxide import PdfDocument

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

Задача pdfplumber PDF Oxide
Открыть PDF pdfplumber.open("file.pdf") PdfDocument("file.pdf")
Количество страниц len(pdf.pages) doc.page_count()
Извлечь текст pdf.pages[0].extract_text() doc.extract_text(0)
Позиции символов pdf.pages[0].chars doc.extract_chars(0)
Извлечь таблицы pdf.pages[0].extract_tables() doc.to_markdown(0)
Поля форм Не поддерживается (только чтение) doc.get_form_fields()
Зашифрованный PDF Не поддерживается PdfDocument("file.pdf", password="pw")
Извлечь изображения Не поддерживается doc.extract_image_bytes(0)
В Markdown Не поддерживается doc.to_markdown(0)
Рендеринг Не поддерживается doc.render_page(0)
OCR Не поддерживается doc.extract_text_ocr(0)
Создать PDF Не поддерживается Pdf.from_markdown("# Title")

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

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

pdfplumber требует контекстный менеджер. PDF Oxide — нет:

# pdfplumber — нужен контекстный менеджер
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    for page in pdf.pages:
        text = page.extract_text()
        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)

Извлечение таблиц

pdfplumber возвращает таблицы в виде вложенных списков Python. PDF Oxide выводит их в формате Markdown:

# pdfplumber — возвращает список списков
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    tables = pdf.pages[0].extract_tables()
    for table in tables:
        for row in table:
            print(row)

# PDF Oxide — структурированный Markdown
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
md = doc.to_markdown(0)
print(md)  # Таблицы отрисованы как Markdown-таблицы

Посимвольное извлечение

# pdfplumber
import pdfplumber
with pdfplumber.open("report.pdf") as pdf:
    chars = pdf.pages[0].chars
    for c in chars:
        print(f"{c['text']} at ({c['x0']}, {c['top']})")

# PDF Oxide
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
chars = doc.extract_chars(0)
for c in chars:
    print(f"{c.char} at ({c.x}, {c.y})")

Зашифрованные PDF (новая возможность)

pdfplumber не может открывать зашифрованные PDF. PDF Oxide обрабатывает их прозрачно:

from pdf_oxide import PdfDocument

# Поддерживает все методы шифрования, включая AES-256
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)
print(text)

Извлечение изображений (новая возможность)

pdfplumber не умеет извлекать изображения. 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"])

OCR для сканированных документов (новая возможность)

pdfplumber не обрабатывает сканированные PDF. PDF Oxide включает встроенный OCR:

from pdf_oxide import PdfDocument

doc = PdfDocument("scanned.pdf")
text = doc.extract_text_ocr(0)
print(text)

Ключевые различия

  1. Без контекстного менеджера — pdfplumber использует with pdfplumber.open(...) as pdf:. PDF Oxide не требует контекстного менеджера.
  2. Зашифрованные PDF — pdfplumber вообще не может их открыть. PDF Oxide обрабатывает шифрование прозрачно.
  3. Таблицы — pdfplumber возвращает списки Python. PDF Oxide выводит таблицы в формате Markdown или HTML. Для сложных таблиц с визуальной отладкой можно использовать pdfplumber параллельно с PDF Oxide.

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

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

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