Giới thiệu
Aspose.PDF FOSS cho Python tập trung vào lớp Document, lớp này cung cấp pages, form, outlines, tagged_content và attachments như các điểm vào cho việc chỉnh sửa cấu trúc và mức tài liệu. Ngoài việc thêm nội dung trang, thư viện còn bao phủ các thao tác khiến một PDF trở thành một artefact hoàn chỉnh, có thể phân phối: các trường biểu mẫu tương tác thu thập và hiển thị dữ liệu có cấu trúc, các tệp đính kèm ở mức tài liệu, việc khám phá và nhúng phông chữ cho việc soạn thảo văn bản, và một cây dấu trang để điều hướng. Mỗi một trong những khu vực này phát sinh lỗi thông qua một hệ thống ngoại lệ duy nhất có gốc tại AsposePdfException, để các bên gọi có thể bắt các lỗi đặc thù của gói mà không phải đoán loại ngoại lệ từng module.
Hướng dẫn này chỉ ra cách làm việc với bề mặt quản lý tài liệu đó: bắt và phân biệt các lớp con của AsposePdfException, tạo và đọc các trường AcroForm bằng Form và Field, nhúng và khôi phục các tệp đính kèm qua FileSpecification, giải quyết phông chữ với FontRepository và FontRegistry, và xây dựng cây dấu trang bằng OutlineCollection và OutlineItem. Mỗi phần chỉ sử dụng các lớp và phương thức có trong gói hiện tại.
Aspose.PDF FOSS cho Python là một gói Python, aspose-pdf-foss-for-python, được phát hành dưới giấy phép MIT, yêu cầu Python 3.11 trở lên. Tên mô-đun cấp cao nhất của nó là aspose_pdf. Gói lõi chỉ phụ thuộc vào cryptography và asn1crypto; các phần mở rộng tùy chọn bổ sung khả năng giải mã hình ảnh dựa trên Pillow, hỗ trợ phông chữ WOFF2 dựa trên Brotli, và bố cục văn bản phức tạp dựa trên HarfBuzz.
Các tính năng chính
Xử lý ngoại lệ với AsposePdfException
Mọi lỗi đặc thù của gói trong Aspose.PDF FOSS cho Python đều kế thừa từ AsposePdfException. Hầu hết các thất bại trong xử lý tài liệu thuộc lớp con PdfException của nó, lớp này lại là cơ sở cho PdfParseException (đầu vào sai định dạng), PdfSecurityException (các lỗi mã hoá và mật khẩu, bao gồm InvalidPasswordException), và PdfValidationException (các lỗi cấu trúc hoặc tuân thủ). Bắt AsposePdfException cuối cùng, sau các lớp con cụ thể hơn, cho phép người gọi phản hồi khác nhau đối với mật khẩu sai so với tệp bị hỏng, trong khi vẫn có một phương án dự phòng duy nhất cho mọi lỗi khác mà gói có thể phát sinh.
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
Trường Biểu Mẫu Tương Tác
Document.form trả về một giao diện Form trên các trường AcroForm của tài liệu. Form.add_text_field(), add_checkbox() và add_radio_group() tạo các trường cuối mới gắn với một trang và một hình chữ nhật widget, mỗi trường trả về một Field. Field cung cấp name, value và field_type để các trường hiện có có thể được kiểm tra và cập nhật theo tên, và Field.remove() xóa một trường hoàn toàn.
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")
Tệp Nhúng và Tệp Đính Kèm
Document.add_attachment nhúng các byte dưới dạng tệp đính kèm cấp tài liệu, được ghi vào cây tên /Names /EmbeddedFiles của PDF khi lưu, cùng với loại MIME tùy chọn, mô tả và ngày tạo/điều chỉnh. Document.embedded_files đọc lại mọi tệp đính kèm dưới dạng FileSpecification có kiểu (name, contents, mime_type, description, size), và Document.get_embedded_file tìm một tệp theo tên. FileSpecification.save() ghi các byte đã khôi phục ra đĩa.
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")
Khám Phá và Nhúng Phông Chữ
FontRepository tổng hợp các nguồn phông chữ và giải quyết phông chữ theo tên trên toàn bộ tài liệu. FontRepository.add_source() đăng ký một FontSource như FolderFontSource (quét một thư mục, tùy chọn đệ quy); FontRepository.find_font() và search() sau đó giải quyết một phông chữ theo họ, đầy đủ, hoặc tên PostScript, quay lại danh sách đăng ký phông chữ tiêu chuẩn nếu cần. Mỗi kết quả khớp là một FontDescriptor, có thể truyền trực tiếp cho Page.add_text để nhúng và tạo tập con cho phông chữ. FontRegistry ánh xạ các tên không chuẩn phổ biến (Arial, Times New Roman và tương tự) sang tương đương Standard-14 gần nhất thông qua 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")
Đề Cương và Dấu Trang
Document.outlines trả về một OutlineCollection, là container cấp cao nhất cho cây dấu trang của PDF. OutlineCollection.add thêm một OutlineItem cấp cao nhất; OutlineItem.add() lồng một dấu trang con dưới một dấu trang hiện có. Mỗi OutlineItem chứa một title, một page_index mục tiêu, và các cờ hiển thị is_bold / is_italic, và cung cấp danh sách children của riêng nó.
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")
Bắt đầu nhanh
Cài đặt gói, sau đó tạo một tài liệu kết hợp dấu trang, siêu dữ liệu tài liệu và tệp đính kèm trong một script duy nhất.
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])
Định dạng được hỗ trợ
| Định dạng | Phần mở rộng | Đọc | Ghi |
|---|---|---|---|
| Có | Có | ||
| TIFF | tiff | - | Có |
Page.render, Page.save_as_image, và Document.save_page_as_image cũng tạo ra đầu ra raster PNG bên cạnh TIFF.
Đây là các đầu ra raster hóa trang chứ không phải các định dạng tải tài liệu.
Mã nguồn mở & Giấy phép
Aspose.PDF FOSS cho Python được phát hành dưới giấy phép MIT: không có hạn chế sử dụng, không có phí chạy, và không yêu cầu đăng ký cho việc sử dụng thương mại hoặc cá nhân. Mã nguồn được lưu trữ tại github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, và gói được xuất bản trên PyPI với tên aspose-pdf-foss-for-python.
