Comment créer des documents avec le module de compatibilité généré dans Python

Aspose.PDF FOSS pour Python propose un sous-package de compatibilité generated (aspose_pdf.generated) qui reproduit un sous-ensemble stable de la surface principale API — une classe Document avec les opérations de cycle de vie de base, ainsi que UnsignedContent/UnsignedContentAbsorber et PdfAValidateOptions/PdfAValidationResult. Il existe pour les appelants qui souhaitent cette surface plus restreinte explicitement plutôt que les classes de haut niveau riches en fonctionnalités, et ses classes ne sont pas importées automatiquement par import aspose_pdf — vous les importez directement depuis aspose_pdf.generated.*. Le package est purement Python et s’installe avec la commande ci-dessous.

Guide étape par étape

Étape 1: Installer le package

Installez le package 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 .

Vérifiez l’installation en important le Document généré et en affichant un message de confirmation:

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

Étape 2: Importer les classes requises

Les classes de compatibilité generated se trouvent dans aspose_pdf.generated.document, aspose_pdf.generated.forms et aspose_pdf.generated.pdfa — importez-les explicitement par sous-module:

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

Étape 3: Créer et charger un document

Document(source) se charge immédiatement lorsqu’une source est fournie; appeler Document() sans argument crée une instance vide que vous pouvez charger plus tard avec load_from. Les deux acceptent un chemin de fichier, bytes, ou un flux binaire:

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

Étape 7: Extraire le contenu du formulaire non signé

UnsignedContentAbsorber extrait les pages, champs de formulaire et annotations qui n’ont pas fait partie d’une signature numérique. Appelez extract() pour exécuter l’extraction, has_extracted() pour vérifier si elle a été exécutée, et get_extracted() pour récupérer à nouveau le résultat sans ré-extraction:

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

Étape 8: Construire manuellement un conteneur UnsignedContent

UnsignedContent est également un conteneur simple que vous pouvez remplir vous-même avec add_page, add_form_field et add_annotation — chacun dispose d’une méthode remove_* correspondante, et reset() efface les trois collections en même temps:

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

Étape 9: Configurer et exécuter la validation PDF/A

PdfAValidateOptions recueille les entrées et les paramètres pour une exécution de validation. add_input(source) enregistre une entrée, set_option(key, value) stocke une option nommée, et get_options() renvoie une copie des options stockées. PdfAValidationResult contient le résultat — add_error(message) marque le résultat comme invalide et l’ajoute à errors, et to_dict() rend is_valid et errors sous forme de dictionnaire 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())

Problèmes courants et solutions

ImportError or AttributeError lors de l’accès aspose_pdf.generated

Le sous-package generated n’est pas réexporté par import aspose_pdf — importez chaque classe depuis son sous-module spécifique, par exemple from aspose_pdf.generated.document import Document, plutôt que de s’attendre à ce que aspose_pdf.generated.Document fonctionne après un simple import aspose_pdf.

Confondre le généré Document avec le principal aspose_pdf.Document

aspose_pdf.Document (la classe de niveau supérieur réexportée par import aspose_pdf) possède une surface plus large — elle ajoute des méthodes telles que validate_pdfa, iter_pages et redact_text que aspose_pdf.generated.document.Document n’implémente pas. Si une méthode manque dans le Document généré, vérifiez si elle appartient plutôt à la classe de niveau supérieur Document.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() libère l’état interne du document de façon permanente — un Document éliminé ne peut pas être enregistré, optimisé ou réparé par la suite. Effectuez toutes les opérations restantes avant d’appeler close(), ou rechargez depuis la source avec un nouvel appel Document(...).

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords ne fait que faire pivoter un mot de passe sur un document déjà chiffré. Appelez encrypt(password) d’abord, ou vérifiez document.is_encrypted avant d’essayer de changer le mot de passe.

PdfAValidationResult.add_error raises TypeError

add_error nécessite un argument str. Convertissez les objets d’exception ou d’autres détails d’erreur en chaîne (str(error)) avant de les transmettre à add_error.

Foire aux questions

Pourquoi `aspose_pdf.generated` existe-t-il aux côtés du `aspose_pdf.Document` principal?

Il reflète un sous-ensemble plus étroit et stable du Aspose.PDF API pour le code écrit contre cette surface réduite. Le nouveau code qui n’a pas spécifiquement besoin de cet sous-ensemble de compatibilité devrait généralement utiliser le aspose_pdf.Document de niveau supérieur, qui prend en charge davantage d’opérations (PDF/A conversion, itération de pages, rédaction de texte, et d’autres).

Est-ce que `UnsignedContentAbsorber.extract()` accepte un `Document` à scanner?

extract() accepte des arguments positionnels et nommés qui sont utilisés pour remplir les collections pages, form_fields et annotations du UnsignedContent retourné — transmettez les collections que vous souhaitez représenter en tant qu’arguments nommés (pages=, form_fields=, annotations=).

Que se passe-t-il si j’appelle `reset()` sur `UnsignedContentAbsorber` avant d’extraire quoi que ce soit?

Cela efface tout résultat précédemment extrait. get_extracted() renvoie alors None et has_extracted() renvoie False jusqu’à ce que extract() soit appelé de nouveau.

Le `PdfAValidateOptions.add_input` peut-il être appelé plus d’une fois?

Oui — chaque appel ajoute une autre entrée à la liste inputs, et il renvoie self, de sorte que les appels peuvent être chaînés: options.add_input("a.pdf").add_input("b.pdf").

Le `close()` est-il différent de `dispose()` sur le `Document` généré?

Non — close() est un alias direct qui appelle dispose() avec les mêmes arguments; les deux noms libèrent les ressources du document.