مقدمه

Aspose.PDF FOSS برای Python یک کتابخانه منبع باز جدید برای کار با اسناد PDF از کد Python است. این کتابخانه تحت مجوز MIT منتشر شده و به‌طور کامل با Python پیاده‌سازی شده است — تجزیه‌گر PDF، نویسنده، رسترایزر صفحه و روتین‌های رمزنگاری جزئی از بسته خود هستند، و وابستگی‌های مورد نیاز محدود به cryptography و asn1crypto می‌باشند. افزونه‌های اختیاری پشتیبانی از تصویر مبتنی بر Pillow، رمزگشایی قلم WOFF2 مبتنی بر Brotli، و شکل‌دهی پیچیده متن مبتنی بر HarfBuzz را اضافه می‌کنند.

کتابخانه حول کلاس Document سازماندهی شده است، که PDF را از مسیر، بایت‌ها یا یک جریان باینری بارگذاری می‌کند و صفحات آن را از طریق document.pages، یک PageCollection که از تکرار، ایندکس‌گذاری و برش پشتیبانی می‌کند، در دسترس می‌گذارد. از این نقطه، API شامل افزودن متن و تصویر به صفحات، خواندن و تغییر حاشیه‌نویسی‌ها، ایجاد و پر کردن فیلدهای AcroForm، رمزنگاری و رمزگشایی اسناد، و استخراج متن و پیوست‌ها — عملیات‌های مورد نیاز برای ساخت PDFهای جدید یا کار با PDFهای موجود می‌شود.

این نسخه برای توسعه‌دهندگانی است که نیاز به پردازش PDF درون یک پایه کد Python بدون داشتن مجوز تجاری دارند: تولید گزارش و فاکتور، خطوط لوله‌ی استخراج اسناد، خودکارسازی پر کردن فرم‌ها، و سرویس‌هایی که نیاز به رندر کردن صفحات PDF به تصویر یا استخراج متن برای ایندکس‌گذاری بعدی دارند. پروژه در حال حاضر در مرحله آلفا است، بنابراین APIها و پوشش ویژگی‌ها ممکن است قبل از اولین انتشار پایدار تغییر کنند. Python نسخه 3.11 یا جدیدتر لازم است.

چه چیزهایی شامل می‌شود

ایجاد و بارگذاری سند

PdfDocument() یک PDF خالی ایجاد می‌کند؛ PdfDocument(source, password=..., limits=...) یک PDF موجود را از مسیر، بایت‌های خام یا یک جریان باینری بارگذاری می‌کند و معادل فراخوانی PdfDocument().load_from(source, ...) است. هر دو در صورت عدم وجود فایل، داده‌های غیر‑PDF یا عدم وجود رمز عبور خطا می‌دهند به جای برگرداندن یک سند خالی. PdfDocument یک مدیر زمینه (context manager) است، بنابراین منابع به‌صورت خودکار هنگام خروج از بلوک with آزاد می‌شوند.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text("Generated by Aspose.PDF FOSS", x=72, y=720, font_size=14)
    document.save("report.pdf")

with Document("report.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

افزودن متن و تصاویر

Page.add_text متن Standard‑14 یا یونیکد جاسازی‌شده را در موقعیت x/y با font_size داده شده قرار می‌دهد؛ آرگومان font می‌تواند یک FontDescriptor، بایت‌های خام فونت، یا مسیر به یک فونت TrueType/OpenType برای یونیکد خارج از رمزگذاری‌های Standard‑14 باشد. Page.add_image یک XObject تصویر خام، JPEG یا PNG را در صفحه در موقعیت و اندازه مشخص شده قرار می‌دهد.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Quarterly Summary",
        x=72,
        y=740,
        font_size=16,
    )
    page.add_image(
        "chart.png",
        x=72,
        y=420,
        width=300,
        height=200,
    )
    document.save("summary.pdf")

حاشیه‌نویسی‌ها

