مقدمة
Aspose.PDF FOSS لـ Python هي مكتبة مفتوحة المصدر جديدة للعمل مع مستندات PDF من شفرة Python. تم إصدارها تحت رخصة MIT ومُنفذة بالكامل بـ Python — محلل PDF، الكاتب، مُرصّص الصفحات، وروتينات التشفير هي جزء من الحزمة نفسها، مع اعتماديات مطلوبة محدودة إلى cryptography وasn1crypto. الإضافات الاختيارية تضيف دعم الصور المستند إلى Pillow، وفك تشفير الخطوط WOFF2 المستند إلى Brotli، و HarfBuzz لتشكيل النص المعقد.
المكتبة منظمة حول الفئة Document، التي تقوم بتحميل PDF من مسار أو بايتات أو تدفق ثنائي وتكشف عن صفحاته عبر document.pages، وهو PageCollection يدعم التكرار والفهرسة والتقطيع. من هناك، يغطي API إضافة النصوص والصور إلى الصفحات، قراءة وتعديل التعليقات التوضيحية، إنشاء وتعبئة حقول AcroForm، تشفير وفك تشفير المستندات، واستخراج النص والمرفقات — العمليات اللازمة لإنشاء ملفات PDF جديدة أو العمل مع الملفات الموجودة.
هذا الإصدار موجه للمطورين الذين يحتاجون إلى معالجة PDF داخل قاعدة شفرة Python دون رخصة تجارية: توليد التقارير والفواتير، خطوط أنابيب استيعاب المستندات، أتمتة ملء النماذج، والخدمات التي تحتاج إلى تحويل صفحات PDF إلى صور أو استخراج النص للفهرسة اللاحقة. المشروع حالياً في مرحلة ألفا، لذا قد تتطور واجهات برمجة التطبيقات وتغطية الميزات قبل الإصدار المستقر الأول. يتطلب Python 3.11 أو أحدث.
ما الذي يتضمنه
إنشاء المستندات وتحميلها
PdfDocument() ينشئ PDF فارغ؛ PdfDocument(source, password=..., limits=...) يحمل ملفًا موجودًا من مسار أو بايتات خام أو تدفق ثنائي، وهو مكافئ لاستدعاء PdfDocument().load_from(source, ...). كلاهما يرفع استثناءً عند ملف مفقود أو بيانات غير‑PDF أو كلمة مرور مفقودة بدلاً من إرجاع مستند فارغ. PdfDocument هو مدير سياق، لذا يتم تحرير الموارد تلقائيًا عندما يخرج كتلة 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 أو Unicode مدمج في موضع x/y مع font_size معين؛ يمكن أن يكون معامل font إما FontDescriptor، أو بايتات الخط الخام، أو مسارًا إلى خط TrueType/OpenType لـ Unicode خارج ترميزات Standard‑14. Page.add_image يضع كائن صورة XObject بصيغة raw أو 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 هو أيضًا مدير سياق.
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}")
الصيغ المدعومة
| تنسيق | امتداد | قراءة | كتابة |
|---|---|---|---|
| ✓ | ✓ | ||
| 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. تسمح الرخصة بالاستخدام التجاري، والتعديل، وإعادة التوزيع دون اتفاقية منفصلة.
