Einleitung
Aspose.PDF FOSS für Python konzentriert sich auf die Klasse Document, die pages, form, outlines, tagged_content und attachments als Einstiegspunkte für strukturelle, dokumentenbezogene Bearbeitung bereitstellt. Neben dem Hinzufügen von Seiteninhalt deckt die Bibliothek die Vorgänge ab, die ein PDF zu einem vollständigen, verteilbaren Artefakt machen: interaktive Formularfelder, die strukturierte Daten sammeln und bereitstellen, dateibasierte Anhänge auf Dokumentenebene, Schriftartenerkennung und -einbettung für die Textverfassung sowie einen Lesezeichenbaum zur Navigation. Jeder dieser Bereiche wirft Fehler über eine einheitliche Ausnahmehierarchie, die in AsposePdfException verankert ist, sodass Aufrufer paketbezogene Fehler abfangen können, ohne für jedes Modul die Ausnahmetypen erraten zu müssen.
Dieses Handbuch zeigt, wie man mit dieser Dokumentverwaltungsoberfläche arbeitet: das Abfangen und Unterscheiden von AsposePdfException-Unterklassen, das Erstellen und Lesen von AcroForm-Feldern mit Form und Field, das Einbetten und Wiederherstellen von Anhängen über FileSpecification, das Auflösen von Schriften mit FontRepository und FontRegistry sowie das Erstellen eines Lesezeichenbaums mit OutlineCollection und OutlineItem. Jeder Abschnitt verwendet nur die Klassen und Methoden, die im aktuellen Paket vorhanden sind.
Aspose.PDF FOSS für Python ist ein Python-Paket, aspose-pdf-foss-for-python, veröffentlicht unter der MIT-Lizenz, das Python 3.11 oder höher erfordert. Der Name des Top-Level-Moduls ist aspose_pdf. Das Kernpaket hängt nur von cryptography und asn1crypto ab; optionale Extras fügen bildbasierte Dekodierung über Pillow, Brotli-basierte WOFF2-Schriftunterstützung und HarfBuzz-basierte komplexe Textlayout-Funktionen hinzu.
Hauptfunktionen
Ausnahmebehandlung mit AsposePdfException
Jeder paketbezogene Fehler in Aspose.PDF FOSS für Python leitet sich von AsposePdfException ab. Die meisten Dokumentverarbeitungsfehler fallen unter dessen PdfException-Unterklasse, die wiederum die Basis für PdfParseException (fehlerhafte Eingabe), PdfSecurityException (Verschlüsselungs- und Passwortfehler, einschließlich InvalidPasswordException) und PdfValidationException (strukturelle oder Konformitätsfehler) bildet. Das Abfangen von AsposePdfException zuletzt, nach den spezifischeren Unterklassen, ermöglicht es einem Aufrufer, unterschiedlich auf ein falsches Passwort im Vergleich zu einer beschädigten Datei zu reagieren, während weiterhin ein einziger Fallback für alle anderen vom Paket auslösbaren Ausnahmen besteht.
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
Interaktive Formularfelder
Document.form gibt eine Form Fassade über den AcroForm Feldern des Dokuments zurück. Form.add_text_field(), add_checkbox() und add_radio_group() erzeugen neue Terminalfelder, die an eine Seite und ein Widget-Rechteck gebunden sind, wobei jedes ein Field zurückgibt. Field stellt name, value und field_type bereit, sodass vorhandene Felder nach Namen inspiziert und aktualisiert werden können, und Field.remove() löscht ein Feld vollständig.
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")
Eingebettete Dateien und Anhänge
Document.add_attachment bettet Bytes als Dateianhang auf Dokumentebene ein, der beim Speichern in den /Names /EmbeddedFiles Namensbaum des PDFs geschrieben wird, zusammen mit einem optionalen MIME-Typ, einer Beschreibung und Erstellungs-/Änderungsdaten. Document.embedded_files liest jeden Anhang wieder als typisiertes FileSpecification (name, contents, mime_type, description, size) ein, und Document.get_embedded_file sucht einen nach Namen. FileSpecification.save() schreibt die wiederhergestellten Bytes auf die Festplatte.
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")
Schrifterkennung und Einbetten
FontRepository aggregiert Schriftquellen und löst Schriften nach Namen im gesamten Dokument auf. FontRepository.add_source() registriert ein FontSource wie FolderFontSource (scannt ein Verzeichnis, optional rekursiv); FontRepository.find_font() und search() lösen dann eine Schrift nach Familie, Voll- oder PostScript Namen auf und greifen bei Bedarf auf das Standard-Schrift-Register zurück. Jeder Treffer ist ein FontDescriptor, der direkt an Page.add_text übergeben werden kann, um die Schrift einzubetten und zu subsetten. FontRegistry ordnet gängige nicht-standardisierte Namen (Arial, Times New Roman und ähnlichen) über search_font_by_name() ihrem nächstgelegenen Standard-14-Äquivalent zu.
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")
Dokumentgliederung und Lesezeichen
Document.outlines gibt ein OutlineCollection zurück, den obersten Container für den Lesezeichenbaum eines PDFs. OutlineCollection.add fügt ein OutlineItem auf oberster Ebene hinzu; OutlineItem.add() verschachtelt ein untergeordnetes Lesezeichen unter einem bestehenden. Jeder OutlineItem trägt ein title, ein Ziel-page_index und Anzeige-Flags is_bold / is_italic, und stellt seine eigene children-Liste bereit.
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")
Schnellstart
Installieren Sie das Paket und erstellen Sie dann ein Dokument, das ein Lesezeichen, Dokumentmetadaten und einen Anhang in einem einzigen Skript kombiniert.
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])
Unterstützte Formate
| Format | Erweiterung | Lesen | Schreiben |
|---|---|---|---|
| Ja | Ja | ||
| TIFF | tiff | - | Ja |
Page.render, Page.save_as_image und Document.save_page_as_image erzeugen ebenfalls PNG-Rasterausgabe neben TIFF.
Dies sind Seitenrasterisierungsausgaben und keine Dokumentladeformate.
Open Source & Lizenzierung
Aspose.PDF FOSS für Python wird unter der MIT-Lizenz veröffentlicht: keine Nutzungsbeschränkungen, keine Laufzeitgebühren und keine Registrierungsanforderungen für kommerzielle oder private Nutzung. Der Quellcode ist gehostet unter github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, und das Paket wird auf PyPI als aspose-pdf-foss-for-python veröffentlicht.
