Belge Yönetimi

Belge Yönetimi

Document sınıfı, Aspose.PDF FOSS for Python içinde neredeyse her işlem için giriş noktasıdır: yeni bir PDF oluşturma, mevcut bir PDF’yi yükleme, sayfalarını düzenleme ve sonucu geri yazma. Bu kılavuz, belge yaşam döngüsü, sayfa koleksiyonu işlemleri, optimizasyon, çok dosyalı iş akışları, şifreleme ve beklemeniz gereken istisnalar üzerinden ilerler.

Belge Yaşam Döngüsü: Oluştur, Aç ve Kaydet

Document() hiçbir argüman olmadan boş, bellek içi bir belge oluşturur. Bir dosya yolu, ham bytes veya herhangi bir okunabilir ikili akışı ilk argüman olarak geçirin (veya load_from()‘yi açıkça çağırın) böylece mevcut bir PDF’yi yükleyebilirsiniz. save() bir yol veya io.BytesIO gibi yazılabilir bir ikili akışı kabul eder.

from aspose_pdf import Document

# Create a new, empty document and add a blank page
doc = Document()
doc.pages.add()
doc.save("hello.pdf")

# Re-open it — a path, bytes, or a binary stream all work
reopened = Document("hello.pdf")
print(reopened.page_count)   # 1

# ...or load explicitly onto an existing instance
another = Document()
another.load_from("hello.pdf")

reopened.close()
another.dispose()
doc.dispose()

save(), hedef yol zaten mevcutsa FileExistsError hatasını yükseltir, overwrite=True‘yi geçmezseniz. close(), dispose() için bir takma addır; ikisi de idempotenttir, bu yüzden birden fazla kez çağırmak güvenlidir.

Kaydetme hedefi olarak yalnızca PDF uygulanmıştır — bu, kütüphanenin çekirdeği, tamamen çalışan işlevdir. save()‘ye SaveFormat.PPTX veya DocFormat.HTML gibi bir dışa aktarma değeri geçirmek, dosyayı yanlış etiketlemek yerine UnsupportedFeatureException hatasını yükseltir, bu yüzden başarısız bir dışa aktarma her zaman sessiz kalmaz, sesli bir hata verir.

Sayfa Koleksiyonunu Yönetme

doc.pages bir PageCollection. len(), yineleme ve 0 tabanlı indeksleme (doc.pages[0]) destekler, ayrıca yapısal düzenlemeler için add(), insert(index, page) ve delete(index) sunar. Her Page index, rect (MediaBox) ve rotation sağlar.

from aspose_pdf import Document

doc = Document()
doc.pages.add()            # page 0
doc.pages.add()            # page 1
doc.pages.insert(1, None)  # insert a blank page at index 1

print(doc.page_count)      # 3

first_page = doc.pages[0]
print(first_page.rect)     # (0, 0, 612, 792)

for page in doc.pages:
    print(page.index, page.rotation)

doc.pages.delete(1)        # remove the page we inserted
doc.save("pages_demo.pdf", overwrite=True)

pages.add(page=None), argüman verilmeden çağrıldığında boş bir sayfa ekler. pages.insert(), geçersiz bir indeksi yükseltmek yerine en yakın geçerli konuma sınırlar.

Belgeleri Optimize Etme ve Sıkıştırma

Document.optimize, tek bir çağrıda görüntü/akış deduplikasyonu, kullanılmayan nesne çöp toplama ve akış sıkıştırması gerçekleştirir. Hangi tekniklerin çalışacağını kontrol etmek için bir OptimizationOptions örneği geçirin; standart temizlik profilini kullanmak için atlayın.

from aspose_pdf import Document, OptimizationOptions

doc = Document("large_report.pdf")

options = OptimizationOptions()
options.remove_unused_objects = True
options.link_duplicate_streams = True
options.image_compression_quality = 60
options.subset_fonts = True

doc.optimize(options)
doc.save("large_report_optimized.pdf", overwrite=True)

optimize_resources(), optimize() için bir takma addır. Yalnızca yapısal temizlik aşaması olmadan akış sıkıştırması istiyorsanız, doc.compress_streams()‘yi doğrudan çağırın.

Dosyaları Birleştirme, Bölme ve Düzenleme

