Wie man Dokumente mit dem generierten Kompatibilitätsmodul in Python erstellt

Aspose.PDF FOSS für Python liefert ein generated Kompatibilitäts-Subpaket (aspose_pdf.generated), das einen stabilen Teilbereich der Haupt-API-Oberfläche abbildet – eine Document Klasse mit den Kern-Lebenszyklus-Operationen sowie UnsignedContent/UnsignedContentAbsorber und PdfAValidateOptions/PdfAValidationResult. Es existiert für Aufrufer, die diese engere Oberfläche explizit statt der voll ausgestatteten Top-Level-Klassen benötigen, und seine Klassen werden nicht automatisch von import aspose_pdf importiert – Sie importieren sie direkt aus aspose_pdf.generated.*. Das Paket ist reines Python und wird mit dem unten stehenden Befehl installiert.

Schritt-für-Schritt-Anleitung

Schritt 1: Paket installieren

Installieren Sie das Aspose.PDF FOSS-Paket:

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

Verifizieren Sie die Installation, indem Sie das generierte Document importieren und eine Bestätigungsnachricht ausgeben:

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

Schritt 2: Erforderliche Klassen importieren

Die generated Kompatibilitätsklassen befinden sich in aspose_pdf.generated.document, aspose_pdf.generated.forms und aspose_pdf.generated.pdfa — importieren Sie sie explizit per Untermodul:

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

Schritt 3: Ein Dokument erstellen und laden

Document(source) lädt sofort, wenn eine Quelle angegeben wird; ein Aufruf von Document() ohne Argument erzeugt eine leere Instanz, die Sie später mit load_from laden können. Beide akzeptieren einen Dateipfad, bytes oder einen Binärstrom:

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

Schritt 7: Nicht signierten Formularinhalt extrahieren

UnsignedContentAbsorber extrahiert die Seiten, Formularfelder und Anmerkungen, die nicht Teil einer digitalen Signatur waren. Rufen Sie extract() auf, um die Extraktion auszuführen, has_extracted(), um zu prüfen, ob sie bereits ausgeführt wurde, und get_extracted(), um das Ergebnis erneut abzurufen, ohne erneut zu extrahieren:

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

Schritt 8: Einen UnsignedContent-Container manuell erstellen

UnsignedContent ist auch ein einfacher Container, den Sie selbst mit add_page, add_form_field und add_annotation füllen können — jedes hat eine passende remove_*-Methode, und reset() löscht alle drei Sammlungen auf einmal:

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

Schritt 9: PDF/A-Validierung konfigurieren und ausführen

PdfAValidateOptions sammelt die Eingaben und Einstellungen für einen Validierungslauf. add_input(source) registriert eine Eingabe, set_option(key, value) speichert eine benannte Option und get_options() gibt eine Kopie der gespeicherten Optionen zurück. PdfAValidationResult enthält das Ergebnis — add_error(message) markiert das Ergebnis als ungültig und fügt es errors hinzu, und to_dict() rendert is_valid und errors als einfaches Wörterbuch:

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

Häufige Probleme und Lösungen

ImportError or AttributeError beim Zugriff aspose_pdf.generated

Das generated-Unterpaket wird von import aspose_pdf nicht erneut exportiert — importieren Sie jede Klasse aus ihrem jeweiligen Untermodul, zum Beispiel from aspose_pdf.generated.document import Document, anstatt zu erwarten, dass aspose_pdf.generated.Document nach einem einfachen import aspose_pdf funktioniert.

Verwirrende die erzeugten Document mit dem Haupt aspose_pdf.Document

aspose_pdf.Document (die von import aspose_pdf erneut exportierte Oberklasse) hat eine größere Oberfläche — sie fügt Methoden wie validate_pdfa, iter_pages und redact_text hinzu, die aspose_pdf.generated.document.Document nicht implementiert. Wenn eine Methode im generierten Document fehlt, prüfen Sie, ob sie stattdessen zur Oberklasse Document gehört.

save() raises AsposePdfException: Cannot save a disposed document

close()/dispose() gibt den internen Zustand des Dokuments dauerhaft frei — ein verworfener Document kann danach nicht gespeichert, optimiert oder repariert werden. Führen Sie alle verbleibenden Vorgänge aus, bevor Sie close() aufrufen, oder laden Sie aus der Quelle mit einem frischen Document(...)-Aufruf neu.

change_passwords raises PdfSecurityException: Document is not encrypted

change_passwords rotiert nur ein Passwort bei einem bereits verschlüsselten Dokument. Rufen Sie zuerst encrypt(password) auf oder prüfen Sie document.is_encrypted, bevor Sie versuchen, das Passwort zu ändern.

PdfAValidationResult.add_error raises TypeError

add_error erfordert ein str-Argument. Konvertieren Sie Ausnahmeobjekte oder andere Fehlermeldungen in eine Zeichenkette (str(error)), bevor Sie sie an add_error übergeben.

Häufig gestellte Fragen

Warum existiert `aspose_pdf.generated` neben dem Haupt-`aspose_pdf.Document`?

Es spiegelt ein engeres, stabiles Teilset des Aspose.PDF API für Code wider, der gegen diese reduzierte Oberfläche geschrieben wurde. Neuer Code, der dieses Kompatibilitäts-Teilset nicht explizit benötigt, sollte im Allgemeinen das Top-Level aspose_pdf.Document verwenden, das mehr Operationen unterstützt (PDF/A Konvertierung, Seiteniteration, Textredaktion und andere).

Akzeptiert `UnsignedContentAbsorber.extract()` ein `Document` zum Scannen?

extract() akzeptiert Positions- und Schlüsselwortargumente, die verwendet werden, um die zurückgegebene UnsignedContent’s pages, form_fields und annotations Sammlungen zu füllen — übergeben Sie die Sammlungen, die Sie als Schlüsselwortargumente repräsentiert haben möchten (pages=, form_fields=, annotations=).

Was passiert, wenn ich `reset()` auf `UnsignedContentAbsorber` aufrufe, bevor ich irgendetwas extrahiere?

Es löscht jedes zuvor extrahierte Ergebnis. get_extracted() gibt dann None zurück und has_extracted() gibt False zurück, bis extract() erneut aufgerufen wird.

Kann `PdfAValidateOptions.add_input` mehr als einmal aufgerufen werden?

Ja — jeder Aufruf fügt einen weiteren Eintrag zur inputs-Liste hinzu und gibt self zurück, sodass Aufrufe verkettet werden können: options.add_input("a.pdf").add_input("b.pdf").

Ist `close()` anders als `dispose()` im erzeugten `Document`?

Nein — close() ist ein direkter Alias, der dispose() mit denselben Argumenten aufruft; beide Namen geben die Ressourcen des Dokuments frei.