مقدمه
Aspose.PDF FOSS برای Python بر کلاس Document متمرکز است که pages، form، outlines، tagged_content و attachments را به عنوان نقاط ورود برای ویرایش ساختاری و سطوح سندی افشا میکند. فراتر از افزودن محتوای صفحه، کتابخانه عملیاتهایی را پوشش میدهد که یک PDF را به یک artefact کامل و قابل توزیع تبدیل میکند: فیلدهای فرم تعاملی که دادههای ساختاریافته را جمعآوری و نمایش میدهند، پیوستهای فایل در سطح سند، کشف و جاسازی قلم برای نگارش متن، و درخت نشانک برای ناوبری. هر یک از این حوزهها خطاها را از طریق یک سلسله مراتب استثنا واحد که ریشه در AsposePdfException دارد، ایجاد میکند، بنابراین فراخوانندگان میتوانند شکستهای خاص بسته را بدون حدس زدن انواع استثنا بهصورت ماژول به ماژول بگیرند.
این راهنما نشان میدهد چگونه با آن سطح مدیریت سند کار کنیم: گرفتن و تمایز زیرکلاسهای AsposePdfException، ایجاد و خواندن فیلدهای AcroForm با Form و Field، جاسازی و بازیابی پیوستها از طریق FileSpecification، حل قلمها با FontRepository و FontRegistry، و ساخت درخت نشانک با OutlineCollection و OutlineItem. هر بخش فقط از کلاسها و متدهای موجود در بستهٔ جاری استفاده میکند.
Aspose.PDF FOSS برای Python یک بستهٔ Python است، aspose-pdf-foss-for-python، که تحت مجوز MIT منتشر شده و نیاز به Python نسخهٔ ۳.۱۱ یا بالاتر دارد. نام ماژول سطح بالای آن 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() فیلدهای انتهایی جدیدی ایجاد میکنند که به صفحه و مستطیل ویجت مرتبط هستند و هر کدام یک 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 بایتها را بهعنوان یک پیوست فایل در سطح سند جاسازی میکند که هنگام ذخیرهسازی در درخت نام /Names /EmbeddedFiles PDF نوشته میشود، بههمراه یک نوع MIME اختیاری، توضیح، و تاریخهای ایجاد/تغییر. Document.embedded_files هر پیوست را بهعنوان یک FileSpecification تایپشده ( name، contents، mime_type، description، size ) میخواند و Document.get_embedded_file بر اساس نام یکی را جستجو میکند. FileSpecification.save() بایتهای بازیابیشده را روی دیسک مینویسد.
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 و مشابه) را از طریق search_font_by_name() به نزدیکترین معادل Standard-14 نقشه میکند.
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")
شروع سریع
پکیج را نصب کنید، سپس سندی بسازید که یک نشانک، متادیتای سند، و یک پیوست را در یک اسکریپت ترکیب میکند.
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])
فرمتهای پشتیبانیشده
| فرمت | پسوند | خواندن | نوشتن |
|---|---|---|---|
| بله | بله | ||
| TIFF | tiff | - | بله |
Page.render، Page.save_as_image و Document.save_page_as_image همچنین خروجی رستر PNG را همراه با TIFF تولید میکنند.
اینها خروجیهای رسترسازی صفحه هستند نه فرمتهای بارگذاری سند.
منبع باز و مجوزدهی
Aspose.PDF FOSS برای Python تحت مجوز MIT منتشر شده است: بدون محدودیت استفاده، بدون هزینههای زمان اجرا، و بدون نیاز به ثبتنام برای استفاده تجاری یا شخصی. کد منبع در github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python میزبانی میشود، و پکیج در PyPI به عنوان aspose-pdf-foss-for-python منتشر شده است.
