Quản lý tài liệu

Quản lý Tài liệu

Lớp Document là điểm vào cho hầu hết mọi thao tác trong Aspose.PDF FOSS cho Python: tạo một PDF mới, tải một PDF đã tồn tại, chỉnh sửa các trang của nó, và ghi kết quả ra. Hướng dẫn này sẽ đi qua vòng đời tài liệu, các thao tác với bộ sưu tập trang, tối ưu hoá, quy trình làm việc đa tệp, mã hoá, và các ngoại lệ mà bạn nên chuẩn bị xử lý.

Vòng đời Tài liệu: Tạo, Mở và Lưu

Document() không có đối số sẽ tạo một tài liệu rỗng trong bộ nhớ. Cung cấp một đường dẫn tệp, bytes thô, hoặc bất kỳ luồng nhị phân có thể đọc nào làm đối số đầu tiên (hoặc gọi load_from() một cách rõ ràng) để tải một PDF đã tồn tại thay thế. save() chấp nhận một đường dẫn hoặc một luồng nhị phân có thể ghi như io.BytesIO.

from aspose_pdf import Document

# Create a new, empty document and add a blank page
doc = Document()
doc.pages.add()
doc.save("hello.pdf")

# Re-open it — a path, bytes, or a binary stream all work
reopened = Document("hello.pdf")
print(reopened.page_count)   # 1

# ...or load explicitly onto an existing instance
another = Document()
another.load_from("hello.pdf")

reopened.close()
another.dispose()
doc.dispose()

save() ném FileExistsError nếu đường dẫn đích đã tồn tại, trừ khi bạn truyền overwrite=True. close() là một bí danh của dispose(); cả hai đều idempotent, vì vậy gọi chúng nhiều lần là an toàn.

Chỉ PDF được triển khai như mục tiêu lưu — đây là chức năng cốt lõi, hoạt động đầy đủ của thư viện. Truyền một giá trị xuất như SaveFormat.PPTX hoặc DocFormat.HTML vào save() sẽ ném UnsupportedFeatureException thay vì ghi một tệp bị gán nhãn sai, vì vậy việc xuất không thành công luôn được thông báo rõ ràng thay vì im lặng.

Quản lý Bộ sưu tập Trang

doc.pages là một PageCollection. Nó hỗ trợ len(), vòng lặp, và chỉ mục bắt đầu từ 0 (doc.pages[0]), cộng thêm add(), insert(index, page), và delete(index) để chỉnh sửa cấu trúc. Mỗi Page cung cấp index, rect (cái MediaBox), và rotation.

from aspose_pdf import Document

doc = Document()
doc.pages.add()            # page 0
doc.pages.add()            # page 1
doc.pages.insert(1, None)  # insert a blank page at index 1

print(doc.page_count)      # 3

first_page = doc.pages[0]
print(first_page.rect)     # (0, 0, 612, 792)

for page in doc.pages:
    print(page.index, page.rotation)

doc.pages.delete(1)        # remove the page we inserted
doc.save("pages_demo.pdf", overwrite=True)

pages.add(page=None) thêm một trang trống khi được gọi mà không có đối số. pages.insert() giới hạn một chỉ mục ngoài phạm vi tới vị trí hợp lệ gần nhất thay vì ném ngoại lệ.

Tối ưu hoá và Nén Tài liệu

Document.optimize thực hiện việc loại trừ trùng lặp ảnh/luồng, thu gom rác đối tượng không dùng, và nén luồng trong một lần gọi. Cung cấp một thể hiện OptimizationOptions để kiểm soát các kỹ thuật nào sẽ chạy; bỏ qua nó để sử dụng hồ sơ dọn dẹp tiêu chuẩn.

from aspose_pdf import Document, OptimizationOptions

doc = Document("large_report.pdf")

options = OptimizationOptions()
options.remove_unused_objects = True
options.link_duplicate_streams = True
options.image_compression_quality = 60
options.subset_fonts = True

doc.optimize(options)
doc.save("large_report_optimized.pdf", overwrite=True)

optimize_resources() là một bí danh của optimize(). Nếu bạn chỉ muốn nén luồng mà không có bước dọn dẹp cấu trúc, hãy gọi doc.compress_streams() trực tiếp.

Ghép, Tách và Chỉnh sửa Tệp

