Введение
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")
Быстрый старт
Установите пакет, затем создайте документ, который объединяет закладку, метаданные документа и вложение в едином скрипте.
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])
Поддерживаемые форматы
| Формат | Расширение | Чтение | Запись |
|---|---|---|---|
| Да | Да | ||
| TIFF | tiff | - | Да |
Page.render, Page.save_as_image и Document.save_page_as_image также генерируют растровый вывод PNG наряду с TIFF.
Это выводы растрирования страниц, а не форматы загрузки документов.
Открытый исходный код и лицензирование
Aspose.PDF FOSS for Python выпущен под лицензией MIT: отсутствие ограничений по использованию, отсутствие сборов за выполнение и отсутствие требований регистрации для коммерческого или личного использования. Исходный код размещён по адресу github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python, а пакет опубликован на PyPI как aspose-pdf-foss-for-python.