Zaten açık olan belgeler için, Document.merge() diğer Document örneklerini mevcut belgeye ekler:

from aspose_pdf import Document

base = Document("part1.pdf")
extra = Document("part2.pdf")

base.merge(extra)
base.save("combined.pdf", overwrite=True)

Kendi başınıza bir Document açmadan dosyadan dosyaya iş akışları için, düşük kodlu Merger ve Splitter eklentileri, FileDataSource girdileri ve çıktılarından oluşturulan bir MergeOptions/SplitOptions nesnesi alır:

from aspose_pdf import Merger, MergeOptions, Splitter, SplitOptions, FileDataSource

# Merge two files into one
merge_options = MergeOptions()
merge_options.add_input(FileDataSource("part1.pdf"))
merge_options.add_input(FileDataSource("part2.pdf"))
merge_options.add_output(FileDataSource("combined.pdf"))
Merger().process(merge_options)

# Split the result into one file per page
split_options = SplitOptions()
split_options.add_input(FileDataSource("combined.pdf"))
split_options.add_output(FileDataSource("combined_page1.pdf"))
split_options.add_output(FileDataSource("combined_page2.pdf"))
Splitter().process(split_options)

PdfFileEditor, yükseltmek yerine True/False döndüren bir facade gibi aynı işlem ailesini sunar, bu da toplu betikler için uygundur:

from aspose_pdf import PdfFileEditor

with PdfFileEditor() as editor:
    ok = editor.concatenate(["part1.pdf", "part2.pdf"], "combined.pdf")
    if not ok:
        print("concatenate failed:", editor.last_exception)

    editor.extract("combined.pdf", "first_page_only.pdf", page_from=1, page_to=1)

PdfFileEditor.extract() and .insert() take 1 tabanlı sayfa numaraları, farklı olarak PageCollection’s 0 tabanlı indeksleme — bkz Yaygın Sorunlar aşağıda.

Şifreleme ve Belge Güvenliği

Document.encrypt(user_password, owner_password=None, permissions=-4), bellek içindeki belgeyi şifreler; decrypt(password) ve change_passwords(old, new_user, new_owner=None) şifreleri tersine çevirir veya döndürür. is_encrypted ve permissions, mevcut durumu rapor eder.

from aspose_pdf import Document
from aspose_pdf.exceptions import PdfSecurityException

doc = Document()
doc.pages.add()
doc.encrypt("user-pass", "owner-pass", permissions=-4)
doc.save("secured.pdf", overwrite=True)

try:
    Document("secured.pdf", password="wrong-pass")
except PdfSecurityException as exc:
    print("could not open:", exc)

reopened = Document("secured.pdf", password="user-pass")
print(reopened.is_encrypted)   # True
reopened.decrypt("user-pass")
reopened.save("unsecured.pdf", overwrite=True)

Şifreli bir belgeyi şifresiz ya da yanlış şifreyle açmak PdfSecurityException hatasını yükseltir — yüklemenin her zaman başarılı olacağını varsaymak yerine bu sınıfı ( aspose_pdf.exceptions‘den) yakalayın.

Üst Veri, Doğrulama ve İstisna İşleme

Belge üst verileri doc.info üzerinde bulunur (düz bir dict[str, str]), ve doc.version / doc.id PDF başlık sürümünü ve trailer dosya tanımlayıcısını ortaya çıkarır. validate() (check() olarak takma adlandırılmıştır) yapısal bütünlüğü rapor eder; repair() eksik sayfa listesi veya kapsam dışı MediaBox gibi yaygın sorunları düzeltmeye çalışır.

from aspose_pdf import Document, PdfLoadLimits
from aspose_pdf.exceptions import AsposePdfException, PdfIOException

doc = Document()
doc.pages.add()
doc.info["Title"] = "Quarterly Report"
doc.info["Author"] = "Reporting Bot"
doc.save("report.pdf", overwrite=True)

# Load untrusted input under an explicit resource-limit policy
safe_limits = PdfLoadLimits(max_input_bytes=50 * 1024 * 1024, max_pages=1000)

try:
    untrusted = Document("incoming.pdf", limits=safe_limits)
    if not untrusted.validate():
        untrusted.repair()
except (AsposePdfException, PdfIOException) as exc:
    print("failed to process incoming.pdf:", exc)

