Introducción

Aspose.PDF FOSS para Python se centra en la clase Document, que expone pages, form, outlines, tagged_content y attachments como puntos de entrada para la edición estructural y a nivel de documento. Más allá de añadir contenido a la página, la biblioteca cubre las operaciones que convierten un PDF en un artefacto completo y distribuible: campos de formulario interactivos que recopilan y exponen datos estructurados, archivos adjuntos a nivel de documento, descubrimiento e incorporación de fuentes para la creación de texto, y un árbol de marcadores para la navegación. Cada una de estas áreas genera errores a través de una única jerarquía de excepciones con raíz en AsposePdfException, de modo que los llamadores pueden capturar fallos específicos del paquete sin adivinar los tipos de excepción módulo por módulo.

Esta guía muestra cómo trabajar con esa capa de gestión de documentos: capturar y distinguir subclases de AsposePdfException, crear y leer campos AcroForm con Form y Field, incrustar y recuperar adjuntos mediante FileSpecification, resolver fuentes con FontRepository y FontRegistry, y construir un árbol de marcadores con OutlineCollection y OutlineItem. Cada sección utiliza solo las clases y métodos presentes en el paquete actual.

Aspose.PDF FOSS para Python es un paquete Python, aspose-pdf-foss-for-python, publicado bajo la licencia MIT, que requiere Python 3.11 o posterior. Su nombre de módulo de nivel superior es aspose_pdf. El paquete central depende solo de cryptography y asn1crypto; complementos opcionales añaden decodificación de imágenes basada en Pillow, soporte de fuentes WOFF2 basado en Brotli, y maquetación de texto compleja basada en HarfBuzz.

Características clave

Manejo de excepciones con AsposePdfException

Cada error específico del paquete en Aspose.PDF FOSS para Python deriva de AsposePdfException. La mayoría de los fallos de procesamiento de documentos se agrupan bajo su subclase PdfException, que a su vez es la base para PdfParseException (entrada malformada), PdfSecurityException (fallos de cifrado y contraseña, incluido InvalidPasswordException), y PdfValidationException (fallos estructurales o de cumplimiento). Capturar AsposePdfException al final, después de las subclases más específicas, permite que el llamador reaccione de manera diferente a una contraseña incorrecta que a un archivo corrupto, mientras sigue teniendo una única alternativa de reserva para todo lo demás que el paquete pueda generar.

from aspose_pdf import Document
from aspose_pdf.exceptions import (
    AsposePdfException,
    InvalidPasswordException,
    PdfParseException,
)


def open_document(path, password=None):
    try:
        document = Document()
        document.load_from(path, password=password)
        return document
    except InvalidPasswordException:
        print(f"{path}: a correct password is required")
    except PdfParseException as error:
        print(f"{path}: not a valid PDF ({error})")
    except AsposePdfException as error:
        # Catches every other aspose_pdf-specific error not handled above.
        print(f"{path}: PDF operation failed ({error})")
    return None

Campos de formulario interactivos

Document.form devuelve una fachada Form sobre los campos AcroForm del documento. Form.add_text_field(), add_checkbox() y add_radio_group() crean nuevos campos terminales vinculados a una página y a un rectángulo de widget, cada uno devolviendo un Field. Field expone name, value y field_type para que los campos existentes puedan inspeccionarse y actualizarse por nombre, y Field.remove() elimina un campo por completo.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()

    document.form.add_text_field("customer_name", page, (72, 700, 300, 720))
    document.form.add_checkbox("subscribe", page, (72, 670, 90, 688), on_value="Yes")
    document.form.add_radio_group(
        "plan",
        page,
        {"Basic": (72, 630, 90, 648), "Pro": (72, 600, 90, 618)},
        value="Basic",
    )

    for field in document.form.fields:
        print(field.name, field.field_type, field.value)

    for field in document.form.fields:
        if field.name == "customer_name":
            field.value = "Jane Doe"

    document.form.generate_appearances()
    document.save("form.pdf")

Archivos incrustados y adjuntos

Document.add_attachment incrusta bytes como un adjunto de archivo a nivel de documento, escrito en el árbol de nombres /Names /EmbeddedFiles del PDF al guardar, junto con un tipo MIME opcional, descripción y fechas de creación/modificación. Document.embedded_files lee cada adjunto de vuelta como un FileSpecification tipado (name, contents, mime_type, description, size), y Document.get_embedded_file busca uno por nombre. FileSpecification.save() escribe los bytes recuperados en disco.

