Introduction
Aspose.PDF FOSS pour Python se concentre sur la classe Document, qui expose pages, form, outlines, tagged_content et attachments comme points d’entrée pour l’édition structurelle et au niveau du document. Au-delà de l’ajout de contenu de page, la bibliothèque couvre les opérations qui font d’un PDF un artefact complet et distribuable: des champs de formulaire interactifs qui collectent et exposent des données structurées, des pièces jointes de fichiers au niveau du document, la découverte et l’incorporation de polices pour la rédaction de texte, et un arbre de signets pour la navigation. Chacune de ces zones génère des erreurs via une hiérarchie d’exceptions unique enracinée dans AsposePdfException, de sorte que les appelants puissent intercepter les échecs spécifiques au paquet sans deviner les types d’exceptions module par module.
Ce guide montre comment travailler avec cette interface de gestion de documents: intercepter et distinguer les sous-classes de AsposePdfException, créer et lire les champs AcroForm avec Form et Field, incorporer et récupérer les pièces jointes via FileSpecification, résoudre les polices avec FontRepository et FontRegistry, et construire un arbre de signets avec OutlineCollection et OutlineItem. Chaque section n’utilise que les classes et méthodes présentes dans le paquet actuel.
Aspose.PDF FOSS pour Python est un paquet Python, aspose-pdf-foss-for-python, publié sous licence MIT, nécessitant Python 3.11 ou ultérieur. Son nom de module de niveau supérieur est aspose_pdf. Le paquet principal ne dépend que de cryptography et asn1crypto; des options supplémentaires ajoutent le décodage d’images basé sur Pillow, la prise en charge des polices WOFF2 basée sur Brotli, et la mise en forme de texte complexe basée sur HarfBuzz.
Fonctionnalités clés
Gestion des exceptions avec AsposePdfException
Chaque erreur spécifique au paquet dans Aspose.PDF FOSS pour Python dérive de AsposePdfException. La plupart des échecs de traitement de documents relèvent de sa sous-classe PdfException, qui à son tour constitue la base pour PdfParseException (entrée mal formée), PdfSecurityException (échecs de chiffrement et de mot de passe, y compris InvalidPasswordException), et PdfValidationException (échecs structurels ou de conformité). Intercepter AsposePdfException en dernier, après les sous-classes plus spécifiques, permet à l’appelant de réagir différemment à un mot de passe incorrect qu’à un fichier corrompu tout en conservant un seul recours pour tout le reste que le paquet peut lever.
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
Champs de formulaire interactifs
Document.form renvoie une façade Form sur les champs AcroForm du document. Form.add_text_field(), add_checkbox() et add_radio_group() créent de nouveaux champs terminaux liés à une page et à un rectangle de widget, chacun renvoyant un Field. Field expose name, value et field_type afin que les champs existants puissent être inspectés et mis à jour par nom, et Field.remove() supprime un champ entièrement.
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")
Fichiers intégrés et pièces jointes
Document.add_attachment intègre des octets comme une pièce jointe de fichier au niveau du document, écrite dans l’arbre de noms /Names /EmbeddedFiles du PDF lors de l’enregistrement, avec un type MIME facultatif, une description et des dates de création/modification. Document.embedded_files lit chaque pièce jointe en tant que FileSpecification typé (name, contents, mime_type, description, size), et Document.get_embedded_file en recherche une par son nom. FileSpecification.save() écrit les octets récupérés sur le disque.
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")
Découverte et intégration de polices
FontRepository agrège les sources de polices et résout les polices par nom dans tout le document. FontRepository.add_source() enregistre un FontSource tel que FolderFontSource (analyse un répertoire, éventuellement de façon récursive) ; FontRepository.find_font() et search() résolvent ensuite une police par famille, nom complet ou nom PostScript, en revenant au registre des polices standard si nécessaire. Chaque correspondance est un FontDescriptor, qui peut être passé directement à Page.add_text pour intégrer et sous-ensempler la police. FontRegistry associe les noms non standard courants (Arial, Times New Roman et similaires) à leur équivalent Standard-14 le plus proche 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")
Structure du document et signets
Document.outlines renvoie un OutlineCollection, le conteneur de niveau supérieur de l’arbre des signets d’un PDF. OutlineCollection.add ajoute un OutlineItem de niveau supérieur ; OutlineItem.add() imbrique un signet enfant sous un existant. Chaque OutlineItem possède un title, une cible page_index, et des indicateurs d’affichage is_bold / is_italic, et expose sa propre liste 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")
Démarrage rapide
Installez le paquet, puis créez un document qui combine un signet, les métadonnées du document et une pièce jointe dans un seul 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])
Formats pris en charge
| Format | Extension | Lire | Écrire |
|---|---|---|---|
| Oui | Oui | ||
| TIFF | tiff | - | Oui |
Page.render, Page.save_as_image et Document.save_page_as_image produisent également une sortie raster PNG en plus du TIFF.
Il s’agit de sorties de rasterisation de pages plutôt que de formats de chargement de document.
Open Source & Licence
Aspose.PDF FOSS pour Python est publié sous la licence MIT : aucune restriction d’utilisation, aucun frais d’exécution, et aucune exigence d’enregistrement pour une utilisation commerciale ou personnelle. Le code source est hébergé sur github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, et le paquet est publié sur PyPI sous le nom aspose-pdf-foss-for-python.