Đối với các tài liệu mà bạn đã mở, Document.merge() sẽ thêm các thể hiện Document khác vào tài liệu hiện tại:

from aspose_pdf import Document

base = Document("part1.pdf")
extra = Document("part2.pdf")

base.merge(extra)
base.save("combined.pdf", overwrite=True)

Đối với quy trình làm việc file-to-file mà không cần tự mở một Document, các plugin Merger và Splitter ít mã sẽ nhận một đối tượng MergeOptions/SplitOptions được xây dựng từ các đầu vào và đầu ra FileDataSource:

from aspose_pdf import Merger, MergeOptions, Splitter, SplitOptions, FileDataSource

# Merge two files into one
merge_options = MergeOptions()
merge_options.add_input(FileDataSource("part1.pdf"))
merge_options.add_input(FileDataSource("part2.pdf"))
merge_options.add_output(FileDataSource("combined.pdf"))
Merger().process(merge_options)

# Split the result into one file per page
split_options = SplitOptions()
split_options.add_input(FileDataSource("combined.pdf"))
split_options.add_output(FileDataSource("combined_page1.pdf"))
split_options.add_output(FileDataSource("combined_page2.pdf"))
Splitter().process(split_options)

PdfFileEditor cung cấp cùng một nhóm các thao tác như một façade trả về True/False thay vì ném lỗi, điều này tiện lợi cho các script batch:

from aspose_pdf import PdfFileEditor

with PdfFileEditor() as editor:
    ok = editor.concatenate(["part1.pdf", "part2.pdf"], "combined.pdf")
    if not ok:
        print("concatenate failed:", editor.last_exception)

    editor.extract("combined.pdf", "first_page_only.pdf", page_from=1, page_to=1)

PdfFileEditor.extract() and .insert() take cơ sở 1 số trang, không giống như PageCollectioncó chỉ mục bắt đầu từ 0 — xem Các vấn đề thường gặp bên dưới.

Mã hoá và Bảo mật Tài liệu

Document.encrypt(user_password, owner_password=None, permissions=-4) mã hoá tài liệu trong bộ nhớ; decrypt(password) và change_passwords(old, new_user, new_owner=None) đảo ngược hoặc thay đổi mật khẩu. is_encrypted và permissions báo cáo trạng thái hiện tại.

from aspose_pdf import Document
from aspose_pdf.exceptions import PdfSecurityException

doc = Document()
doc.pages.add()
doc.encrypt("user-pass", "owner-pass", permissions=-4)
doc.save("secured.pdf", overwrite=True)

try:
    Document("secured.pdf", password="wrong-pass")
except PdfSecurityException as exc:
    print("could not open:", exc)

reopened = Document("secured.pdf", password="user-pass")
print(reopened.is_encrypted)   # True
reopened.decrypt("user-pass")
reopened.save("unsecured.pdf", overwrite=True)

Mở một tài liệu đã mã hoá mà không có mật khẩu, hoặc mật khẩu sai, sẽ ném ra PdfSecurityException — bắt lớp này (từ aspose_pdf.exceptions) thay vì giả định việc tải luôn thành công.

Siêu dữ liệu, Xác thực và Xử lý Ngoại lệ

Siêu dữ liệu tài liệu nằm trên doc.info (một dict[str, str] đơn giản), và doc.version / doc.id hiển thị phiên bản tiêu đề PDF và định danh tệp trailer. validate() (được đặt tên khác là check()) báo cáo tính toàn vẹn cấu trúc; repair() cố gắng sửa các vấn đề phổ biến như danh sách trang thiếu hoặc MediaBox nằm ngoài phạm vi.

from aspose_pdf import Document, PdfLoadLimits
from aspose_pdf.exceptions import AsposePdfException, PdfIOException

doc = Document()
doc.pages.add()
doc.info["Title"] = "Quarterly Report"
doc.info["Author"] = "Reporting Bot"
doc.save("report.pdf", overwrite=True)

# Load untrusted input under an explicit resource-limit policy
safe_limits = PdfLoadLimits(max_input_bytes=50 * 1024 * 1024, max_pages=1000)

try:
    untrusted = Document("incoming.pdf", limits=safe_limits)
    if not untrusted.validate():
        untrusted.repair()
except (AsposePdfException, PdfIOException) as exc:
    print("failed to process incoming.pdf:", exc)

