Skip to content
PDF Oxide

Миграция с pdfminer.six на PDF Oxide

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

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

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

  1. Примерно в 30 раз быстрее — pdfminer является самой медленной из популярных Python PDF-библиотек. PDF Oxide обрабатывает страницу в среднем за 0,8 мс, pdfminer — за десятки миллисекунд. Пакетные задачи, занимавшие минуты, теперь выполняются за секунды.
  2. Активная поддержка — pdfminer.six обновляется редко и имеет большой список нерешённых issue. 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: Типовые изменения в коде

Базовое извлечение текста

extract_text в pdfminer обрабатывает весь документ целиком. 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 позволяет легко передавать 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)

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

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}")

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

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