Εισαγωγή
Aspose.PDF FOSS για Python εστιάζει στην κλάση Document, η οποία εκθέτει τα pages, form, outlines, tagged_content και attachments ως σημεία εισόδου για δομική, επεξεργασία επιπέδου εγγράφου. Πέρα από την προσθήκη περιεχομένου σελίδας, η βιβλιοθήκη καλύπτει τις λειτουργίες που κάνουν ένα PDF ένα πλήρες, διανέψιμο αντικείμενο: διαδραστικά πεδία φόρμας που συλλέγουν και εκθέτουν δομημένα δεδομένα, συνημμένα αρχείων επιπέδου εγγράφου, εντοπισμό και ενσωμάτωση γραμματοσειρών για συγγραφή κειμένου, και ένα δέντρο σελιδοδεικτών για πλοήγηση. Κάθε ένα από αυτά τα πεδία προκαλεί σφάλματα μέσω μιας ενιαίας ιεραρχίας εξαιρέσεων που ριζώνεται στο AsposePdfException, ώστε οι καλούντες να μπορούν να συλλάβουν σφάλματα ειδικά για το πακέτο χωρίς να μαντεύουν τύπους εξαιρέσεων ανά μονάδα.
Αυτός ο οδηγός δείχνει πώς να εργάζεστε με αυτήν την επιφάνεια διαχείρισης εγγράφων: σύλληψη και διάκριση των υποκατηγοριών AsposePdfException, δημιουργία και ανάγνωση πεδίων AcroForm με Form και Field, ενσωμάτωση και ανάκτηση συνημμένων μέσω FileSpecification, επίλυση γραμματοσειρών με FontRepository και FontRegistry, και δημιουργία δέντρου σελιδοδεικτών με OutlineCollection και OutlineItem. Κάθε ενότητα χρησιμοποιεί μόνο τις κλάσεις και τις μεθόδους που υπάρχουν στο τρέχον πακέτο.
Aspose.PDF FOSS για Python είναι ένα πακέτο Python, aspose-pdf-foss-for-python, κυκλοφορεί υπό την άδεια MIT, απαιτώντας Python 3.11 ή νεότερη έκδοση. Το όνομα του ανώτερου επιπέδου ενότητας είναι aspose_pdf. Το βασικό πακέτο εξαρτάται μόνο από τα cryptography και asn1crypto; προαιρετικά πρόσθετα προσθέτουν αποκωδικοποίηση εικόνας με βάση το Pillow, υποστήριξη γραμματοσειρών WOFF2 με βάση το Brotli, και διάταξη σύνθετου κειμένου με βάση το HarfBuzz.
Κύρια Χαρακτηριστικά
Διαχείριση Εξαίρεσεων με AsposePdfException
Κάθε σφάλμα ειδικό για το πακέτο στο Aspose.PDF FOSS για Python προέρχεται από το AsposePdfException. Οι περισσότερες αποτυχίες επεξεργασίας εγγράφων ανήκουν στην υποκατηγορία PdfException του, η οποία με τη σειρά της είναι η βάση για τα PdfParseException (κακοδιαμορφωμένη είσοδος), PdfSecurityException (αποτυχίες κρυπτογράφησης και κωδικού πρόσβασης, συμπεριλαμβανομένου του InvalidPasswordException), και PdfValidationException (δομικές ή συμμορφωτικές αποτυχίες). Η σύλληψη του AsposePdfException τελευταία, μετά τις πιο συγκεκριμένες υποκατηγορίες, επιτρέπει σε έναν καλούντα να αντιδρά διαφορετικά σε έναν εσφαλμένο κωδικό πρόσβασης από ό,τι σε ένα κατεστραμμένο αρχείο, ενώ διατηρεί μια ενιαία εναλλακτική λύση για όλα τα υπόλοιπα σφάλματα που μπορεί να εγείρει το πακέτο.
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
Διαδραστικά Πεδία Φορμών
Document.form επιστρέφει μια Form προσέκταση πάνω από τα AcroForm πεδία του εγγράφου. Form.add_text_field(), add_checkbox() και add_radio_group() δημιουργούν νέα τερματικά πεδία συνδεδεμένα με μια σελίδα και ένα ορθογώνιο widget, το καθένα επιστρέφει μια Field. Field εκθέτει name, value και field_type ώστε τα υπάρχοντα πεδία να μπορούν να ελεγχθούν και να ενημερωθούν κατά όνομα, και Field.remove() διαγράφει ένα πεδίο εντελώς.
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")
Ενσωματωμένα Αρχεία και Συνημμένα
Document.add_attachment ενσωματώνει bytes ως συνημμένο αρχείο επιπέδου εγγράφου, καταχωρημένο στο /Names /EmbeddedFiles δέντρο ονομάτων του PDF κατά την αποθήκευση, μαζί με προαιρετικό τύπο MIME, περιγραφή και ημερομηνίες δημιουργίας/τροποποίησης. Document.embedded_files διαβάζει κάθε συνημμένο ως έναν τυποποιημένο FileSpecification (name, contents, mime_type, description, size), και Document.get_embedded_file εντοπίζει ένα κατά όνομα. FileSpecification.save() γράφει τα επανακτημένα bytes στο δίσκο.
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")
Ανακάλυψη και Ενσωμάτωση Γραμματοσειρών
FontRepository συγκεντρώνει πηγές γραμματοσειρών και επιλύει γραμματοσειρές κατά όνομα σε όλο το έγγραφο. FontRepository.add_source() καταχωρεί ένα FontSource όπως το FolderFontSource (σαρώσει έναν κατάλογο, προαιρετικά επαναληπτικά); FontRepository.find_font() και search() στη συνέχεια επιλύουν μια γραμματοσειρά κατά οικογένεια, πλήρες ή PostScript όνομα, επαναφέροντας στο μητρώο τυπικών γραμματοσειρών. Κάθε αντιστοιχία είναι ένα FontDescriptor, το οποίο μπορεί να περαστεί άμεσα στο Page.add_text για ενσωμάτωση και υποσυνολο της γραμματοσειράς. FontRegistry χαρτογραφεί κοινά μη-τυπικά ονόματα (Arial, Times New Roman και παρόμοια) στο πιο κοντινό ισοδύναμο Standard-14 μέσω του 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")
Περιγράμματα Εγγράφου και Σελιδοδείκτες
Document.outlines επιστρέφει ένα OutlineCollection, το κορυφαίο δοχείο για το δέντρο σελιδοδεικτών ενός PDF. OutlineCollection.add προσθέτει έναν κορυφαίο OutlineItem; OutlineItem.add() ενσωματώνει ένα παιδικό σελιδοδείκτη κάτω από έναν υπάρχοντα. Κάθε OutlineItem περιέχει ένα title, έναν στόχο page_index, και σημαίες εμφάνισης is_bold / is_italic, και εκθέτει τη δική του λίστα 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")
Γρήγορη Εκκίνηση
Εγκαταστήστε το πακέτο, έπειτα δημιουργήστε ένα έγγραφο που συνδυάζει σελιδοδείκτη, μεταδεδομένα εγγράφου και συνημμένο σε ένα ενιαίο script.
git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .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])
Υποστηριζόμενες Μορφές
| Μορφή | Επέκταση | Ανάγνωση | Εγγραφή |
|---|---|---|---|
| Ναι | Ναι | ||
| TIFF | tiff | - | Ναι |
Page.render, Page.save_as_image και Document.save_page_as_image επίσης παράγουν raster έξοδο PNG παράλληλα με TIFF.
Αυτά είναι έξοδοι rasterization σελίδας αντί για μορφές φόρτωσης εγγράφου.
Ανοιχτός Κώδικας & Άδεια
Aspose.PDF FOSS για Python κυκλοφορεί υπό την άδεια MIT: χωρίς περιορισμούς χρήσης, χωρίς χρεώσεις χρόνου εκτέλεσης και χωρίς απαιτήσεις εγγραφής για εμπορική ή προσωπική χρήση. Ο πηγαίος κώδικας φιλοξενείται στο github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, και το πακέτο δημοσιεύεται στο PyPI ως aspose-pdf-foss-for-python.