from aspose_pdf import Document

with Document() as document:
    document.pages.add()
    document.add_attachment(
        "notes.txt",
        b"Reviewed and approved.",
        mime="text/plain",
        description="Reviewer notes",
    )
    document.save("with-attachment.pdf")

with Document() as document:
    document.load_from("with-attachment.pdf")

    for spec in document.embedded_files:
        print(spec.name, spec.mime_type, spec.size)

    notes = document.get_embedded_file("notes.txt")
    if notes is not None:
        notes.save("notes-recovered.txt")

Descubrimiento e incrustación de fuentes

FontRepository agrega fuentes y resuelve fuentes por nombre en todo el documento. FontRepository.add_source() registra un FontSource como FolderFontSource (escanea un directorio, opcionalmente de forma recursiva); FontRepository.find_font() y search() luego resuelven una fuente por familia, nombre completo o PostScript, recurriendo al registro de fuentes estándar. Cada coincidencia es un FontDescriptor, que puede pasarse directamente a Page.add_text para incrustar y subestablecer la fuente. FontRegistry asigna nombres comunes no estándar (Arial, Times New Roman y similares) a su equivalente más cercano del Standard-14 mediante search_font_by_name().

from aspose_pdf import Document, FolderFontSource, FontRepository
from aspose_pdf.font_registry import FontRegistry

FontRepository.add_source(FolderFontSource("./fonts", scan_subdirectories=True))

descriptor = FontRepository.find_font("Open Sans")
if descriptor is None:
    # Fall back to the closest Standard-14 match for a common font name.
    descriptor = FontRegistry().search_font_by_name("Arial")

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Rendered with a resolved font",
        x=72,
        y=700,
        font_size=14,
        font=descriptor,
    )
    document.save("font-sample.pdf")

Contornos y marcadores del documento

Document.outlines devuelve un OutlineCollection, el contenedor de nivel superior para el árbol de marcadores de un PDF. OutlineCollection.add agrega un OutlineItem de nivel superior; OutlineItem.add() anida un marcador hijo bajo uno existente. Cada OutlineItem lleva un title, un page_index objetivo, y banderas de visualización is_bold / is_italic, y expone su propia lista de children.

from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem

with Document() as document:
    document.pages.add()
    document.pages.add()

    chapter = OutlineItem("Chapter 1: Overview", page_index=0)
    document.outlines.add(chapter)
    chapter.add(OutlineItem("Section 1.1", page_index=0, is_italic=True))
    document.outlines.add(OutlineItem("Chapter 2: Details", page_index=1, is_bold=True))

    document.save("bookmarked.pdf")

Inicio rápido

Instale el paquete y luego cree un documento que combine un marcador, metadatos del documento y un adjunto en un solo script.

asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.
from aspose_pdf import Document
from aspose_pdf.outlines import OutlineItem

with Document() as document:
    page = document.pages.add()
    page.add_text("Quarterly Report", x=72, y=740, font_size=20)

    document.outlines.add(OutlineItem("Quarterly Report", page_index=0))
    document.info = {"Title": "Quarterly Report"}
    document.add_attachment(
        "source-data.csv", b"quarter,total\nQ1,1000\n", mime="text/csv"
    )
    document.save("report.pdf")

with Document() as reopened:
    reopened.load_from("report.pdf")
    print(reopened.page_count, "page(s),", reopened.info.get("Title"))
    print([spec.name for spec in reopened.embedded_files])

Formatos compatibles

FormatoExtensiónLeerEscribir
PDFpdfSíSí
TIFFtiff-Sí

Page.render, Page.save_as_image y Document.save_page_as_image también generan salida raster PNG junto a TIFF.

Estos son resultados de rasterización de página en lugar de formatos de carga de documento.

Código abierto y licencias

Aspose.PDF FOSS para Python se lanza bajo la licencia MIT: sin restricciones de uso, sin cuotas de tiempo de ejecución y sin requisitos de registro para uso comercial o personal. El código fuente está alojado en github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, y el paquete se publica en PyPI como aspose-pdf-foss-for-python.

Primeros pasos

Recursos relacionados