Skip to content
PDF Oxide

Migrar de PyMuPDF (fitz) a PDF Oxide

Una guía completa para pasar de PyMuPDF a PDF Oxide, cubriendo cada API que usas hoy y cómo reemplazarla.

¿Por qué cambiar de PyMuPDF?

Hay cuatro razones de peso para migrar:

  1. 5,8× más rápido — PDF Oxide promedia 0,8 ms por página frente a los 4,6 ms de PyMuPDF. A escala esa diferencia se multiplica: un lote de 1 000 páginas termina en menos de un segundo en lugar de cinco.
  2. Licencia MIT — PyMuPDF usa AGPL, que te obliga a liberar el código de cualquier software que interactúe con ella, o a comprar una licencia comercial. PDF Oxide es MIT — úsalo donde quieras, sin ataduras.
  3. Fiabilidad del 100 % — PDF Oxide pasa el 100 % de la suite de pruebas PDF. PyMuPDF falla en un 0,7 % de los archivos (tasa de éxito del 99,3 %), lo que supone salida rota en aproximadamente 1 de cada 140 documentos.
  4. Funciones integradas — conversión a Markdown, salida HTML, OCR, soporte de formularios XFA y renderizado de PDF vienen incluidos. PyMuPDF requiere paquetes aparte (pymupdf4llm) o herramientas externas (Tesseract) para funciones similares.

Paso 1: Instalar

pip install pdf_oxide
pip uninstall pymupdf  # opcional — quítalo cuando estés listo

Paso 2: Sustituir los imports

# Antes
import fitz

# Después
from pdf_oxide import PdfDocument

Si usabas pymupdf4llm para convertir a Markdown, puedes eliminar esa dependencia por completo — PDF Oxide la trae de serie.

Paso 3: Mapeo de API

Tarea PyMuPDF PDF Oxide
Abrir PDF fitz.open("file.pdf") PdfDocument("file.pdf")
Número de páginas doc.page_count doc.page_count()
Extraer texto doc[0].get_text() doc.extract_text(0)
Posiciones de caracteres doc[0].get_text("dict") doc.extract_chars(0)
Extraer imágenes 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 formulario doc[0].widgets() o doc.get_form_fields() doc.get_form_fields()
PDF cifrado doc.authenticate("pw") PdfDocument("f.pdf", password="pw")
A Markdown pymupdf4llm.to_markdown("file.pdf") (paquete aparte) doc.to_markdown(0) (integrado)
A HTML No disponible doc.to_html(0)
Crear PDF insert_text() manual Pdf.from_markdown("# Título")
Renderizar a imagen doc[0].get_pixmap() doc.render_page(0)
Formularios XFA No soportado doc.has_xfa()
OCR Requiere Tesseract PaddleOCR integrado

Paso 4: Cambios de patrones habituales

Bucle de extracción 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)

Extracción de imágenes

PyMuPDF necesita una búsqueda xref en varios pasos. PDF Oxide lo resuelve en una sola llamada:

# PyMuPDF — búsqueda xref en varios pasos
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 — un solo paso
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 cifrados

PyMuPDF sigue un patrón de dos pasos: abrir y luego autenticar. PDF Oxide admite tanto password= en el constructor como doc.authenticate() después de abrir:

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

# PDF Oxide — un paso con password=
from pdf_oxide import PdfDocument
doc = PdfDocument("encrypted.pdf", password="password")
text = doc.extract_text(0)

Conversión a Markdown

PyMuPDF exige el paquete aparte pymupdf4llm. PDF Oxide lleva Markdown integrado:

# PyMuPDF — requiere paquete extra
import pymupdf4llm
md = pymupdf4llm.to_markdown("report.pdf")

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

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

Paso 5: Probar la migración

Pasa tus archivos de prueba por ambas bibliotecas y compara las salidas:

from pdf_oxide import PdfDocument

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

# Verifica la extracción de texto
text = doc.extract_text(0)
print(text[:500])

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

# Verifica los campos de formulario (si aplica)
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name}: {f.value}")

Otras guías de migración

Páginas relacionadas