Примитивы данных и метаданные XMP

Примитивы данных и метаданные XMP

Aspose.PDF FOSS for Python строит свои более высокоуровневые API — Document, Page и классы аннотаций и форм — поверх небольшого набора примитивных типов данных, определённых в aspose_pdf.engine.data. Вы редко будете создавать большинство из них напрямую, но они постоянно появляются в виде типов свойств и возвращаемых значений: словарь ресурсов страницы индексируется значениями PdfName, цвета представляются экземплярами Color, а Document.xmp_metadata возвращает XmpPacket. Это руководство представляет примитивы идентичности объектов, обёртки примитивных значений, Color, перечисления кодировок текста и модель метаданных XMP.

Идентичность объектов и реестр объектов

PdfObjectID идентифицирует косвенный объект в PDF-файле по его object_number и generation_number. PdfObjectRegistry назначает и отслеживает эти идентификаторы при сериализации объектов, а PdfTrailerable является общим контрактом для объектов, способных создать словарь, записываемый в трейлер PDF.

import aspose_pdf
from aspose_pdf.engine.data import PdfObjectRegistry

registry = PdfObjectRegistry()

# register() assigns a PdfObjectID to a serializable object
object_id = registry.register(some_pdf_object)
print(object_id.object_number, object_id.generation_number)

# get() resolves an object back from its PdfObjectID
resolved = registry.get(object_id)

Обёртки примитивных значений

PdfNumber и PdfName оборачивают сырые значения PDF в типизированные объекты Python. PdfNumber хранит своё числовое value как нативный Python int или float; PdfName хранит строку name и используется в качестве типа для ключей словарей по всей низкоуровневой объектной модели — например, ключи Font и Resources в словаре ресурсов страницы. PdfNull представляет объект PDF null.

import aspose_pdf
from aspose_pdf.engine.data.number import PdfNumber
from aspose_pdf.engine.data.types import PdfName

number = PdfNumber(3.14)
raw_value = number.value  # already the native int/float you passed in

resources_key = PdfName("Resources")
font_key = PdfName("Font")

Значения цветов

Color представляет цвет RGBA с плавающими свойствами r, g, b и a. Помимо конструктора с двумя аргументами плюс альфа, он предоставляет полный набор именованных фабрик цветов — как в нижнем регистре (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()), так и PascalCase псевдонимов (Aqua(), Blue(), Azure(), Red(), Green(), Yellow(), Black(), White(), Gray()).

import aspose_pdf
from aspose_pdf.engine.data.types import Color

custom = Color(r=0.2, g=0.4, b=0.8, a=1.0)

# Named factories return ready-made Color instances
highlight = Color.yellow()
border = Color.Black()

Текстовые кодировки и фильтры потоков

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) определяет текстовую кодировку, а Encoding предоставляет соответствующие константы кодировок (UTF8, UTF16, LATIN1, WIN_ANSI) вместе с методом encode(text, encoding_type), возвращающим закодированный bytes. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) определяет фильтр потока, применяемый к сжатому содержимому PDF.

import aspose_pdf
from aspose_pdf.engine.data import Encoding, EncodingType, FilterType

encoded = Encoding.encode("Hello, world", EncodingType.WIN_ANSI)

# FilterType values identify how a content or image stream is compressed
current_filter = FilterType.FLATE_DECODE

Метаданные XMP

XmpPacket является моделью в памяти для пакета XMP-метаданных документа — это тип, возвращаемый Document.xmp_metadata. Он содержит упорядоченную коллекцию fields (каждый из которых является XmpField, XmpArray или XmpProperty) и разрешает префиксы пространств имён через XmpNamespaceProvider. Типизированные геттеры и сеттеры (аксессоры в стиле get_value, такие как get_bool, get_int, get_real, get_date, get_localized_text, get_array, и их set_* аналоги) читают и записывают отдельные свойства по префиксу пространства имён или URI и имени свойства.

import aspose_pdf

doc = aspose_pdf.Document()
doc.load_from("input.pdf")

xmp = doc.xmp_metadata  # XmpPacket

title = xmp.get_localized_text("dc", "title", lang="x-default")
xmp.set_value("dc", "creator", "Jane Doe")

serialized = xmp.serialize()

XmpStruct моделирует структурированное значение (rdf:parseType="Resource") со своей собственной таблицей поиска get(name), XmpArray моделирует упорядоченный массив с add(item) и remove(item), а XmpProperty — это свойство, несщее свои собственные квалификаторы add_qualifier/remove_qualifier. Все четыре используют один и тот же строительный блок XmpField для отдельных значений.

Советы и лучшие практики

• Прочитайте Document.xmp_metadata, чтобы получить XmpPacket документа, вместо того чтобы создавать его с нуля — он уже заполнен из загруженного файла.
• Читать PdfNumber.value напрямую — он уже содержит нативный Python int или float, который вы передали конструктору; нет метода конвертации to_double() или to_int().
• Отдавайте предпочтение именованным фабрикам Color (Color.red(), Color.Black() и т.д.) вместо самодельных кортежей r/g/b/a для обычных цветов — они читаются яснее в местах вызова.
• Согласуйте EncodingType, который вы передаёте в Encoding.encode(), с кодировкой, которую действительно ожидает получатель (шрифт, поток или просмотрщик); несоответствия кодировок текста PDF часто являются причиной искажённого вывода.
• Считайте PdfObjectRegistry и PdfObjectID низкоуровневыми типами, ориентированными на движок — большинство кода приложения читает содержимое документа через Document и Page, а не регистрируя объекты напрямую.

Распространённые проблемы

FAQ

Мне нужно самостоятельно создавать PdfObjectID или PdfObjectRegistry?

Редко. Они поддерживают процесс сериализации движка; большинство кода приложения никогда не создаёт их напрямую, если только не работает с низкоуровневой объектной моделью.

В чем разница между XmpField, XmpArray, XmpStruct и XmpProperty?

XmpField — это одиночное скалярное значение. XmpArray — упорядоченный список значений, XmpStruct — структурированная (rdf:parseType="Resource") группировка полей, а XmpProperty — значение, которое также содержит собственные квалификаторы.

Как получить XMP-метаданные документа?

Прочитайте свойство xmp_metadata у загруженного Document — оно возвращает XmpPacket, который можно запросить и обновить на месте.

Являются ли фабрики цветов в нижнем регистре и PascalCase разными цветами?

Нет — Color.red() и Color.Red() являются псевдонимами, возвращающими один и тот же цвет; обе записи предоставлены для удобства.

API Reference Сводка

См. также:

• Aspose.PDF for Python — Enterprise Documentation