PdfLoadLimits, güvenilmeyen dosyalar için bellek ve nesne sayılarını sınırlar; kaynağa tamamen güvendiğinizde tüm limitleri devre dışı bırakmak için PdfLoadLimits.unlimited()‘i çağırın. AsposePdfException, tüm istisna hiyerarşisinin temel sınıfıdır ( PdfIOException ve PdfSecurityException dahil), bu yüzden tek bir except AsposePdfException kütüphane tarafından yükseltilen herhangi bir hatayı yakalar.

İpuçları ve En İyi Uygulamalar

• İşiniz bittiğinde bir Document üzerinde her zaman dispose() (veya close()) çağırın, ya da onu kısa ömürlü bir yerel değişken olarak kullanın — motor, çözülen sayfa içeriğini ve görselleri atılana kadar bellekte tutar.
• Aynı çalıştırmada zaten oluşturduğunuz bir yolu yeniden yazarken overwrite=True‘ı save()‘a geçirin; varsayılan False‘dir ve FileExistsError hatasını tetikler.
• Oluşturulan bir PDF’i dağıtmadan önce doc.optimize()‘ı tercih edin — bu, kullanılmayan nesneleri kaldıran ve akışları sıkıştıran tek bir çağrıdır ve genellikle çıktı boyutunu belirgin şekilde küçültür.
• Güvenilmeyen bir kaynaktan (yüklemeler, e-posta ekleri, web kazıma) PDF yüklediğiniz her seferde bir PdfLoadLimits politikasını açıkça belirleyin; varsayılanlar cömert ama sınırlıdır, körü körüne güvenmeniz gereken bir güvenlik sınırı değildir.
• Yükleme/kaydetme çağrıları etrafında çıplak Exception yerine AsposePdfException‘ı (veya PdfSecurityException gibi belirli bir alt sınıfı) yakalayın — bu, kütüphanenin yükselttiği her hatanın ortak temelidir.

Yaygın Sorunlar

FAQ

Aspose.PDF FOSS’ı Python için kullanmak için bir lisansa ihtiyacım var mı?

Hayır. Bu, açık kaynak (MIT lisanslı) sürümdür; yapılandırmak için bir lisans dosyası veya etkinleştirme adımı yoktur.

Document‘ı PDF dışındaki formatlara dışa aktarabilir miyim?

Bu sürümde değil. save() yalnızca PDF çıktısını uygular — başka bir SaveFormat/DocFormat değeri geçmek, dosyayı yanlış etiketlemek yerine UnsupportedFeatureException hatası oluşturur.

Document.merge() ile Merger eklentisi arasındaki fark nedir?

Document.merge(), bellekte zaten açık olan Document örneklerini birleştirir. Merger (MergeOptions ve FileDataSource ile birlikte), bir dosyadan diğerine kolaylık sağlayan bir sarmalayıcıdır; tek bir çağrıda açar, birleştirir ve kaydeder — ara Document nesnesine hiç ihtiyaç duymayan basit toplu komut dosyaları için kullanışlıdır.

pages.insert() neden aralık dışı bir indeks için asla hata vermez?

PageCollection.insert(), hataya yol açmak yerine indeksi geçerli aralığa sınırlamaktadır (negatif değerler 0 olur, sondan sonraki değerler len(doc.pages) olur), bu yüzden bir ekleme yalnızca indeks değerinden dolayı asla başarısız olmaz.

Güvenilmeyen bir kaynaktan PDF’i güvenli bir şekilde nasıl yüklerim?

Açık sınırlarla (max_input_bytes, max_pages, max_objects vb.) bir PdfLoadLimits oluşturun ve bunu Document(...) veya load_from()‘e limits= argümanı olarak iletin. Her alan zaten sonlu bir değere varsayılan, ancak bunları beklenen giriş boyutunuza göre sıkılaştırmak, hatalı bir dosyanın tüketebileceği kaynakları azaltır.

API Reference Özeti

Ayrıca Bakınız

• API Reference: Tam sınıf ve metod belgeleri için aspose_pdf
• Bilgi Tabanı: Görev odaklı nasıl yapılır kılavuzları
• Ürün Genel Bakışı: Özellikler ve yeteneklerin özeti
• Başlarken / Kurulum: kurulum ve yapılandırma
• Aspose.PDF for Python — Enterprise Documentation