Documentbeheer

Documentbeheer

De Document klasse is het toegangspunt voor bijna elke bewerking in Aspose.PDF FOSS voor Python: een nieuwe PDF maken, een bestaande laden, de pagina’s bewerken en het resultaat weer wegschrijven. Deze gids loopt door de levenscyclus van het document, bewerkingen op de paginacollectie, optimalisatie, workflows met meerdere bestanden, versleuteling en de uitzonderingen die je kunt verwachten te moeten afhandelen.

Documentlevenscyclus: Maken, Openen en Opslaan

Document() zonder argumenten maakt een leeg, in-memory document aan. Geef een bestandspad, ruwe bytes, of een willekeurige leesbare binaire stream op als eerste argument (of roep load_from() expliciet aan) om in plaats daarvan een bestaande PDF te laden. save() accepteert een pad of een schrijfbare binaire stream zoals 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() veroorzaakt FileExistsError als het doellpad al bestaat, tenzij je overwrite=True opgeeft. close() is een alias voor dispose(); beide zijn idempotent, dus ze meer dan eens aanroepen is veilig.

Alleen PDF is geïmplementeerd als opslagdoel — dit is de kern van de bibliotheek, volledig functioneel. Het doorgeven van een exportwaarde zoals SaveFormat.PPTX of DocFormat.HTML aan save() veroorzaakt UnsupportedFeatureException in plaats van een verkeerd gelabeld bestand te schrijven, zodat een mislukte export altijd duidelijk is in plaats van stil.

Beheren van de Paginacollectie

doc.pages is een PageCollection. Het ondersteunt len(), iteratie, en 0-gebaseerde indexering (doc.pages[0]), plus add(), insert(index, page) en delete(index) voor structurele bewerkingen. Elke Page biedt index, rect (de MediaBox), en 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) voegt een blanco pagina toe wanneer het wordt aangeroepen zonder argument. pages.insert() beperkt een buiten bereik index tot de dichtstbijzijnde geldige positie in plaats van een fout te genereren.

Documenten optimaliseren en comprimeren

Document.optimize voert beeld-/stroomdeduplicatie, ongebruikte-object garbage collection en stroomcompressie uit in één oproep. Geef een OptimizationOptions instantie door om te bepalen welke technieken worden uitgevoerd; laat het weg om het standaard opruimprofiel te gebruiken.

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() is een alias voor optimize(). Als je alleen stroomcompressie wilt zonder de structurele opruimstap, roep dan doc.compress_streams() direct aan.

Bestanden samenvoegen, splitsen en bewerken

Voor documenten die je al geopend hebt, voegt Document.merge() andere Document instanties toe aan de huidige:

from aspose_pdf import Document

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

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

Voor bestands-naar-bestand workflows zonder zelf een Document te openen, nemen de low-code Merger en Splitter plugins een MergeOptions/SplitOptions object dat is opgebouwd uit FileDataSource invoer en uitvoer:

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 biedt dezelfde reeks bewerkingen aan als een façade die True/False retourneert in plaats van een fout te gooien, wat handig is voor batch-scripts:

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-gebaseerd paginanummers, in tegenstelling tot PageCollection’s 0-gebaseerde indexering — zie Veelvoorkomende problemen hieronder.

Versleuteling en Documentbeveiliging

Document.encrypt(user_password, owner_password=None, permissions=-4) versleutelt het document in het geheugen; decrypt(password) en change_passwords(old, new_user, new_owner=None) draaien of roteren wachtwoorden. is_encrypted en permissions rapporteren de huidige status.

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)

Het openen van een versleuteld document zonder wachtwoord, of met een verkeerd wachtwoord, veroorzaakt een PdfSecurityException — vang deze klasse (van aspose_pdf.exceptions) op in plaats van aan te nemen dat een laadoperatie altijd slaagt.

Metadata, Validatie en Exception-afhandeling

