Dokumentumkezelés

Dokumentumkezelés

A Document osztály a belépési pont szinte minden művelethez a Aspose.PDF FOSS-ben a Python számára: új PDF létrehozása, meglévő betöltése, az oldalak szerkesztése, és az eredmény visszaírása. Ez az útmutató végigvezet a dokumentum életciklusán, az oldalgyűjtemény műveletein, optimalizáláson, többfájlos munkafolyamatokon, titkosításon, és azokról a kivételekről, amelyeket kezelni kell.

Dokumentum életciklus: Létrehozás, Megnyitás és Mentés

A Document() argumentumok nélkül üres, memóriában tárolt dokumentumot hoz létre. Adj meg egy fájl elérési utat, nyers bytes-t, vagy bármilyen olvasható bináris adatfolyamot első argumentumként (vagy hívd meg kifejezetten a load_from()-t), hogy egy meglévő PDF-et tölts be helyette. A save() elfogad egy útvonalat vagy egy írható bináris adatfolyamot, például a 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()

A save() FileExistsError-t dob, ha a cél útvonal már létezik, hacsak nem adod meg a overwrite=True-t. A close() egy alias a dispose() számára; mindkettő idempotens, így többszöri meghívásuk biztonságos.

Jelenleg csak a PDF van megvalósítva mentési célként — ez a könyvtár magja, teljesen működő funkció. Ha exportálási értéket, például SaveFormat.PPTX vagy DocFormat.HTML-t adsz át a save()-nek, akkor UnsupportedFeatureException keletkezik a helytelenül címkézett fájl írása helyett, így egy sikertelen export mindig hangosan jelzett, nem csendben.

Az oldalgyűjtemény kezelése

doc.pages egy PageCollection. Támogatja a len(), az iterációt és a 0-alapú indexelést (doc.pages[0]), valamint a add(), insert(index, page) és delete(index) struktúraszerkesztési lehetőségeket. Minden Page elérhetővé teszi a index, a rect (a MediaBox) és 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) egy üres oldalt fűz hozzá, ha argumentum nélkül hívják. pages.insert() a tartományon kívüli indexet a legközelebbi érvényes pozícióra korlátozza, ahelyett, hogy hibát dobna.

Dokumentumok optimalizálása és tömörítése

Document.optimize egy hívásban futtatja a kép/folyam deduplikációt, a nem használt objektumok szemétgyűjtését és a folyam tömörítését. Adj meg egy OptimizationOptions példányt a futtatandó technikák vezérléséhez; hagyd ki, ha a standard takarítási profilt szeretnéd használni.

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() egy alias a optimize() számára. Ha csak folyam tömörítést szeretnél a struktúra-takarítási lépés nélkül, hívd közvetlenül a doc.compress_streams() függvényt.

Fájlok egyesítése, felosztása és szerkesztése

A már megnyitott dokumentumokhoz a Document.merge() a többi Document példányt a jelenlegire fűzi hozzá:

from aspose_pdf import Document

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

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

Fájl-fájl munkafolyamatokhoz, anélkül hogy saját maga megnyitna egy Document-t, az alacsony kódú Merger és Splitter pluginek egy MergeOptions/SplitOptions objektumot vesznek, amelyet a FileDataSource bemenetek és kimenetek alapján építenek:

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 ugyanazt a műveletcsaládot kínálja, mint egy felület, amely True/False értéket ad vissza ahelyett, hogy kivételt dobna, ami kényelmes kötegelt szkriptekhez:

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-alapú oldalszámok, ellentétben PageCollection’s 0-alapú indexelés — lásd Gyakori problémák alább.

Titkosítás és dokumentumbiztonság

Document.encrypt(user_password, owner_password=None, permissions=-4) titkosítja a memóriában lévő dokumentumot; decrypt(password) és change_passwords(old, new_user, new_owner=None) visszafordítják vagy forgatják a jelszavakat. is_encrypted és permissions jelentik az aktuális állapotot.

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)

Titkosított dokumentum megnyitása jelszó nélkül vagy rossz jelszóval PdfSecurityException kivételt vált ki — ez a osztály (a aspose_pdf.exceptions-ből) elkapandó, ahelyett, hogy azt feltételeznénk, a betöltés mindig sikeres.

Metaadatok, validáció és kivételkezelés