هر Page حاشیه‌نویسی‌های خود را از طریق page.annotations، یک AnnotationCollection، در دسترس می‌گذارد. add(subtype, rect, contents, title, appearance_normal, properties) یک حاشیه‌نویسی از زیرنوع استانداردی مانند Square، Circle، Line، Highlight یا FreeText ایجاد و وارد می‌کند و یک Annotation را برمی‌گرداند. فراخوانی generate_appearance() بر روی حاشیه‌نویسی بازگردانده‌شده، یک جریان ظاهر را از هندسه و ویژگی‌های آن ترکیب می‌کند.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    annotation = page.annotations.add(
        "Square",
        (100, 600, 300, 680),
        "Needs review",
        properties={"C": [1, 0, 0]},
    )
    annotation.generate_appearance()
    document.save("annotated.pdf")

فیلدهای فرم

document.form سند Form را برمی‌گرداند که به‌صورت مستقیم فیلدهای AcroForm را ایجاد می‌کند: add_text_field()، add_checkbox()، add_radio_group()، add_list_box()، add_combo_box() و add_push_button() هر کدام یک نام فیلد، یک Page یا اندیس صفحه، و یک مستطیل مکان‌یابی می‌پذیرند و یک Field را برمی‌گردانند. تنظیم field.value مقدار فیلد را به‌روز می‌کند، و form.flatten() ظاهر هر فیلد را در محتوای ثابت صفحه پخت می‌کند.

from aspose_pdf import Document

with Document() as document:
    page = document.pages.add()
    form = document.form
    field = form.add_text_field(
        "customer_name",
        page,
        (72, 700, 300, 720),
    )
    field.value = "Jane Doe"
    form.flatten()
    document.save("form.pdf")

رمزنگاری

Document.encrypt(user_password, owner_password, permissions) سندی را با رمز عبور کاربر، رمز عبور مالک و یک بیت‌ماسک مجوز محافظت می‌کند و همان Document را برای زنجیره‌سازی برمی‌گرداند. Document.decrypt(password) عملیات را معکوس می‌کند و ویژگی is_encrypted وضعیت فعلی را گزارش می‌دهد. بارگذاری مجدد یک سند رمزنگاری‌شده نیاز دارد که password= را به سازنده یا به load_from() پاس بدهید.

from aspose_pdf import Document

with Document("report.pdf") as document:
    document.encrypt(user_password="user-pass", owner_password="owner-pass", permissions=0)
    document.save("encrypted.pdf")

with Document("encrypted.pdf", password="user-pass") as document:
    print(f"Encrypted: {document.is_encrypted}")

استخراج متن

PdfExtractor به منبعی با bind_pdf() متصل می‌شود، سپس extract_text() صفحات سند را مرور می‌کند. get_text() تمام متن استخراج‌شده را یک‌باره برمی‌گرداند، در حالی که has_next_page_text() و get_next_page_text() نتیجه را صفحه به صفحه تکرار می‌کنند. PdfExtractor نیز یک مدیر زمینه (context manager) است.

from aspose_pdf import PdfExtractor

with PdfExtractor() as extractor:
    extractor.bind_pdf("report.pdf")
    extractor.extract_text()
    while extractor.has_next_page_text():
        print(extractor.get_next_page_text())

شروع سریع

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

with Document() as document:
    page = document.pages.add()
    page.add_text(
        "Hello from Aspose.PDF FOSS!",
        x=72,
        y=720,
        font_size=18,
    )
    document.save("hello.pdf")

with Document("hello.pdf") as document:
    print(f"Pages: {document.page_count}")
    print(f"PDF version: {document.version}")

فرمت‌های پشتیبانی‌شده

قالبپسوندخواندننوشتن
PDF.pdf✓✓
PNG.png—✓
TIFF.tiff—✓

PDF فرمت اصلی ورودی و خروجی کتابخانه است که از طریق Document/load_from() خوانده می‌شود و از طریق Document.save نوشته می‌گردد. PNG و TIFF خروجی‌های رندر صفحه هستند که توسط Page.render، Page.save_as_image و Document.save_page_as_image تولید می‌شوند.

منبع باز و مجوزدهی

Aspose.PDF FOSS برای Python تحت مجوز MIT توزیع می‌شود، با منبع کامل در github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python در دسترس است. این مجوز استفاده تجاری، تغییر و توزیع مجدد را بدون نیاز به توافق جداگانه اجازه می‌دهد.

شروع کار

منابع مرتبط