Wprowadzenie
Aspose.PDF FOSS dla Python koncentruje się na klasie Document, która udostępnia pages, form, outlines, tagged_content i attachments jako punkty wejścia do strukturalnej i dokumentowej edycji. Poza dodawaniem treści stron, biblioteka obejmuje operacje, które czynią PDF kompletnym, dystrybuowalnym artefaktem: interaktywne pola formularzy zbierające i udostępniające dane strukturalne, załączniki plików na poziomie dokumentu, wykrywanie i osadzanie czcionek do tworzenia tekstu oraz drzewo zakładek do nawigacji. Każdy z tych obszarów zgłasza błędy poprzez jedną hierarchię wyjątków zaczynającą się od AsposePdfException, więc wywołujący może przechwytywać specyficzne błędy pakietu bez zgadywania typów wyjątków moduł po module.
Ten przewodnik pokazuje, jak pracować z tym interfejsem zarządzania dokumentem: przechwytywanie i rozróżnianie podklas AsposePdfException, tworzenie i odczytywanie pól AcroForm przy użyciu Form i Field, osadzanie i odzyskiwanie załączników poprzez FileSpecification, rozwiązywanie czcionek przy pomocy FontRepository i FontRegistry, oraz budowanie drzewa zakładek przy użyciu OutlineCollection i OutlineItem. Każda sekcja używa wyłącznie klas i metod dostępnych w bieżącym pakiecie.
Aspose.PDF FOSS dla Python jest pakietem Python, aspose-pdf-foss-for-python, wydanym na licencji MIT, wymagającym Python 3.11 lub nowszego. Jego nazwa modułu najwyższego poziomu to aspose_pdf. Pakiet podstawowy zależy jedynie od cryptography i asn1crypto; dodatkowe opcje dodają dekodowanie obrazów oparte na Pillow, wsparcie czcionek WOFF2 oparte na Brotli oraz układ tekstu złożonego oparty na HarfBuzz.
Kluczowe funkcje
Obsługa wyjątków w AsposePdfException
Każdy błąd specyficzny dla pakietu w Aspose.PDF FOSS dla Python pochodzi od AsposePdfException. Większość niepowodzeń przetwarzania dokumentów mieści się w podklasie PdfException, która z kolei jest bazą dla PdfParseException (nieprawidłowe dane wejściowe), PdfSecurityException (błędy szyfrowania i hasła, w tym InvalidPasswordException) oraz PdfValidationException (błędy strukturalne lub zgodności). Przechwytywanie AsposePdfException jako ostatniego, po bardziej szczegółowych podklasach, pozwala wywołującemu reagować inaczej na nieprawidłowe hasło niż na uszkodzony plik, zachowując jednocześnie jedną metodę awaryjną dla wszystkich pozostałych wyjątków, które może zgłosić pakiet.
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
Interaktywne pola formularza
Document.form zwraca Form fasadę nad polami AcroForm dokumentu. Form.add_text_field(), add_checkbox() i add_radio_group() tworzą nowe pola końcowe powiązane ze stroną i prostokątem widżetu, każde zwracające Field. Field udostępnia name, value i field_type, aby istniejące pola można było przeglądać i aktualizować po nazwie, a Field.remove() usuwa pole całkowicie.
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")
Osadzone pliki i załączniki
Document.add_attachment osadza bajty jako załącznik pliku na poziomie dokumentu, zapisywany w drzewie nazw /Names /EmbeddedFiles PDF podczas zapisu, wraz z opcjonalnym typem MIME, opisem oraz datami utworzenia/modyfikacji. Document.embedded_files odczytuje każdy załącznik jako typowany FileSpecification (name, contents, mime_type, description, size), a Document.get_embedded_file wyszukuje go po nazwie. FileSpecification.save() zapisuje odzyskane bajty na dysk.
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")
Wykrywanie i osadzanie czcionek
FontRepository agreguje źródła czcionek i rozwiązuje czcionki według nazwy w całym dokumencie. FontRepository.add_source() rejestruje FontSource, taki jak FolderFontSource (przeszukuje katalog, opcjonalnie rekurencyjnie); FontRepository.find_font() i search() następnie rozpoznają czcionkę po rodzinie, pełnej lub PostScript nazwie, odwołując się do rejestru czcionek standardowych. Każde dopasowanie jest FontDescriptor, które może być przekazane bezpośrednio do Page.add_text, aby osadzić i podzbiór czcionki. FontRegistry mapuje powszechne niestandardowe nazwy (Arial, Times New Roman i podobne) na ich najbliższy odpowiednik z Standard-14 poprzez 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")
Konspekt dokumentu i zakładki
Document.outlines zwraca OutlineCollection, kontener najwyższego poziomu drzewa zakładek PDF. OutlineCollection.add dodaje zakładkę najwyższego poziomu OutlineItem; OutlineItem.add() zagnieżdża zakładkę potomną pod istniejącą. Każdy OutlineItem zawiera title, docelowy page_index oraz flagi wyświetlania is_bold / is_italic, i udostępnia własną listę children.
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")
Szybki start
Zainstaluj pakiet, a następnie utwórz dokument, który łączy zakładkę, metadane dokumentu i załącznik w jednym skrypcie.
asposefoss/pdf is not yet published — build from source until it ships. See the project README for build instructions.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])
Obsługiwane formaty
| Format | Rozszerzenie | Odczyt | Zapis |
|---|---|---|---|
| Tak | Tak | ||
| TIFF | tiff | - | Tak |
Page.render, Page.save_as_image i Document.save_page_as_image również generują wyjście rastrowe PNG obok TIFF.
Są to wyjścia rasteryzacji stron, a nie formaty ładowania dokumentów.
Open Source & Licencjonowanie
Aspose.PDF FOSS dla Python jest wydany na licencji MIT: brak ograniczeń w użytkowaniu, brak opłat runtime oraz brak wymogów rejestracji dla zastosowań komercyjnych i prywatnych. Kod źródłowy jest hostowany pod adresem github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, a pakiet jest publikowany na PyPI jako aspose-pdf-foss-for-python.
