Správa dokumentů

Správa dokumentů

Třída Document je vstupním bodem pro téměř každou operaci v Aspose.PDF FOSS pro Python: vytvoření nového PDF, načtení existujícího, úpravu jeho stránek a zápis výsledku zpět. Tento průvodce prochází životním cyklem dokumentu, operacemi se sbírkou stránek, optimalizací, workflow s více soubory, šifrováním a výjimkami, které byste měli očekávat.

Životní cyklus dokumentu: vytvoření, otevření a uložení

Document() bez argumentů vytvoří prázdný dokument v paměti. Jako první argument předáte cestu k souboru, surový bytes nebo jakýkoli čitelný binární stream (nebo zavoláte load_from() explicitně), abyste načetli existující PDF. save() přijímá cestu nebo zapisovatelný binární stream, například io.BytesIO.

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() vyvolá FileExistsError, pokud cílová cesta již existuje, pokud nepředáte overwrite=True. close() je alias pro dispose(); oba jsou idempotentní, takže jejich volání více než jednou je bezpečné.

Jako cíl pro uložení je implementováno pouze PDF — to je jádro knihovny, plně funkční. Předání exportní hodnoty, jako je SaveFormat.PPTX nebo DocFormat.HTML, do save() vyvolá UnsupportedFeatureException místo zápisu špatně pojmenovaného souboru, takže neúspěšný export je vždy hlasitý, nikoli tichý.

Správa sbírky stránek

doc.pages je PageCollection. Podporuje len(), iteraci a indexování od nuly (doc.pages[0]), plus add(), insert(index, page) a delete(index) pro strukturální úpravy. Každý Page poskytuje index, rect (to jsou MediaBox) a rotation.

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) přidá prázdnou stránku, když je voláno bez argumentu. pages.insert() omezí index mimo rozsah na nejbližší platnou pozici místo vyvolání chyby.

Optimalizace a komprese dokumentů

Document.optimize provádí deduplikaci obrázků/streamů, sběr odpadků nepoužitých objektů a kompresi streamů v jednom volání. Předajte instanci OptimizationOptions, abyste řídili, které techniky se spustí; vynechejte ji, chcete-li použít standardní profil úklidu.

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() je alias pro optimize(). Pokud chcete jen kompresi streamu bez průchodu strukturálního úklidu, zavolejte přímo doc.compress_streams().

Sloučení, rozdělení a úprava souborů

Pro dokumenty, které již máte otevřené, Document.merge() připojí další instance Document k aktuální.

from aspose_pdf import Document

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

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

Pro workflow typu soubor-na-soubor bez otevření Document sami, pluginy nízkého kódu Merger a Splitter přijímají objekt MergeOptions/SplitOptions vytvořený z vstupů a výstupů FileDataSource:

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 nabízí stejnou rodinu operací jako fasáda, která vrací True/False místo vyvolání výjimky, což je pohodlné pro dávkové skripty:

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 založené na 1 čísla stránek, na rozdíl od PageCollection’s indexování od nuly — viz Časté problémy níže.

Šifrování a zabezpečení dokumentu

Document.encrypt(user_password, owner_password=None, permissions=-4) šifruje dokument v paměti; decrypt(password) a change_passwords(old, new_user, new_owner=None) obracejí nebo otáčejí hesla. is_encrypted a permissions hlásí aktuální stav.

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)

Otevření šifrovaného dokumentu bez hesla nebo se špatným heslem vyvolá PdfSecurityException — zachyťte tuto třídu (z aspose_pdf.exceptions) místo předpokladu, že načtení vždy uspěje.

Metadata, validace a zpracování výjimek

Metadata dokumentu jsou uloženy v doc.info (prostý dict[str, str]) a doc.version / doc.id odhalují verzi PDF hlavičky a identifikátor souboru v traileru. validate() (alias check()) hlásí strukturální integritu; repair() se pokouší opravit běžné problémy, jako je chybějící seznam stránek nebo MediaBox mimo rozsah.

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 omezuje paměť a počty objektů pro nedůvěryhodné soubory; zavolejte PdfLoadLimits.unlimited() pro vypnutí všech limitů, když plně důvěřujete zdroji. AsposePdfException je základní třída celé hierarchie výjimek (včetně PdfIOException a PdfSecurityException), takže jediný except AsposePdfException zachytí jakoukoli chybu vyvolanou knihovnou.

Tipy a osvědčené postupy

• Vždy zavolejte dispose() (nebo close()) na Document, když s ním skončíte, nebo jej použijte jako krátkodobou lokální proměnnou — engine drží dekódovaný obsah stránky a obrázky v paměti až do uvolnění.
• Předávejte overwrite=True do save(), když přepisujete cestu, kterou jste již vytvořili ve stejném běhu; výchozí hodnota je False a vyvolá FileExistsError.
• Upřednostněte doc.optimize() před odesláním vygenerovaného PDF — jedná se o jediný volání, které odstraní nepoužívané objekty a komprimuje proudy, a typicky výrazně zmenší velikost výstupu.
• Nastavte PdfLoadLimits politiku explicitně vždy, když načítáte PDF z nedůvěryhodného zdroje (nahrání, e-mailové přílohy, webové škrabání); výchozí hodnoty jsou velkorysé, ale omezené, nejsou bezpečnostní bariérou, na kterou byste se měli slepě spoléhat.
• Zachyťte AsposePdfException (nebo konkrétní podtřídu, jako je PdfSecurityException) kolem volání načítání/ukládání místo pouhého Exception — jedná se o společnou základnu pro každou chybu, kterou knihovna vyhazuje.

Časté problémy

FAQ

Potřebuji licenci k použití Aspose.PDF FOSS pro Python?

Ne. Toto je open-source (licencováno pod MIT) vydání; neexistuje žádný licenční soubor ani krok aktivace, který by bylo třeba nastavit.

Mohu exportovat Document do formátů jiných než PDF?

V tomto vydání ne. save() podporuje pouze výstup PDF — předání jiné hodnoty SaveFormat/DocFormat vyvolá UnsupportedFeatureException místo vytvoření nesprávně označeného souboru.

Jaký je rozdíl mezi Document.merge() a pluginem Merger?

Document.merge() kombinuje instance Document, které již máte otevřené v paměti. Merger (s MergeOptions a FileDataSource) je pohodlný obal typu soubor-na-soubor, který otevře, sloučí a uloží za vás v jediném volání — užitečný pro jednoduché dávkové skripty, které nikdy nepotřebují mezilehlý objekt Document.

Proč pages.insert() nikdy nevyvolá výjimku při indexu mimo rozsah?

PageCollection.insert() omezí index na platný rozsah (záporné hodnoty se stanou 0, hodnoty za koncem se stanou len(doc.pages)) místo vyvolání výjimky, takže vložení nikdy neuspěje jen kvůli hodnotě indexu.

Jak bezpečně načíst PDF z nedůvěryhodného zdroje?

Vytvořte PdfLoadLimits s explicitními limity (max_input_bytes, max_pages, max_objects a podobně) a předávejte jej jako argument limits= pro Document(...) nebo load_from(). Každé pole už má výchozí konečnou hodnotu, ale jejich zpřísnění na očekávanou velikost vstupu snižuje prostředky, které může poškozený soubor spotřebovat.

API Reference Shrnutí

Viz také:

• API Reference: Úplná dokumentace tříd a metod pro aspose_pdf
• Znalostní báze: Průvodci zaměřenými na úkoly
• Přehled produktu: Přehled funkcí a schopností
• Začínáme / Instalace: instalace a nastavení
• Aspose.PDF for Python — Enterprise Documentation