Introduzione
Aspose.PDF FOSS per Python si concentra sulla classe Document, che espone pages, form, outlines, tagged_content e attachments come punti di ingresso per la modifica strutturale a livello di documento. Oltre ad aggiungere contenuto alle pagine, la libreria copre le operazioni che rendono un PDF un artefatto completo e distribuibile: campi modulo interattivi che raccolgono ed espongono dati strutturati, allegati di file a livello di documento, scoperta e incorporamento di font per la creazione di testo, e un albero di segnalibri per la navigazione. Ognuna di queste aree genera errori attraverso una singola gerarchia di eccezioni radicata in AsposePdfException, così i chiamanti possono intercettare i fallimenti specifici del pacchetto senza indovinare i tipi di eccezione modulo per modulo.
Questa guida mostra come lavorare con quella superficie di gestione dei documenti: intercettare e distinguere le sottoclassi di AsposePdfException, creare e leggere i campi AcroForm con Form e Field, incorporare e recuperare gli allegati tramite FileSpecification, risolvere i font con FontRepository e FontRegistry, e costruire un albero di segnalibri con OutlineCollection e OutlineItem. Ogni sezione utilizza solo le classi e i metodi presenti nel pacchetto corrente.
Aspose.PDF FOSS per Python è un pacchetto Python, aspose-pdf-foss-for-python, rilasciato sotto licenza MIT, che richiede Python 3.11 o successivo. Il suo nome di modulo di livello superiore è aspose_pdf. Il pacchetto core dipende solo da cryptography e asn1crypto; gli extra opzionali aggiungono la decodifica di immagini basata su Pillow, il supporto ai font WOFF2 basato su Brotli e il layout di testo complesso basato su HarfBuzz.
Caratteristiche principali
Gestione delle eccezioni con AsposePdfException
Tutti gli errori specifici del pacchetto in Aspose.PDF FOSS per Python derivano da AsposePdfException. La maggior parte dei fallimenti nell’elaborazione dei documenti ricade nella sua sottoclasse PdfException, che a sua volta è la base per PdfParseException (input non valido), PdfSecurityException (errori di crittografia e password, inclusi InvalidPasswordException), e PdfValidationException (errori strutturali o di conformità). Intercettare AsposePdfException per ultimo, dopo le sottoclassi più specifiche, permette al chiamante di reagire diversamente a una password errata rispetto a un file corrotto, mantenendo comunque un unico fallback per tutto il resto che il pacchetto può sollevare.
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
Campi Modulo Interattivi
Document.form restituisce una facciata Form sui campi AcroForm del documento. Form.add_text_field(), add_checkbox() e add_radio_group() creano nuovi campi terminali collegati a una pagina e a un rettangolo widget, ciascuno restituendo un Field. Field espone name, value e field_type così che i campi esistenti possano essere ispezionati e aggiornati per nome, e Field.remove() elimina un campo completamente.
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")
File Incorporati e Allegati
Document.add_attachment incorpora byte come allegato file a livello di documento, scritto nell’albero dei nomi /Names /EmbeddedFiles del PDF al salvataggio, insieme a un tipo MIME opzionale, una descrizione e le date di creazione/modifica. Document.embedded_files legge ogni allegato restituendolo come un FileSpecification tipizzato (name, contents, mime_type, description, size), e Document.get_embedded_file ne cerca uno per nome. FileSpecification.save() scrive i byte recuperati su disco.
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")
Scoperta e Incorporamento dei Font
FontRepository aggrega le font sorgenti e risolve i font per nome attraverso il documento. FontRepository.add_source() registra un FontSource come FolderFontSource (scansiona una directory, opzionalmente in modo ricorsivo); FontRepository.find_font() e search() risolvono poi un font per famiglia, completo o nome PostScript, ricadendo nel registro dei font standard. Ogni corrispondenza è un FontDescriptor, che può essere passato direttamente a Page.add_text per incorporare e sottoinsieme il font. FontRegistry mappa i nomi non standard comuni (Arial, Times New Roman e simili) al loro equivalente Standard-14 più vicino tramite 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")
Sommari del Documento e Segnalibri
Document.outlines restituisce un OutlineCollection, il contenitore di livello superiore per l’albero dei segnalibri di un PDF. OutlineCollection.add aggiunge un OutlineItem di livello superiore; OutlineItem.add() annida un segnalibro figlio sotto uno esistente. Ogni OutlineItem contiene un title, un page_index di destinazione, e flag di visualizzazione is_bold / is_italic, e espone la propria lista di 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")
Avvio rapido
Installa il pacchetto, quindi crea un documento che combina un segnalibro, i metadati del documento e un allegato in un unico script.
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])
Formati supportati
| Formato | Estensione | Leggi | Scrivi |
|---|---|---|---|
| Sì | Sì | ||
| TIFF | tiff | - | Sì |
Page.render, Page.save_as_image e Document.save_page_as_image producono anche output raster PNG accanto a TIFF.
Si tratta di output di rasterizzazione di pagina piuttosto che di formati di caricamento del documento.
Open Source e licenze
Aspose.PDF FOSS per Python è rilasciato sotto licenza MIT: nessuna restrizione d’uso, nessuna tariffa di runtime e nessun requisito di registrazione per utilizzo commerciale o personale. Il codice sorgente è ospitato su github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, e il pacchetto è pubblicato su PyPI come aspose-pdf-foss-for-python.
