Come creare documenti con il modulo di compatibilità generato in Python

Aspose.PDF FOSS per Python fornisce un sottopacchetto di compatibilità generated (aspose_pdf.generated) che riproduce un sottoinsieme stabile della superficie principale di API — una classe Document con le operazioni fondamentali del ciclo di vita, più UnsignedContent/UnsignedContentAbsorber e PdfAValidateOptions/PdfAValidationResult. Esiste per gli chiamanti che desiderano esplicitamente questa superficie più ristretta anziché le classi di livello superiore con tutte le funzionalità, e le sue classi non sono importate automaticamente da import aspose_pdf — le importi direttamente da aspose_pdf.generated.*. Il pacchetto è puro Python e viene installato con il comando riportato di seguito.

Guida passo passo

Passo 1: Installa il pacchetto

Installa il pacchetto 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 l’installazione importando il Document generato e stampando un messaggio di conferma:

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

Passo 2: Importa le classi richieste

Le classi di compatibilità generated si trovano in aspose_pdf.generated.document, aspose_pdf.generated.forms e aspose_pdf.generated.pdfa — importale esplicitamente tramite il sotto-modulo:

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

Passo 3: Crea e carica un documento

Document(source) si carica immediatamente quando viene fornita una sorgente; chiamare Document() senza argomento crea un’istanza vuota che puoi caricare in seguito con load_from. Entrambi accettano un percorso file, bytes, o un flusso 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")

Passo 7: Estrai il contenuto del modulo non firmato

UnsignedContentAbsorber estrae le pagine, i campi modulo e le annotazioni che non fanno parte di una firma digitale. Chiama extract() per eseguire l’estrazione, has_extracted() per verificare se è stata eseguita, e get_extracted() per recuperare nuovamente il risultato senza rieseguire l’estrazione:

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

Passo 8: Costruisci manualmente un contenitore UnsignedContent

UnsignedContent è anche un semplice contenitore che puoi popolare tu stesso con add_page, add_form_field e add_annotation — ciascuno ha un metodo remove_* corrispondente, e reset() cancella tutte e tre le collezioni in una volta:

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

Passo 9: Configura ed Esegui la Validazione PDF/A

PdfAValidateOptions raccoglie gli input e le impostazioni per un’esecuzione di validazione. add_input(source) registra un input, set_option(key, value) memorizza un’opzione nominata e get_options() restituisce una copia delle opzioni memorizzate. PdfAValidationResult contiene il risultato — add_error(message) segna il risultato come non valido e lo aggiunge a errors, e to_dict() rende is_valid e errors come un semplice dizionario:

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

Problemi comuni e soluzioni

ImportError or AttributeError quando si accede aspose_pdf.generated

Il sottopacchetto generated non è re-esportato da import aspose_pdf — importa ogni classe dal suo specifico sottomodulo, ad esempio from aspose_pdf.generated.document import Document, invece di aspettarti che aspose_pdf.generated.Document funzioni dopo un semplice import aspose_pdf.

Confondere il generato Document con il principale aspose_pdf.Document

aspose_pdf.Document (la classe di livello superiore re-esportata da import aspose_pdf) ha una superficie più ampia — aggiunge metodi come validate_pdfa, iter_pages e redact_text che aspose_pdf.generated.document.Document non implementa. Se un metodo manca nel Document generato, verifica se invece appartiene alla classe di livello superiore Document.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() rilascia lo stato interno del documento in modo permanente — un Document eliminato non può essere salvato, ottimizzato o riparato successivamente. Esegui tutte le operazioni rimanenti prima di chiamare close(), oppure ricarica dalla sorgente con una nuova chiamata a Document(...).

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords ruota solo la password su un documento già crittografato. Chiama prima encrypt(password), oppure controlla document.is_encrypted prima di tentare di cambiare la password.

PdfAValidationResult.add_error raises TypeError

add_error richiede un argomento str. Converte gli oggetti eccezione o altri dettagli dell’errore in una stringa (str(error)) prima di passarli a add_error.

Domande frequenti

Perché `aspose_pdf.generated` esiste accanto al `aspose_pdf.Document` principale?

Riflette un sottoinsieme più ristretto e stabile del Aspose.PDF API per il codice scritto contro quella superficie ridotta. Il nuovo codice che non ha specificamente bisogno di questo sottoinsieme di compatibilità dovrebbe generalmente usare il aspose_pdf.Document di livello superiore, che supporta più operazioni (PDF/A conversion, page iteration, text redaction, e altri).

Il `UnsignedContentAbsorber.extract()` accetta un `Document` da scansionare?

extract() accetta positional and keyword arguments usati per popolare le collezioni pages, form_fields e annotations del UnsignedContent restituito — passa le collezioni che desideri rappresentare come keyword arguments (pages=, form_fields=, annotations=).

Cosa succede se chiamo `reset()` su `UnsignedContentAbsorber` prima di estrarre qualcosa?

Cancella qualsiasi risultato precedentemente estratto. get_extracted() restituisce quindi None e has_extracted() restituisce False fino a quando extract() non viene chiamato di nuovo.

Può `PdfAValidateOptions.add_input` essere chiamato più di una volta?

Sì — ogni chiamata aggiunge un’altra voce alla lista inputs e restituisce self, così le chiamate possono essere concatenate: options.add_input("a.pdf").add_input("b.pdf").

È `close()` diverso da `dispose()` sul `Document` generato?

No — close() è un alias diretto che chiama dispose() con gli stessi argomenti; entrambi i nomi rilasciano le risorse del documento.