Вступ
Aspose.PDF FOSS для Python зосереджений навколо класу Document, який відкриває pages, form, outlines, tagged_content та attachments як точки входу для структурного, документального рівня редагування. Окрім додавання вмісту сторінок, бібліотека охоплює операції, які роблять PDF повним, розповсюджуваним артефактом: інтерактивні поля форми, що збирають і надають структуровані дані, вкладення файлів на рівні документа, пошук шрифтів та їх вбудовування для створення тексту, а також дерево закладок для навігації. Кожна з цих областей генерує помилки через єдину ієрархію виключень, що має корінь у AsposePdfException, тому викликаючі можуть перехоплювати помилки, специфічні для пакету, без необхідності вгадувати типи виключень модуль за модулем.
У цьому посібнику показано, як працювати з цим інтерфейсом керування документами: перехоплювати та розрізняти підкласи AsposePdfException, створювати та читати поля AcroForm за допомогою Form і Field, вбудовувати та відновлювати вкладення через FileSpecification, вирішувати шрифти за допомогою FontRepository і FontRegistry, а також будувати дерево закладок за допомогою OutlineCollection і OutlineItem. Кожен розділ використовує лише класи та методи, присутні у поточному пакеті.
Aspose.PDF FOSS для Python — це пакет Python, aspose-pdf-foss-for-python, випущений під ліцензією MIT, що вимагає Python 3.11 або новішої версії. Його назва модуля верхнього рівня — aspose_pdf. Основний пакет залежить лише від cryptography і asn1crypto; додаткові опціональні компоненти додають декодування зображень на базі Pillow, підтримку шрифтів WOFF2 на базі Brotli та складне розташування тексту на базі HarfBuzz.
Ключові можливості
Обробка виключень за допомогою AsposePdfException
Кожна помилка, специфічна для пакету, у Aspose.PDF FOSS для Python походить від AsposePdfException. Більшість збоїв обробки документів належать до його підкласу PdfException, який, у свою чергу, слугує базою для PdfParseException (некоректний вхід), PdfSecurityException (помилки шифрування та пароля, включаючи InvalidPasswordException), та PdfValidationException (структурні або відповідності). Перехоплення AsposePdfException останнім, після більш специфічних підкласів, дозволяє викликаючому реагувати по-різному на неправильний пароль і на пошкоджений файл, залишаючи при цьому єдину резервну можливість для всіх інших виключень, які може підняти пакет.
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
Інтерактивні поля форми
Document.form повертає Form фасад над AcroForm полями документа. Form.add_text_field(), add_checkbox() та add_radio_group() створюють нові кінцеві поля, прив’язані до сторінки та прямокутника віджету, кожне з яких повертає Field. Field надає доступ до name, value та field_type, щоб існуючі поля можна було переглядати та оновлювати за ім’ям, а Field.remove() повністю видаляє поле.
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")
Вбудовані файли та вкладення
Document.add_attachment вбудовує байти як файл-вкладення рівня документа, записуючи їх у дерево імен /Names /EmbeddedFiles PDF під час збереження, разом з необов’язковим MIME-типом, описом та датами створення/модифікації. Document.embedded_files зчитує кожне вкладення назад як типізований FileSpecification (name, contents, mime_type, description, size), а Document.get_embedded_file шукає його за ім’ям. FileSpecification.save() записує відновлені байти на диск.
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")
Виявлення шрифтів та їх вбудовування
FontRepository агрегує джерела шрифтів і визначає шрифти за назвою у всьому документі. FontRepository.add_source() реєструє FontSource, наприклад FolderFontSource (сканує каталог, за потреби рекурсивно); FontRepository.find_font() та search() потім визначають шрифт за сімейством, повною або PostScript назвою, повертаючись до реєстру стандартних шрифтів. Кожен збіг — це FontDescriptor, який можна передати безпосередньо до Page.add_text для вбудовування та підмножини шрифту. FontRegistry зіставляє поширені нестандартні назви (Arial, Times New Roman та подібні) з їх найближчим еквівалентом Standard-14 через 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")
Контури документа та закладки
Document.outlines повертає OutlineCollection, верхній контейнер для дерева закладок PDF. OutlineCollection.add додає верхньорівневу OutlineItem; OutlineItem.add() розміщує дочірню закладку під існуючою. Кожна OutlineItem містить title, цільовий page_index та прапори відображення is_bold / is_italic, і надає власний список 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")
Швидкий старт
Встановіть пакет, а потім створіть документ, який поєднує закладку, метадані документа та вкладення в одному скрипті.
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])
Підтримувані формати
| Формат | Розширення | Читання | Запис |
|---|---|---|---|
| Так | Так | ||
| TIFF | tiff | - | Так |
Page.render, Page.save_as_image і Document.save_page_as_image також створюють растровий вихід PNG поряд з TIFF.
Це виводи растеризації сторінок, а не формати завантаження документів.
Open Source та ліцензування
Aspose.PDF FOSS для Python випускається під ліцензією MIT: немає обмежень використання, немає зборів за виконання та немає вимог реєстрації для комерційного чи особистого використання. Вихідний код розміщений за адресою github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, а пакет публікується на PyPI як aspose-pdf-foss-for-python.
