Úvod
Aspose.PDF FOSS pro Python se soustředí na třídu Document, která zpřístupňuje pages, form, outlines, tagged_content a attachments jako vstupní body pro strukturální a dokumentové úpravy. Kromě přidávání obsahu stránek knihovna pokrývá operace, které dělají z PDF kompletní, distribuovatelný artefakt: interaktivní formulářová pole, která sbírají a zveřejňují strukturovaná data, souborové přílohy na úrovni dokumentu, vyhledávání písem a jejich vkládání pro tvorbu textu a strom záložek pro navigaci. Každá z těchto oblastí vyhazuje chyby prostřednictvím jediné hierarchie výjimek zakořeněné v AsposePdfException, takže volající mohou zachytit chyby specifické pro balíček, aniž by hádali typy výjimek modul po modulu.
Tento průvodce ukazuje, jak pracovat s tímto rozhraním pro správu dokumentů: zachytávat a rozlišovat podtřídy AsposePdfException, vytvářet a číst pole AcroForm pomocí Form a Field, vkládat a obnovovat přílohy prostřednictvím FileSpecification, řešit písma pomocí FontRepository a FontRegistry a vytvářet strom záložek pomocí OutlineCollection a OutlineItem. Každá sekce používá pouze třídy a metody dostupné v aktuálním balíčku.
Aspose.PDF FOSS pro Python je balíček Python, aspose-pdf-foss-for-python, vydaný pod licencí MIT, vyžadující Python 3.11 nebo novější. Název jeho modulů na nejvyšší úrovni je aspose_pdf. Jádrový balíček závisí jen na cryptography a asn1crypto; volitelné rozšíření přidávají dekódování obrazů založené na Pillow, podporu písem WOFF2 založenou na Brotli a složité rozvržení textu založené na HarfBuzz.
Klíčové funkce
Zpracování výjimek s AsposePdfException
Každá chyba specifická pro balíček v Aspose.PDF FOSS pro Python pochází z AsposePdfException. Většina selhání při zpracování dokumentů spadá pod její podtřídu PdfException, která je zase základem pro PdfParseException (špatně formovaný vstup), PdfSecurityException (selhání šifrování a hesla, včetně InvalidPasswordException) a PdfValidationException (strukturální nebo shodové selhání). Zachycení AsposePdfException jako poslední, po specifických podtřídách, umožňuje volajícímu reagovat odlišně na špatné heslo než na poškozený soubor, přičemž stále existuje jediné záložní řešení pro všechny ostatní výjimky, které balíček může vyvolat.
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
Interaktivní pole formuláře
Document.form vrací Form fasádu nad AcroForm polí dokumentu. Form.add_text_field(), add_checkbox() a add_radio_group() vytvářejí nová terminální pole svázaná se stránkou a obdélníkem widgetu, přičemž každé vrací Field. Field zpřístupňuje name, value a field_type, aby mohla být existující pole prohlížena a aktualizována podle názvu, a Field.remove() pole zcela odstraní.
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")
Vnořené soubory a přílohy
Document.add_attachment vkládá bajty jako souborovou přílohu na úrovni dokumentu, která je při uložení zapsána do stromu názvů /Names /EmbeddedFiles PDF, spolu s volitelným MIME typem, popisem a daty vytvoření/úpravy. Document.embedded_files načte každou přílohu zpět jako typovaný FileSpecification (name, contents, mime_type, description, size) a Document.get_embedded_file vyhledá jednu podle názvu. FileSpecification.save() zapíše získané bajty na 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")
Objevování a vkládání fontů
FontRepository agreguje zdroje fontů a řeší fonty podle názvu napříč dokumentem. FontRepository.add_source() registruje FontSource, například FolderFontSource (prohledává adresář, volitelně rekurzivně); FontRepository.find_font() a search() pak řeší font podle rodiny, úplného nebo PostScript názvu, s návratem na registr standardních fontů. Každá shoda je FontDescriptor, kterou lze předat přímo do Page.add_text pro vložení a podmnožinu fontu. FontRegistry mapuje běžné nestandardní názvy (Arial, Times New Roman a podobně) na jejich nejbližší ekvivalent ze Standard-14 pomocí 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")
Obrysy dokumentu a záložky
Document.outlines vrací OutlineCollection, nejvyšší úroveň kontejneru pro strom záložek PDF. OutlineCollection.add přidá nejvyšší úroveň OutlineItem; OutlineItem.add() vnoří podřízenou záložku pod existující. Každý OutlineItem nese title, cílový page_index a zobrazovací příznaky is_bold / is_italic, a zpřístupňuje svůj vlastní seznam children.
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")
Rychlý start
Nainstalujte balíček a poté vytvořte dokument, který kombinuje záložku, metadata dokumentu a přílohu v jediném skriptu.
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])
Podporované formáty
| Formát | Přípona | Číst | Zapsat |
|---|---|---|---|
| Ano | Ano | ||
| TIFF | tiff | - | Ano |
Page.render, Page.save_as_image a Document.save_page_as_image také produkují rastrový výstup PNG vedle TIFF.
Jedná se o výstupy rasterizace stránek, nikoli o formáty pro načítání dokumentů.
Open Source a licencování
Aspose.PDF FOSS pro Python je vydán pod licencí MIT: žádná omezení užívání, žádné poplatky za běh a žádné požadavky na registraci pro komerční ani osobní použití. Zdrojový kód je umístěn na github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python a balíček je publikován na PyPI jako aspose-pdf-foss-for-python.
