Inleiding
Aspose.PDF FOSS voor Python draait om de Document klasse, die pages, form, outlines, tagged_content en attachments blootlegt als de toegangspunten voor structurele, documentniveau bewerking. Naast het toevoegen van paginainhoud dekt de bibliotheek de operaties die een PDF tot een volledig, distributeerbaar artefact maken: interactieve formuliervelden die gestructureerde gegevens verzamelen en beschikbaar stellen, bestandsbijlagen op documentniveau, lettertype-detectie en -inbedding voor tekstopmaak, en een bladwijzerboom voor navigatie. Elk van deze gebieden werpt fouten via een enkele exceptiehiearchie die is geworteld in AsposePdfException, zodat aanroepers pakket-specifieke fouten kunnen opvangen zonder per module te moeten raden naar exceptietypen.
Deze gids laat zien hoe u met die document-beheerinterface werkt: het opvangen en onderscheiden van AsposePdfException subklassen, het maken en lezen van AcroForm velden met Form en Field, het insluiten en herstellen van bijlagen via FileSpecification, het oplossen van lettertypen met FontRepository en FontRegistry, en het bouwen van een bladwijzerboom met OutlineCollection en OutlineItem. Elke sectie maakt alleen gebruik van de klassen en methoden die aanwezig zijn in het huidige pakket.
Aspose.PDF FOSS voor Python is een Python pakket, aspose-pdf-foss-for-python, uitgebracht onder de MIT-licentie, en vereist Python 3.11 of hoger. De naam van de top-level module is aspose_pdf. Het kernpakket hangt alleen af van cryptography en asn1crypto; optionele extra’s voegen Pillow-gebaseerde afbeeldingsdecodering, Brotli-gebaseerde WOFF2-lettertypeondersteuning, en HarfBuzz-gebaseerde complexe tekstlay-out toe.
Belangrijkste kenmerken
Foutafhandeling met AsposePdfException
Elke pakketspecifieke fout in Aspose.PDF FOSS voor Python is afgeleid van AsposePdfException. De meeste documentverwerkingsfouten vallen onder zijn PdfException subklasse, die op zijn beurt de basis vormt voor PdfParseException (ongeldige invoer), PdfSecurityException (versleuteling- en wachtwoordfouten, inclusief InvalidPasswordException), en PdfValidationException (structurele of conformiteitsfouten). Het opvangen van AsposePdfException als laatste, na meer specifieke subklassen, stelt een aanroeper in staat anders te reageren op een fout wachtwoord dan op een beschadigd bestand, terwijl er nog steeds één fallback is voor alle andere fouten die het pakket kan genereren.
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
Interactieve Formuliervelden
Document.form retourneert een Form façade over de AcroForm velden van het document. Form.add_text_field(), add_checkbox() en add_radio_group() maken nieuwe terminalvelden aan die gekoppeld zijn aan een pagina en een widget-rectangle, elk retourneert een Field. Field maakt name, value en field_type beschikbaar zodat bestaande velden kunnen worden geïnspecteerd en bijgewerkt op naam, en Field.remove() verwijdert een veld volledig.
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")
Ingesloten bestanden en bijlagen
Document.add_attachment voegt bytes in als een bestandsbijlage op documentniveau, weggeschreven naar de /Names /EmbeddedFiles naamtak van de PDF bij het opslaan, samen met een optioneel MIME-type, beschrijving en aanmaak-/wijzigingsdatums. Document.embedded_files leest elke bijlage terug als een getypeerde FileSpecification (name, contents, mime_type, description, size), en Document.get_embedded_file zoekt er één op naam. FileSpecification.save() schrijft de herstelde bytes naar schijf.
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")
Lettertypeontdekking en insluiten
FontRepository aggregeert lettertypebronnen en lost lettertypen op naam op door het document heen. FontRepository.add_source() registreert een FontSource zoals FolderFontSource (scan een map, optioneel recursief); FontRepository.find_font() en search() lossen vervolgens een lettertype op op basis van familie, volledige of PostScript naam, met terugval op de standaard-lettertype register. Elke match is een FontDescriptor, die direct kan worden doorgegeven aan Page.add_text om het lettertype in te sluiten en te subsetten. FontRegistry mapt veelvoorkomende niet-standaard namen (Arial, Times New Roman en soortgelijke) naar hun dichtstbijzijnde Standard-14 equivalent via search_font_by_name().
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")
Documentoverzichten en bladwijzers
Document.outlines retourneert een OutlineCollection, de bovenste container voor de bladwijzerboom van een PDF. OutlineCollection.add voegt een bovenste OutlineItem toe; OutlineItem.add() nestelt een onderliggende bladwijzer onder een bestaande. Elke OutlineItem draagt een title, een doel-page_index, en is_bold/is_italic weergavevlaggen, en maakt zijn eigen children lijst beschikbaar.
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")
Snelstart
Installeer het pakket en bouw vervolgens een document dat een bladwijzer, documentmetadata en een bijlage combineert in één script.
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])
Ondersteunde formaten
| Formaat | Extensie | Lezen | Schrijven |
|---|---|---|---|
| Ja | Ja | ||
| TIFF | tiff | - | Kunt u alstu |
Page.render, Page.save_as_image en Document.save_page_as_image produceren ook PNG-rasteroutput naast TIFF.
Dit zijn paginarasterisatie-uitvoer in plaats van documentlaadformaten.
Open source & licenties
Aspose.PDF FOSS voor Python wordt uitgebracht onder de MIT-licentie: geen gebruiksbeperkingen, geen runtimekosten, en geen registratievereisten voor commercieel of persoonlijk gebruik. De broncode wordt gehost op github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, en het pakket wordt gepubliceerd op PyPI als aspose-pdf-foss-for-python.
