Pendahuluan
Aspose.PDF FOSS untuk Python berfokus pada kelas Document, yang mengekspos pages, form, outlines, tagged_content, dan attachments sebagai titik masuk untuk penyuntingan struktural dan tingkat dokumen. Selain menambahkan konten halaman, pustaka ini mencakup operasi yang menjadikan PDF sebuah artefak lengkap yang dapat didistribusikan: bidang formulir interaktif yang mengumpulkan dan menampilkan data terstruktur, lampiran file tingkat dokumen, penemuan dan penyematan font untuk penulisan teks, serta pohon bookmark untuk navigasi. Setiap area ini menghasilkan kesalahan melalui satu hierarki pengecualian yang berakar pada AsposePdfException, sehingga pemanggil dapat menangkap kegagalan khusus paket tanpa menebak tipe pengecualian modul demi modul.
Panduan ini menunjukkan cara bekerja dengan antarmuka manajemen dokumen tersebut: menangkap dan membedakan subclass AsposePdfException, membuat dan membaca bidang AcroForm dengan Form dan Field, menyematkan dan memulihkan lampiran melalui FileSpecification, menyelesaikan font dengan FontRepository dan FontRegistry, serta membangun pohon bookmark dengan OutlineCollection dan OutlineItem. Setiap bagian hanya menggunakan kelas dan metode yang ada dalam paket saat ini.
Aspose.PDF FOSS untuk Python adalah paket Python, aspose-pdf-foss-for-python, dirilis di bawah lisensi MIT, memerlukan Python 3.11 atau lebih baru. Nama modul tingkat atasnya adalah aspose_pdf. Paket inti hanya bergantung pada cryptography dan asn1crypto; tambahan opsional menambahkan decoding gambar berbasis Pillow, dukungan font WOFF2 berbasis Brotli, dan tata letak teks kompleks berbasis HarfBuzz.
Fitur Utama
Penanganan Pengecualian dengan AsposePdfException
Setiap kesalahan khusus paket dalam Aspose.PDF FOSS untuk Python diturunkan dari AsposePdfException. Kebanyakan kegagalan pemrosesan dokumen berada di bawah subclass PdfException, yang pada gilirannya menjadi dasar untuk PdfParseException (input yang tidak terbentuk dengan benar), PdfSecurityException (kegagalan enkripsi dan kata sandi, termasuk InvalidPasswordException), dan PdfValidationException (kegagalan struktural atau kepatuhan). Menangkap AsposePdfException terakhir, setelah subclass yang lebih spesifik, memungkinkan pemanggil bereaksi berbeda terhadap kata sandi yang salah dibandingkan dengan file yang rusak sekaligus tetap memiliki satu cadangan untuk semua kesalahan lain yang dapat dihasilkan paket.
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
Bidang Form Interaktif
Document.form mengembalikan sebuah Form facade di atas bidang AcroForm dokumen. Form.add_text_field(), add_checkbox(), dan add_radio_group() membuat bidang terminal baru yang terkait dengan sebuah halaman dan persegi widget, masing-masing mengembalikan sebuah Field. Field mengekspos name, value, dan field_type sehingga bidang yang ada dapat diperiksa dan diperbarui berdasarkan nama, dan Field.remove() menghapus sebuah bidang sepenuhnya.
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 Tertanam dan Lampiran
Document.add_attachment menyematkan byte sebagai lampiran file tingkat dokumen, ditulis ke pohon nama /Names /EmbeddedFiles PDF saat disimpan, bersama dengan tipe MIME opsional, deskripsi, dan tanggal pembuatan/modifikasi. Document.embedded_files membaca setiap lampiran kembali sebagai FileSpecification bertipe (name, contents, mime_type, description, size), dan Document.get_embedded_file mencari satu berdasarkan nama. FileSpecification.save() menulis byte yang dipulihkan ke 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")
Penemuan dan Penyematan Font
FontRepository mengumpulkan sumber font dan menyelesaikan font berdasarkan nama di seluruh dokumen. FontRepository.add_source() mendaftarkan sebuah FontSource seperti FolderFontSource (memindai direktori, secara opsional secara rekursif); FontRepository.find_font() dan search() kemudian menyelesaikan sebuah font berdasarkan keluarga, lengkap, atau nama PostScript, kembali ke registri font standar bila diperlukan. Setiap kecocokan adalah sebuah FontDescriptor, yang dapat diteruskan langsung ke Page.add_text untuk menyematkan dan memotong font. FontRegistry memetakan nama non-standar umum (Arial, Times New Roman, dan serupa) ke ekuivalen Standard-14 terdekat melalui 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")
Garis Besar Dokumen dan Penanda Buku
Document.outlines mengembalikan sebuah OutlineCollection, kontainer tingkat atas untuk pohon penanda buku PDF. OutlineCollection.add menambahkan sebuah OutlineItem tingkat atas; OutlineItem.add() menempatkan penanda buku anak di bawah yang sudah ada. Setiap OutlineItem membawa sebuah title, sebuah page_index target, dan flag tampilan is_bold / is_italic, serta mengekspos daftar children miliknya.
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")
Panduan Cepat
Instal paket, lalu buat dokumen yang menggabungkan bookmark, metadata dokumen, dan lampiran dalam satu skrip.
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])
Format yang Didukung
| Format | Ekstensi | Baca | Tulis |
|---|---|---|---|
| Ya | Ya | ||
| TIFF | tiff | - | Ya |
Page.render, Page.save_as_image, dan Document.save_page_as_image juga menghasilkan output raster PNG bersamaan dengan TIFF.
Ini adalah output rasterisasi halaman, bukan format pemuatan dokumen.
Sumber Terbuka & Lisensi
Aspose.PDF FOSS untuk Python dirilis di bawah lisensi MIT: tidak ada pembatasan penggunaan, tidak ada biaya runtime, dan tidak ada persyaratan pendaftaran untuk penggunaan komersial atau pribadi. Kode sumber dihosting di github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, dan paket dipublikasikan di PyPI sebagai aspose-pdf-foss-for-python.
