المقدمة
document.py، الوحدة التي تعرف Aspose.PDF FOSS لفئة Document في Python، تصفه كفئة “تغلف محرك PDF الأصلي”. عمليًا، هذا المحرك هو aspose_pdf.engine.simple_pdf.SimplePdf: Document.load_from يبني مثالًا من SimplePdf، وكل عملية على مستوى المستند — الحفظ، التحسين، الإصلاح، التشفير — تُفوض إليه. نفس الأمر ينطبق على العرض: Page.render و Document.render_page كلاهما يستدعيان aspose_pdf.engine.rasterizer.
معظم شفرة التطبيق لا تحتاج أبدًا إلى النظر إلى ما وراء Document و Page. لكن aspose_pdf.engine هي حزمة Python عادية قابلة للاستيراد، والعديد من الأجزاء تحت الواجهة مفيدة بحد ذاتها: أداة التحويل إلى نقطية التي تحول الصفحة إلى بكسلات، ومحولات الترميز لمرشحات التدفق التي تضغط وتفك ضغط تدفقات محتوى PDF، وأدوات التشفير التي تُطبق خوارزميات AES-CBC و RC4 التي يعتمد عليها معالجات أمان PDF. على عكس الحزمة الرئيسية، لا يتم إعادة تصدير الوحدات الفرعية لـ aspose_pdf.engine من المستوى العلوي aspose_pdf — الاستثناء الوحيد هو RasterizedPage، المتصلة عبر aspose_pdf.visualization — لذا يتم استيراد كل شيء أدناه عبر مساره النقطي الكامل، على سبيل المثال from aspose_pdf.engine.filters import StreamDecoder.
Aspose.PDF FOSS لـ Python هي حزمة Python، aspose-pdf-foss-for-python، صادرة بموجب رخصة MIT، وتتطلب Python 3.11 أو أحدث. اسم الوحدة العليا هو aspose_pdf. تعتمد الحزمة الأساسية فقط على cryptography و asn1crypto؛ الإضافات الاختيارية تضيف فك ترميز الصور المستند إلى Pillow، ودعم خطوط WOFF2 المستند إلى Brotli، وتنسيق نص معقد مستند إلى HarfBuzz.
الميزات الرئيسية
عرض الصفحات باستخدام محرك التحويل إلى نقطية
Document.render_page(page_index, dpi=..., scale=..., background=..., antialias=...) ونظيره Page.render كلاهما يُرجع RasterizedPage — مصفوفة RGB مضغوطة ينتجها محول النقاط في المحرك. يُظهر RasterizedPage width، height، وبايتات pixels الخام، بالإضافة إلى get_pixel() للبحث عن بكسل واحد، وto_png() / to_tiff() للبايتات المشفرة في الذاكرة، وsave() لكتابة ملف .png أو ملف .tif/.tiff مباشرة. العمل مع الكائن في الذاكرة — بدلاً من حفظه فقط على القرص — يكون مفيدًا عندما يرغب المتصل في فحص أو تحويل البكسلات قبل اتخاذ قرار بالاحتفاظ بها.
from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
page.add_text("Rendered by the engine", x=72, y=700, font_size=18)
raster = document.render_page(0, dpi=150)
print(raster.width, raster.height)
corner = raster.get_pixel(0, 0)
print("top-left pixel:", corner)
with open("page-0.png", "wb") as handle:
handle.write(raster.to_png())
raster.save("page-0.tiff")
محرك مرشح التدفق
يتم ضغط محتوى PDF وتدفقات الكائنات باستخدام مرشحات مسماة مثل FlateDecode وLZWDecode. يطبق aspose_pdf.engine.filters.StreamEncoder.encode(data, filters, decode_parms=None) وStreamDecoder.decode(data, filters, decode_parms, *, limits=None, max_output_bytes=None) جانب الترميز وفك الترميز من سلسلة المرشحات — نفس codecs التي يستخدمها المحرك داخليًا عندما يكتب ويقرأ تدفقات المستند. كلاهما يقبل اسم مرشح واحد أو قائمة للمرشحات المتسلسلة، وStreamDecoder.decode() يثير PdfValidationException عند اسم مرشح غير معروف بدلاً من إرجاع بايتات خاطئة بصمت.
from aspose_pdf.engine.filters import StreamDecoder, StreamEncoder
raw = b"Sample content-stream payload.\n" * 40
compressed = StreamEncoder.encode(raw, "FlateDecode")
restored = StreamDecoder.decode(compressed, "FlateDecode", None)
assert restored == raw
print(f"{len(raw)} bytes -> {len(compressed)} bytes with FlateDecode")
محرك التشفير
aspose_pdf.engine.encryption.EncryptionUtils هي فئة المرافق ذات الطرق الثابتة التي يستدعيها SimplePdf لكل عملية تتعلق بالتشفير: Document.encrypt، decrypt()، وchange_passwords() جميعها تتحول إلى استدعاءات EncryptionUtils في الخلفية. تنفذ طرقها AES-CBC وتشفير RC4 مباشرةً (encrypt_aes_cbc، decrypt_aes_cbc، encrypt_rc4، decrypt_rc4)، واشتقاق المفتاح لإصدارات معالج الأمان القياسي لـ PDF (compute_owner_key_v4، compute_user_key_v4، compute_user_owner_keys_v6)، وgenerate_file_id() للمعرف العشوائي المكوّن من 16 بايت الذي تحتاجه المستندات الجديدة.
from aspose_pdf.engine.encryption import EncryptionUtils
key = b"0123456789ABCDEF" # 16 bytes -> AES-128
ciphertext = EncryptionUtils.encrypt_aes_cbc(key, b"Reviewer notes: approved")
plaintext = EncryptionUtils.decrypt_aes_cbc(key, ciphertext)
assert plaintext == b"Reviewer notes: approved"
file_id = EncryptionUtils.generate_file_id()
print(file_id.hex())
البدء السريع
قم بتثبيت الحزمة، ثم قم بعرض صفحة مباشرة من طبقة المحرك في سكريبت واحد.
asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.from aspose_pdf import Document
with Document() as document:
page = document.pages.add()
page.add_text("Engine-rendered page", x=72, y=740, font_size=20)
raster = document.render_page(0, dpi=150)
raster.save("engine-render.png")
document.save("engine-quickstart.pdf")
print("Saved engine-quickstart.pdf and engine-render.png")
الصيغ المدعومة
| تنسيق | امتداد | قراءة | كتابة |
|---|---|---|---|
| نعم | نعم | ||
| TIFF | tiff | - | نعم |
قراءة وكتابة ملفات PDF هي Aspose.PDF FOSS للوظيفة الأساسية لـ Python — زوج محرك Document/SimplePdf يقوم بتحميل وكتابة مستندات PDF في كل مسار شفرة في هذه المقالة. Document.render_page، Page.render، وRasterizedPage.to_png() / to_tiff() ينتجون أيضًا مخرجات نقطية PNG وTIFF؛ هذه مخرجات تجسيد صفحات بدلاً من تنسيقات تحميل المستند.
المصدر المفتوح والترخيص
Aspose.PDF FOSS لـ Python صُدر تحت رخصة MIT: لا قيود على الاستخدام، لا رسوم تشغيل، ولا متطلبات تسجيل للاستخدام التجاري أو الشخصي. الكود المصدري مستضاف على github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python، والحزمة منشورة على PyPI باسم aspose-pdf-foss-for-python.
