Introduktion
Aspose.PDF FOSS för Python fokuserar på klassen Document, som exponerar pages, form, outlines, tagged_content och attachments som ingångspunkter för strukturell, dokumentnivåredigering. Utöver att lägga till sidinnehåll täcker biblioteket de operationer som gör en PDF till ett komplett, distribuerbart artefakt: interaktiva formulärfält som samlar in och exponerar strukturerad data, filbilagor på dokumentnivå, upptäckt och inbäddning av typsnitt för textförfattande samt ett bokmärkesträd för navigering. Var och en av dessa områden kastar fel genom en enda undantagshierarki med rot i AsposePdfException, så att anroparna kan fånga paket-specifika fel utan att gissa på undantagstyper modul för modul.
Denna guide visar hur man arbetar med den dokumenthanteringsytan: fånga och särskilja AsposePdfException-subklasser, skapa och läsa AcroForm-fält med Form och Field, bädda in och återvinna bilagor via FileSpecification, lösa upp typsnitt med FontRepository och FontRegistry, samt bygga ett bokmärkesträd med OutlineCollection och OutlineItem. Varje avsnitt använder endast de klasser och metoder som finns i det aktuella paketet.
Aspose.PDF FOSS för Python är ett Python-paket, aspose-pdf-foss-for-python, släppt under MIT-licensen, och kräver Python 3.11 eller senare. Dess top-nivåmodulnamn är aspose_pdf. Kärnpaketet beror endast på cryptography och asn1crypto; valfria tillägg lägger till Pillow-baserad bildavkodning, Brotli-baserat WOFF2-typsnittsstöd och HarfBuzz-baserad komplex textlayout.
Viktiga funktioner
Undantagshantering med AsposePdfException
Varje paket-specifikt fel i Aspose.PDF FOSS för Python härstammar från AsposePdfException. De flesta dokumentbehandlingsfel faller under dess PdfException-subklass, som i sin tur är bas för PdfParseException (felaktig inmatning), PdfSecurityException (krypterings- och lösenordsfel, inklusive InvalidPasswordException), och PdfValidationException (strukturella eller efterlevnadsfel). Att fånga AsposePdfException sist, efter mer specifika subklasser, gör att en anropar kan reagera annorlunda på ett fel lösenord än på en korrupt fil samtidigt som den har en enda återfalla för allt annat som paketet kan kasta.
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
Interaktiva formulärfält
Document.form returnerar en Form fasad över dokumentets AcroForm fält. Form.add_text_field(), add_checkbox() och add_radio_group() skapar nya terminalfält kopplade till en sida och en widget-rektangel, var och en returnerar en Field. Field exponerar name, value och field_type så att befintliga fält kan inspekteras och uppdateras efter namn, och Field.remove() tar bort ett fält helt.
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")
Inbäddade filer och bilagor
Document.add_attachment bäddar in bytes som en filbilaga på dokumentnivå, skriven till PDF:ens /Names /EmbeddedFiles namntree vid sparande, tillsammans med en valfri MIME-typ, beskrivning och skapande-/ändringsdatum. Document.embedded_files läser tillbaka varje bilaga som en typad FileSpecification (name, contents, mime_type, description, size), och Document.get_embedded_file söker upp en efter namn. FileSpecification.save() skriver de återvunna bytes till disk.
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")
Typsnittsupptäckt och inbäddning
FontRepository samlar typsnittskällor och löser upp typsnitt efter namn i hela dokumentet. FontRepository.add_source() registrerar en FontSource såsom FolderFontSource (skannar en katalog, eventuellt rekursivt); FontRepository.find_font() och search() löser sedan upp ett typsnitt efter familj, fullständigt eller PostScript namn, med fallback till standard-typsnittregistret. Varje matchning är en FontDescriptor, som kan skickas direkt till Page.add_text för att bädda in och delmängda typsnittet. FontRegistry mappar vanliga icke-standardnamn (Arial, Times New Roman och liknande) till deras närmaste Standard-14 motsvarighet via search_font_by_name().
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")
Dokumentöversikter och bokmärken
Document.outlines returnerar en OutlineCollection, den översta behållaren för en PDFs bokmärkesträd. OutlineCollection.add lägger till ett toppnivå-OutlineItem; OutlineItem.add() nästar ett underbokmärke under ett befintligt. Varje OutlineItem bär en title, ett mål-page_index, och is_bold/is_italic visningsflaggor, och exponerar sin egen children-lista.
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")
Snabbstart
Installera paketet och bygg sedan ett dokument som kombinerar ett bokmärke, dokumentmetadata och en bilaga i ett enda skript.
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])
Stödda format
| Format | Filändelse | Läs | Skriv |
|---|---|---|---|
| Ja | Ja | ||
| TIFF | tiff | - | Ja |
Page.render, Page.save_as_image och Document.save_page_as_image producerar också PNG rasterutmatning tillsammans med TIFF.
Detta är sidrasteriseringsutdata snarare än dokumentläsningsformat.
Öppen källkod & licensiering
Aspose.PDF FOSS för Python släpps under MIT-licensen: inga användningsrestriktioner, inga körningsavgifter och inga registreringskrav för kommersiell eller personlig användning. Källkoden är hostad på github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, och paketet publiceras på PyPI som aspose-pdf-foss-for-python.
