Skip to content
PDF Oxide

Міграція з PyMuPDF (fitz) на PDF Oxide

Повний посібник із переходу з PyMuPDF на PDF Oxide: усі API, якими ви користуєтеся сьогодні, і як їх замінити.

Навіщо йти з PyMuPDF?

Чотири вагомі причини для міграції:

  1. У 5,8× швидше — PDF Oxide у середньому опрацьовує сторінку за 0,8 мс проти 4,6 мс у PyMuPDF. На масштабі різниця накопичується: пакет із 1 000 сторінок завершиться менш ніж за секунду замість п’яти.
  2. Ліцензія MIT — PyMuPDF під AGPL змушує відкривати код будь-якого ПЗ, що з нею взаємодіє, або купувати комерційну ліцензію. PDF Oxide під MIT — користуйтеся скрізь без обмежень.
  3. Надійність 100 % — PDF Oxide проходить 100 % тестового набору PDF. PyMuPDF падає на 0,7 % файлів (99,3 % успіху) — це приблизно один зламаний результат на 140 документів.
  4. Вбудовані можливості — конвертація в Markdown, вивід HTML, OCR, підтримка форм XFA та рендеринг PDF входять у постачання. PyMuPDF для аналогічних задач потребує окремих пакетів (pymupdf4llm) або зовнішніх інструментів (Tesseract).

Крок 1. Встановлення

pip install pdf_oxide
pip uninstall pymupdf  # необов’язково — видаляйте, коли будете готові

Крок 2. Замініть імпорти

# До
import fitz

# Після
from pdf_oxide import PdfDocument

Якщо для Markdown ви використовували pymupdf4llm, цю залежність можна повністю прибрати — PDF Oxide підтримує Markdown нативно.

Крок 3. Таблиця відповідності API

Задача PyMuPDF PDF Oxide
Відкрити PDF fitz.open("file.pdf") PdfDocument("file.pdf")
Кількість сторінок doc.page_count doc.page_count()
Видобути текст doc[0].get_text() doc.extract_text(0)
Позиції символів doc[0].get_text("dict") doc.extract_chars(0)
Видобути зображення doc[0].get_images() + doc.extract_image(xref) doc.extract_images(0)
Пошук тексту doc[0].search_for("query") doc.search_page(0, "query")
Поля форм doc[0].widgets() або doc.get_form_fields() doc.get_form_fields()
Зашифрований PDF doc.authenticate("pw") PdfDocument("f.pdf", password="pw")
У Markdown pymupdf4llm.to_markdown("file.pdf") (окремий пакет) doc.to_markdown(0) (вбудовано)
У HTML Недоступно doc.to_html(0)
Створити PDF Вручну через insert_text() Pdf.from_markdown("# Заголовок")
Рендер у зображення doc[0].get_pixmap() doc.render_page(0)
Форми XFA Не підтримуються doc.has_xfa()
OCR Потрібен Tesseract Вбудований PaddleOCR

Крок 4. Типові зміни патернів

Цикл видобування тексту

# PyMuPDF
import fitz
doc = fitz.open("report.pdf")
for page in doc:
    text = page.get_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)

Видобування зображень

PyMuPDF потребує багатокрокового обходу xref. PDF Oxide робить це одним викликом:

# PyMuPDF — багатокроковий пошук через xref
import fitz
doc = fitz.open("report.pdf")
page = doc[0]
for img in page.get_images():
    xref = img[0]
    base = doc.extract_image(xref)
    with open(f"img.{base['ext']}", "wb") as f:
        f.write(base["image"])

# PDF Oxide — один крок
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i, img in enumerate(doc.extract_image_bytes(0)):
    with open(f"img_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

Зашифровані PDF

У PyMuPDF використовують двокроковий патерн «відкрити, потім автентифікуватися». PDF Oxide підтримує як password= у конструкторі, так і виклик doc.authenticate() після відкриття:

# PyMuPDF
import fitz
doc = fitz.open("encrypted.pdf")
doc.authenticate("password")
text = doc[0].get_text()

# PDF Oxide — один крок із password=
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Конвертація в Markdown

PyMuPDF вимагає окремий пакет pymupdf4llm. У PDF Oxide Markdown вбудовано:

# PyMuPDF — потрібен додатковий пакет
import pymupdf4llm
md = pymupdf4llm.to_markdown("report.pdf")

# PDF Oxide — вбудовано
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
md = doc.to_markdown(0)

Рендеринг сторінок

# PyMuPDF
import fitz
doc = fitz.open("report.pdf")
pix = doc[0].get_pixmap()
pix.save("page.png")

# 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)

Крок 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}")

Інші посібники з міграції

Пов’язані сторінки