Cómo crear documentos con el módulo de compatibilidad generado en Python

Aspose.PDF FOSS para Python incluye un subpaquete de compatibilidad generated (aspose_pdf.generated) que replica un subconjunto estable de la superficie principal de API — una clase Document con las operaciones centrales del ciclo de vida, más UnsignedContent/UnsignedContentAbsorber y PdfAValidateOptions/PdfAValidationResult. Existe para los llamadores que desean esta superficie más estrecha explícitamente en lugar de las clases de nivel superior con todas las funciones, y sus clases no se importan automáticamente por import aspose_pdf — las importas directamente desde aspose_pdf.generated.*. El paquete es puro Python y se instala con el siguiente comando.

Guía paso a paso

Paso 1: Instalar el paquete

Instala el paquete FOSS Aspose.PDF:

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

Verifica la instalación importando el Document generado y mostrando un mensaje de confirmación:

import aspose_pdf
from aspose_pdf.generated.document import Document
print("aspose-pdf-foss-for-python is ready.")

Paso 2: Importar clases requeridas

Las clases de compatibilidad generated se encuentran en aspose_pdf.generated.document, aspose_pdf.generated.forms y aspose_pdf.generated.pdfa — impórtalas explícitamente por submódulo:

import aspose_pdf
from aspose_pdf.generated.document import Document
from aspose_pdf.generated.forms import UnsignedContent, UnsignedContentAbsorber
from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

Paso 3: Crear y cargar un documento

Document(source) se carga inmediatamente cuando se proporciona una fuente; llamar a Document() sin argumento crea una instancia vacía que puedes cargar más tarde con load_from. Ambas aceptan una ruta de archivo, bytes, o un flujo binario:

from aspose_pdf.generated.document import Document

document = Document("report.pdf")
print(f"Loaded {len(document.pages)} page(s)")

empty_doc = Document()
empty_doc.load_from("report.pdf")

Paso 7: Extraer contenido de formulario no firmado

UnsignedContentAbsorber extrae las páginas, campos de formulario y anotaciones que no forman parte de una firma digital. Llama a extract() para ejecutar la extracción, has_extracted() para comprobar si se ha ejecutado, y get_extracted() para recuperar el resultado nuevamente sin volver a extraer:

from aspose_pdf.generated.forms import UnsignedContentAbsorber

absorber = UnsignedContentAbsorber()
unsigned = absorber.extract()
print(f"Unsigned pages: {len(unsigned.pages)}")
print(f"Unsigned form fields: {len(unsigned.form_fields)}")

if absorber.has_extracted():
    same_result = absorber.get_extracted()

Paso 8: Construir manualmente un contenedor UnsignedContent

UnsignedContent también es un contenedor simple que puedes poblar tú mismo con add_page, add_form_field y add_annotation — cada uno tiene un método remove_* correspondiente, y reset() borra las tres colecciones a la vez:

from aspose_pdf.generated.forms import UnsignedContent

content = UnsignedContent()
content.add_page("page-1")
content.add_annotation("signature-placeholder")
print(content)  # UnsignedContent(pages=1, form_fields=0, annotations=1)

content.remove_annotation("signature-placeholder")
content.reset()

Paso 9: Configurar y ejecutar la validación de PDF/A

PdfAValidateOptions recopila las entradas y configuraciones para una ejecución de validación. add_input(source) registra una entrada, set_option(key, value) almacena una opción con nombre, y get_options() devuelve una copia de las opciones almacenadas. PdfAValidationResult contiene el resultado — add_error(message) marca el resultado como inválido y lo añade a errors, y to_dict() representa is_valid y errors como un diccionario simple:

from aspose_pdf.generated.pdfa import PdfAValidateOptions, PdfAValidationResult

options = PdfAValidateOptions()
options.add_input("report.pdf")
options.set_option("pdfa_version", "1b")
print(options.get_options())

result = PdfAValidationResult()
result.add_error("Font 'Arial' is not embedded")
print(result.is_valid)   # False
print(result.to_dict())

Problemas comunes y soluciones

ImportError or AttributeError al acceder aspose_pdf.generated

El subpaquete generated no es reexportado por import aspose_pdf — importe cada clase desde su submódulo específico, por ejemplo from aspose_pdf.generated.document import Document, en lugar de esperar que aspose_pdf.generated.Document funcione después de un simple import aspose_pdf.

Confundir lo generado Document con el main aspose_pdf.Document

aspose_pdf.Document (la clase de nivel superior reexportada por import aspose_pdf) tiene una superficie mayor — añade métodos como validate_pdfa, iter_pages y redact_text que aspose_pdf.generated.document.Document no implementa. Si falta un método en el Document generado, compruebe si pertenece a la clase de nivel superior Document en su lugar.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() libera el estado interno del documento de forma permanente — un Document descartado no puede guardarse, optimizarse ni repararse después. Realice todas las operaciones restantes antes de llamar a close(), o vuelva a cargar desde la fuente con una nueva llamada a Document(...).

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords solo rota una contraseña en un documento que ya está cifrado. Llame a encrypt(password) primero, o compruebe document.is_encrypted antes de intentar cambiar la contraseña.

PdfAValidationResult.add_error raises TypeError

add_error requiere un argumento str. Convierta los objetos de excepción u otros detalles de error a una cadena (str(error)) antes de pasárselos a add_error.

Preguntas frecuentes

¿Por qué `aspose_pdf.generated` existe junto al `aspose_pdf.Document` principal?

Refleja un subconjunto más estrecho y estable del Aspose.PDF API para el código escrito contra esa superficie reducida. El código nuevo que no necesite específicamente este subconjunto de compatibilidad debería, en general, usar el aspose_pdf.Document de nivel superior, que admite más operaciones (PDF/A conversión, iteración de páginas, redacción de texto y otras).

¿Acepta `UnsignedContentAbsorber.extract()` un `Document` para escanear?

extract() acepta argumentos posicionales y de palabra clave que se utilizan para rellenar las colecciones pages, form_fields y annotations del UnsignedContent devuelto — pase las colecciones que desea representar como argumentos de palabra clave (pages=, form_fields=, annotations=).

¿Qué ocurre si llamo a `reset()` sobre `UnsignedContentAbsorber` antes de extraer nada?

Borra cualquier resultado extraído previamente. Entonces get_extracted() devuelve None y has_extracted() devuelve False hasta que se vuelva a llamar a extract().

¿Puede llamarse a `PdfAValidateOptions.add_input` más de una vez?

Sí — cada llamada añade otra entrada a la lista inputs, y devuelve self, por lo que las llamadas pueden encadenarse: options.add_input("a.pdf").add_input("b.pdf").

¿Es `close()` diferente de `dispose()` en el `Document` generado?

No — close() es un alias directo que llama a dispose() con los mismos argumentos; cualquiera de los dos nombres libera los recursos del documento.