Skip to content
PDF Oxide

Migrar do pdfminer.six para o PDF Oxide

Guia completo para migrar do pdfminer (pdfminer.six) para o PDF Oxide, cobrindo todas as APIs que você usa atualmente e como substituí-las.

Por que migrar do pdfminer?

Quatro razões convincentes para migrar:

  1. Cerca de 30x mais rápido — O pdfminer é a biblioteca Python de PDF mais lenta entre as principais. O PDF Oxide processa em média 0,8ms por página, enquanto o pdfminer leva dezenas de milissegundos. Tarefas em lote que levavam minutos agora são concluídas em segundos.
  2. Manutenção ativa — O pdfminer.six recebe atualizações com pouca frequência e possui um grande acúmulo de issues em aberto. O PDF Oxide é desenvolvido ativamente com lançamentos regulares.
  3. Biblioteca completa — O pdfminer só faz extração de texto. O PDF Oxide também cria PDFs, edita, renderiza páginas em imagens, extrai imagens, processa formulários e converte para Markdown/HTML.
  4. Sem configuração necessária — O pdfminer requer ajuste manual de LAParams (word_margin, line_margin, char_margin) para obter resultados aceitáveis. O PDF Oxide detecta o layout automaticamente.

Passo 1: Instalação

pip install pdf_oxide
pip uninstall pdfminer.six  # opcional

Passo 2: Substituir imports

# Antes
from pdfminer.high_level import extract_text, extract_pages
from pdfminer.layout import LAParams

# Depois
from pdf_oxide import PdfDocument

Passo 3: Tabela de mapeamento de API

Tarefa pdfminer PDF Oxide
Extrair texto extract_text("file.pdf") PdfDocument("file.pdf").extract_text(0)
Extrair páginas extract_pages("file.pdf") Página a página com doc.extract_text(i)
Análise de layout Configuração LAParams() Detecção de layout integrada
Posições de caracteres Objetos LTChar doc.extract_chars(0)
PDF criptografado Suporte limitado (falha em AES-256) Suporte completo
Para Markdown Não suportado doc.to_markdown(0)
Campos de formulário Não suportado doc.get_form_fields()

Passo 4: Mudanças em padrões comuns

Extração básica de texto

O extract_text do pdfminer processa o documento inteiro de uma vez. O PDF Oxide oferece controle por página:

# pdfminer — documento inteiro de uma vez
from pdfminer.high_level import extract_text
text = extract_text("report.pdf")
print(text)

# PDF Oxide — controle por página
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(text)

Análise de layout

O pdfminer requer configuração manual de LAParams. O PDF Oxide faz automaticamente:

# pdfminer — configuração manual de layout
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 — detecção automática de layout
from pdf_oxide import PdfDocument
doc = PdfDocument("report.pdf")
text = doc.extract_text(0)  # Layout tratado automaticamente

Extração em nível de caractere

O pdfminer usa uma árvore complexa de objetos de layout. O PDF Oxide retorna uma lista plana:

# pdfminer — percorrer árvore de layout
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 — lista plana de caracteres
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})")

PDFs criptografados

O pdfminer tem suporte limitado a criptografia e falha em arquivos AES-256:

# pdfminer — falha em muitos PDFs criptografados
from pdfminer.high_level import extract_text
text = extract_text("encrypted.pdf", password="password")
# Pode gerar erro em arquivos criptografados com AES-256

# PDF Oxide — suporte completo a criptografia
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)  # Funciona com todos os métodos de criptografia

Conversão para Markdown (nova funcionalidade)

O pdfminer não suporta Markdown. O PDF Oxide facilita a integração de PDFs em pipelines de LLM:

from pdf_oxide import PdfDocument

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

Extração de campos de formulário (nova funcionalidade)

O pdfminer não consegue extrair campos de formulário. O PDF Oxide lida com isso:

from pdf_oxide import PdfDocument

doc = PdfDocument("form.pdf")
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

Renderização de páginas (nova funcionalidade)

O pdfminer não possui capacidade de renderização. O PDF Oxide pode renderizar páginas em imagens:

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)

Principais diferenças

  1. Sem ajuste de LAParams — O PDF Oxide lida com o layout automaticamente. Não é necessário configurar word_margin, line_margin, etc.
  2. Velocidade — O pdfminer é a biblioteca Python de PDF mais lenta. O PDF Oxide é cerca de 30x mais rápido.
  3. Tudo-em-um — O pdfminer só faz extração. O PDF Oxide também cria, edita e renderiza PDFs.

Passo 5: Testando a migração

Execute seus arquivos de teste existentes em ambas as bibliotecas e compare as saídas:

from pdf_oxide import PdfDocument

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

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

# Verificar número de páginas
print(f"Pages: {doc.page_count()}")

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

Outros guias de migração

Páginas relacionadas