PdfLoadLimits giới hạn bộ nhớ và số lượng đối tượng cho các tệp không đáng tin; gọi PdfLoadLimits.unlimited() để tắt mọi giới hạn khi bạn hoàn toàn tin tưởng nguồn. AsposePdfException là lớp cơ sở cho toàn bộ cây hierarchy ngoại lệ (bao gồm PdfIOException và PdfSecurityException), vì vậy một except AsposePdfException duy nhất sẽ bắt bất kỳ lỗi nào do thư viện ném ra.

Mẹo và Thực hành Tốt nhất

• Luôn gọi dispose() (hoặc close()) trên một Document khi bạn hoàn thành, hoặc sử dụng nó như một biến cục bộ ngắn hạn — engine giữ nội dung trang đã giải mã và hình ảnh trong bộ nhớ cho đến khi giải phóng.
• Truyền overwrite=True cho save() khi ghi lại một đường dẫn mà bạn đã tạo trong cùng một lần chạy; mặc định là False và sẽ ném ra FileExistsError.
• Ưu tiên doc.optimize() trước khi phát hành PDF đã tạo — nó là một lời gọi duy nhất loại bỏ các đối tượng không dùng và nén các luồng, thường làm giảm kích thước đầu ra đáng kể.
• Đặt chính sách PdfLoadLimits một cách rõ ràng mỗi khi bạn tải PDF từ nguồn không tin cậy (tải lên, tệp đính kèm email, thu thập web); các giá trị mặc định là rộng rãi nhưng có giới hạn, không phải là ranh giới bảo mật mà bạn nên phụ thuộc một cách mù quáng.
• Bắt AsposePdfException (hoặc một lớp con cụ thể như PdfSecurityException) quanh các lời gọi load/save thay vì bắt Exception thuần — nó là lớp cơ sở chung cho mọi lỗi mà thư viện ném ra.

Các vấn đề thường gặp

FAQ

Tôi có cần giấy phép để sử dụng Aspose.PDF FOSS cho Python không?

Không. Đây là phiên bản mã nguồn mở (được cấp phép MIT); không có tệp giấy phép hoặc bước kích hoạt nào cần cấu hình.

Tôi có thể xuất Document sang các định dạng khác ngoài PDF không?

Không có trong phiên bản này. save() chỉ hỗ trợ xuất PDF — việc truyền một giá trị SaveFormat/DocFormat khác sẽ gây ra UnsupportedFeatureException thay vì tạo ra một tệp bị gán nhãn sai.

Sự khác nhau giữa Document.merge() và plugin Merger là gì?

Document.merge() kết hợp các thể hiện Document mà bạn đã mở trong bộ nhớ. Merger (với MergeOptions và FileDataSource) là một lớp bao tiện lợi dạng file-to-file, mở, hợp nhất và lưu cho bạn trong một lần gọi — hữu ích cho các script batch đơn giản không bao giờ cần đối tượng Document trung gian.

Tại sao pages.insert() không bao giờ ném lỗi khi chỉ mục vượt quá phạm vi?

PageCollection.insert() giới hạn chỉ mục vào phạm vi hợp lệ (giá trị âm trở thành 0, các giá trị vượt quá cuối cùng trở thành len(doc.pages)) thay vì ném lỗi, do đó việc chèn sẽ không bao giờ thất bại chỉ vì giá trị chỉ mục.

Làm thế nào để tôi tải một tệp PDF một cách an toàn từ nguồn không tin cậy?

Tạo một PdfLoadLimits với các giới hạn rõ ràng (max_input_bytes, max_pages, max_objects, v.v.) và truyền nó như đối số limits= cho Document(...) hoặc load_from(). Mỗi trường đã có giá trị mặc định hữu hạn, nhưng việc thu hẹp chúng theo kích thước đầu vào mong đợi của bạn sẽ giảm tài nguyên mà một tệp bị sai định dạng có thể tiêu tốn.

API Reference Tóm tắt

Xem thêm

• API Reference: Tài liệu đầy đủ cho lớp và phương thức của aspose_pdf
• Cơ sở Kiến thức: Hướng dẫn cách thực hiện theo nhiệm vụ
• Tổng quan sản phẩm: Tóm tắt tính năng và khả năng
• Bắt đầu / Cài đặt: cài đặt và cấu hình
• Aspose.PDF for Python — Enterprise Documentation