A dokumentum metaadatai a doc.info (egyszerű dict[str, str])-ben tárolódnak, és a doc.version / doc.id felfedik a PDF fejléc verzióját és a trailer fájlazonosítót. A validate() (más néven check()) jelenti a szerkezeti integritást; a repair() megpróbálja kijavítani a gyakori problémákat, például egy hiányzó oldallistát vagy egy tartományon kívüli MediaBox.

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 korlátozza a memóriát és az objektumszámot megbízhatatlan fájlok esetén; hívd a PdfLoadLimits.unlimited()-t, ha teljesen megbízol a forrásban, hogy minden korlátot letiltsd. A AsposePdfException a teljes kivételhierarchia (beleértve a PdfIOException és PdfSecurityException osztályokat) alaposztálya, ezért egyetlen except AsposePdfException elkap minden könyvtárból származó hibát.

Tippek és legjobb gyakorlatok

• Mindig hívd meg a dispose() (vagy a close()) egy Document esetén, amikor befejezted, vagy használd rövid élettartamú helyi változóként — a motor a dekódolt oldal tartalmat és képeket a memóriában tartja a felszabadításig.
• Add át a overwrite=True értéket a save() számára, amikor felülírsz egy útvonalat, amelyet már létrehoztál ugyanabban a futtatásban; az alapértelmezett False, és FileExistsError kivételt dob.
• A doc.optimize() használata előnyösebb, mielőtt elküldenéd a generált PDF-et — ez egyetlen hívás, amely eltávolítja a nem használt objektumokat és tömöríti a folyamokat, és általában jelentősen csökkenti a kimeneti méretet.
• Állíts be egy PdfLoadLimits szabályt kifejezetten, amikor PDF-eket töltesz be nem megbízható forrásból (feltöltések, e-mail mellékletek, webkaparással); az alapértelmezések bőkezűek, de végesek, nem pedig olyan biztonsági határ, amire vakon támaszkodhatnál.
• Kapd el a AsposePdfException (vagy egy konkrét alosztályt, például a PdfSecurityException) a betöltési/mentési hívások körül a puszta Exception helyett — ez a közös alap minden hiba számára, amelyet a könyvtár dob.

Gyakori problémák

FAQ

Szükségem van licencre a Aspose.PDF FOSS használatához Python esetén?

Nem. Ez a nyílt forráskódú (MIT licencű) kiadás; nincs licencfájl vagy aktiválási lépés, amit konfigurálni kellene.

Exportálhatok egy Document fájlt a PDF-en kívül más formátumokba?

Ez a kiadás nem támogatja. A save() csak PDF kimenetet valósít meg — egy másik SaveFormat/DocFormat érték átadása UnsupportedFeatureException-t vált ki ahelyett, hogy hibásan címzett fájlt hozna létre.

Mi a különbség a Document.merge() és a Merger plugin között?

Document.merge() összevonja a már memóriában nyitott Document példányokat. A Merger (a MergeOptions és FileDataSource használatával) egy fájl-fájl kényelmi burkoló, amely egy hívással megnyitja, egyesíti és elmenti a fájlokat — hasznos egyszerű batch szkriptekhez, amelyeknek soha nincs szükségük a közbenső Document objektumra.

Miért nem dob pages.insert() hibát a tartományon kívüli index esetén?

PageCollection.insert() a indexet a érvényes tartományba szorítja (a negatív értékek 0 lesznek, a végén túli értékek len(doc.pages)), ahelyett, hogy hibát dobna, így egy beszúrás soha nem bukik meg kizárólag az index értéke miatt.

Hogyan tölthetek be biztonságosan egy PDF-et egy nem megbízható forrásból?

Hozzon létre egy PdfLoadLimits-t explicit korlátokkal (max_input_bytes, max_pages, max_objects, stb.) és adja át a limits= argumentumként a Document(...) vagy a load_from() függvénynek. Minden mező már alapértelmezés szerint véges értékre van állítva, de ha szigorúbban megadja a várt bemeneti méretet, csökkenti a hibás fájl által felhasználható erőforrásokat.

API Reference Összefoglaló

Lásd még:

• API Reference: Teljes osztály- és metódusdokumentáció a aspose_pdf
• Tudásbázis:Feladatorientált útmutatók
• Termék áttekintés: Jellemzők és képességek összefoglalása
• Első lépések / Telepítés: telepítés és beállítás
• Aspose.PDF for Python — Enterprise Documentation