Documentmetadata bevindt zich op doc.info (een eenvoudige dict[str, str]), en doc.version / doc.id tonen de PDF-headerversie en trailer-bestandsidentificatie. validate() (ook wel check() genoemd) rapporteert de structurele integriteit; repair() probeert veelvoorkomende problemen te verhelpen, zoals een ontbrekende paginalijst of een MediaBox buiten bereik.

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 begrenst geheugen- en objecttellingen voor onbetrouwbare bestanden; roep PdfLoadLimits.unlimited() aan om alle limieten uit te schakelen wanneer je de bron volledig vertrouwt. AsposePdfException is de basisklasse voor de volledige exception-hiërarchie (inclusief PdfIOException en PdfSecurityException), zodat één enkele except AsposePdfException elke door de bibliotheek opgegooide fout opvangt.

Tips en best practices

• Roep altijd dispose() (of close()) aan op een Document wanneer je klaar bent, of gebruik het als een kortlevende lokale variabele — de engine houdt gedecodeerde paginainhoud en afbeeldingen in het geheugen tot verwijdering.
• Geef overwrite=True door aan save() bij het herschrijven van een pad dat je al in dezelfde run hebt aangemaakt; de standaard is False en veroorzaakt FileExistsError.
• Geef de voorkeur aan doc.optimize() vóór het uitgeven van een gegenereerde PDF — het is een enkele oproep die ongebruikte objecten verwijdert en streams comprimeert, en verkleint doorgaans de outputgrootte merkbaar.
• Stel expliciet een PdfLoadLimits beleid in wanneer je PDF’s laadt van een onbetrouwbare bron (uploads, e-mailbijlagen, webscrapes); de standaardinstellingen zijn ruimhartig maar eindig, geen beveiligingsgrens waarop je blind moet vertrouwen.
• Vang AsposePdfException (of een specifieke subklasse zoals PdfSecurityException) op rond laad-/opslaaanroepen in plaats van de kale Exception — het is de gemeenschappelijke basis voor elke fout die de bibliotheek werpt.

Veelvoorkomende problemen

FAQ

Heb ik een licentie nodig om Aspose.PDF FOSS te gebruiken voor Python?

Nee. Dit is de open-source (MIT-gelicentieerde) editie; er is geen licentiebestand of activeringsstap om te configureren.

Kan ik een Document exporteren naar andere formaten dan PDF?

Niet in deze release. save() ondersteunt alleen PDF-uitvoer — het doorgeven van een andere SaveFormat/DocFormat waarde veroorzaakt UnsupportedFeatureException in plaats van een verkeerd gelabeld bestand.

Wat is het verschil tussen Document.merge() en de Merger plugin?

Document.merge() combineert Document instanties die je al in het geheugen hebt geopend. Merger (met MergeOptions en FileDataSource) is een file-to-file gemak-wrapper die voor je opent, samenvoegt en opslaat in één oproep — handig voor eenvoudige batchscripts die nooit het tussenliggende Document object nodig hebben.

Waarom werpt pages.insert() nooit een uitzondering voor een index buiten het bereik?

PageCollection.insert() klempt de index in het geldige bereik (negatieve waarden worden 0, waarden die voorbij het einde liggen worden len(doc.pages)) in plaats van een uitzondering te werpen, zodat een invoeging nooit faalt puur door de indexwaarde.

Hoe laad ik veilig een PDF van een onbetrouwbare bron?

Construeer een PdfLoadLimits met expliciete limieten (max_input_bytes, max_pages, max_objects, enzovoort) en geef deze door als het limits= argument aan Document(...) of load_from(). Elk veld heeft al een eindige standaardwaarde, maar door ze aan te passen aan de verwachte invoergrootte verklein je de middelen die een misvormd bestand kan verbruiken.

API Reference Samenvatting

Zie ook

• API Reference: Volledige klasse- en methodedocumentatie voor aspose_pdf
• Kennisbank: Taakgerichte how-to-gidsen
• Productoverzicht: Samenvatting van functies en mogelijkheden
• Aan de slag / Installatie: installeren en configureren
• Aspose.PDF for Python — Enterprise Documentation