Skip to content
PDF Oxide

Migrar do PyMuPDF (fitz) para o PDF Oxide

Um guia completo para trocar o PyMuPDF pelo PDF Oxide, cobrindo cada API que você usa hoje e como substituí-la.

Por que trocar o PyMuPDF?

São quatro motivos convincentes para migrar:

  1. 5,8× mais rápido — o PDF Oxide fica em média em 0,8 ms por página, contra 4,6 ms do PyMuPDF. Em escala a diferença se acumula: um lote de 1 000 páginas termina em menos de um segundo, e não cinco.
  2. Licença MIT — o PyMuPDF usa AGPL, que obriga a abrir o código de qualquer software que interaja com ele, ou a comprar uma licença comercial. O PDF Oxide é MIT — use em qualquer lugar, sem amarras.
  3. Confiabilidade total — PDF Oxide aceita toda a suíte de testes PDF. O PyMuPDF falha em 0,7 % dos arquivos (99,3 % de sucesso), o que significa saída quebrada em cerca de 1 a cada 140 documentos.
  4. Recursos nativos — Markdown, HTML, OCR, formulários XFA e renderização, tudo integrado. O PyMuPDF precisa de pacotes separados (pymupdf4llm) ou ferramentas externas (Tesseract) para algo equivalente.

Passo 1: Instalar

pip install pdf_oxide
pip uninstall pymupdf  # opcional — remova quando estiver pronto

Passo 2: Trocar os imports

# Antes
import fitz

# Depois
from pdf_oxide import PdfDocument

Se você usava pymupdf4llm para conversão Markdown, pode remover essa dependência por inteiro — o PDF Oxide já traz isso embutido.

Passo 3: Mapeamento de API

Tarefa PyMuPDF PDF Oxide
Abrir PDF fitz.open("file.pdf") PdfDocument("file.pdf")
Contagem de páginas doc.page_count doc.page_count()
Extrair texto doc[0].get_text() doc.extract_text(0)
Posições de caracteres doc[0].get_text("dict") doc.extract_chars(0)
Extrair imagens doc[0].get_images() + doc.extract_image(xref) doc.extract_images(0)
Buscar texto doc[0].search_for("query") doc.search_page(0, "query")
Campos de formulário doc[0].widgets() ou doc.get_form_fields() doc.get_form_fields()
PDF criptografado doc.authenticate("pw") PdfDocument("f.pdf", password="pw")
Para Markdown pymupdf4llm.to_markdown("file.pdf") (pacote à parte) doc.to_markdown(0) (embutido)
Para HTML Indisponível doc.to_html(0)
Criar PDF insert_text() manual Pdf.from_markdown("# Título")
Renderizar em imagem doc[0].get_pixmap() doc.render_page(0)
Formulários XFA Sem suporte doc.has_xfa()
OCR Requer Tesseract PaddleOCR embutido

Passo 4: Mudanças em padrões comuns

Laço de extração de texto

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

Extração de imagens

O PyMuPDF exige uma busca xref em várias etapas. O PDF Oxide resolve em uma única chamada:

# PyMuPDF — busca xref em várias etapas
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 — uma etapa
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"])

PDFs criptografados

O PyMuPDF segue o padrão em duas etapas: abrir e depois autenticar. O PDF Oxide aceita tanto password= no construtor quanto doc.authenticate() após abrir:

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

# PDF Oxide — uma etapa com password=
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Conversão para Markdown

O PyMuPDF exige o pacote separado pymupdf4llm. O PDF Oxide traz Markdown nativo:

# PyMuPDF — exige pacote extra
import pymupdf4llm
md = pymupdf4llm.to_markdown("report.pdf")

# PDF Oxide — embutido
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
md = doc.to_markdown(0)

Renderização de páginas

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

Passo 5: Testar a migração

Passe seus arquivos de teste pelas duas bibliotecas e compare as saídas:

from pdf_oxide import PdfDocument

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

# Verifica a extração de texto
text = doc.extract_text(0)
print(text[:500])

# Verifica a contagem de páginas
print(f"Pages: {doc.page_count()}")

# Verifica os campos de formulário (se houver)
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

Outros guias de migração

Páginas relacionadas