Giriş
Aspose.PDF FOSS, Python için, Document sınıfı etrafında odaklanır; bu sınıf pages, form, outlines, tagged_content ve attachments öğelerini yapısal, belge-seviyesinde düzenleme için giriş noktaları olarak sunar. Sayfa içeriği eklemenin ötesinde, kütüphane bir PDF’yi tam ve dağıtılabilir bir eser haline getiren işlemleri kapsar: yapılandırılmış verileri toplayan ve ortaya çıkaran etkileşimli form alanları, belge-seviyesinde dosya ekleri, metin oluşturma için yazı tipi keşfi ve gömme, ve gezinme için bir yer imi ağacı. Bu alanların her biri, AsposePdfException kökenli tek bir istisna hiyerarşisi üzerinden hatalar üretir, böylece çağırıcılar paket-özel hataları, modül modu tahmin etmeden yakalayabilir.
Bu kılavuz, bu belge-yönetimi yüzeyiyle nasıl çalışılacağını gösterir: AsposePdfException alt sınıflarını yakalama ve ayırt etme, Form ve Field ile AcroForm alanlarını oluşturma ve okuma, FileSpecification üzerinden ekleri gömme ve geri alma, FontRepository ve FontRegistry ile yazı tiplerini çözümleme ve OutlineCollection ve OutlineItem ile bir yer imi ağacı oluşturma. Her bölüm yalnızca geçerli pakette bulunan sınıfları ve metodları kullanır.
Aspose.PDF FOSS, Python için bir Python paketidir, aspose-pdf-foss-for-python, MIT lisansı altında yayınlanmıştır ve Python 3.11 veya daha yenisini gerektirir. Üst-seviye modül adı aspose_pdf‘dir. Çekirdek paket yalnızca cryptography ve asn1crypto‘e bağımlıdır; isteğe bağlı ekler Pillow tabanlı görüntü çözümleme, Brotli tabanlı WOFF2 yazı tipi desteği ve HarfBuzz tabanlı karmaşık metin yerleşimi ekler.
Ana Özellikler
İstisna İşleme AsposePdfException ile
Her paket-özel hata, Python için Aspose.PDF FOSS’de, AsposePdfException‘dan türetilir. Çoğu belge-işleme hatası, onun PdfException alt sınıfı altında yer alır; bu sınıf da sırasıyla PdfParseException (hatalı giriş), PdfSecurityException (şifreleme ve parola hataları, InvalidPasswordException dahil) ve PdfValidationException (yapısal veya uyumluluk hataları) için temel oluşturur. Daha spesifik alt sınıflardan sonra AsposePdfException‘yı en son yakalamak, çağırıcının hatalı bir parolaya karşı bozuk bir dosyadan farklı şekilde tepki vermesini sağlar ve paket tarafından yükseltilebilecek diğer tüm hatalar için tek bir geri dönüş noktasına sahip olur.
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
Etkileşimli Form Alanları
Document.form belge’nin AcroForm alanları üzerinde bir Form kılıfı döndürür. Form.add_text_field(), add_checkbox() ve add_radio_group() bir sayfaya ve bir widget dikdörtgenine bağlanan yeni uç alanlar oluşturur, her biri bir Field döndürür. Field, mevcut alanların adlarıyla incelenebilmesi ve güncellenebilmesi için name, value ve field_type‘u ortaya çıkarır ve Field.remove() bir alanı tamamen siler.
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")
Gömülü Dosyalar ve Ekler
Document.add_attachment baytları belge düzeyinde bir dosya eki olarak gömer, kaydedilirken PDF’nin /Names /EmbeddedFiles ad ağacına yazılır, isteğe bağlı bir MIME türü, açıklama ve oluşturma/değiştirme tarihleri ile birlikte. Document.embedded_files her eki tiplenmiş bir FileSpecification (name, contents, mime_type, description, size) olarak geri okur ve Document.get_embedded_file isme göre birini bulur. FileSpecification.save() kurtarılan baytları diske yazar.
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")
Yazı Tipi Keşfi ve Gömülmesi
FontRepository yazı tipi kaynaklarını toplar ve belge boyunca isimle yazı tiplerini çözer. FontRepository.add_source() FontSource gibi bir FolderFontSource kaydeder (bir dizini tarar, isteğe bağlı olarak yinelemeli); FontRepository.find_font() ve search() ardından bir yazı tipini aile, tam veya PostScript ismiyle çözer, standart-yazı tipi kayıt defterine geri döner. Her eşleşme bir FontDescriptor‘dır, doğrudan Page.add_text‘e aktarılabilir ve yazı tipi gömülüp alt kümesi oluşturulabilir. FontRegistry, yaygın olmayan adları (Arial, Times New Roman ve benzerlerini) en yakın Standard-14 eşdeğeriyle search_font_by_name() aracılığıyla eşleştirir.
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")
Belge Taslakları ve Yer İmleri
Document.outlines bir OutlineCollection döndürür, PDF’nin yer imi ağacının üst düzey kapsayıcısı. OutlineCollection.add üst düzey bir OutlineItem ekler; OutlineItem.add() mevcut birinin altına bir alt yer imi yerleştirir. Her OutlineItem bir title, bir hedef page_index ve is_bold / is_italic görüntüleme bayrakları taşır ve kendi children listesini ortaya çıkarır.
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")
Hızlı Başlangıç
Paketi kurun, ardından bir işaretçi, belge meta verileri ve bir eki tek bir betikte birleştiren bir belge oluşturun.
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
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])
Desteklenen Biçimler
| Biçim | Uzantı | Oku | Yaz |
|---|---|---|---|
| Evet | Evet | ||
| TIFF | tiff | - | Evet |
Page.render, Page.save_as_image ve Document.save_page_as_image ayrıca TIFF’in yanında PNG raster çıktısı da üretir.
Bunlar belge-yükleme biçimleri değil, sayfa rasterleştirme çıktılarıdır.
Açık Kaynak & Lisanslama
Aspose.PDF FOSS for Python MIT lisansı altında yayınlanmıştır: kullanım kısıtlaması yok, çalışma zamanı ücreti yok ve ticari ya da kişisel kullanım için kayıt gereksinimi yoktur. Kaynak kodu github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python adresinde barındırılmaktadır ve paket PyPI üzerinde aspose-pdf-foss-for-python olarak yayımlanmıştır.
