Primitivas de Dados e Metadados XMP

Primitivas de Dados e Metadados XMP

Aspose.PDF FOSS para Python constrói seu API de nível superior — Document, Page, e as classes de anotação e formulário — sobre um pequeno conjunto de tipos de dados primitivos definidos em aspose_pdf.engine.data. Você raramente construirá a maioria desses diretamente, mas eles aparecem constantemente como tipos de propriedade e valores de retorno: o dicionário de recursos de uma página é indexado por valores PdfName, cores são instâncias Color, e Document.xmp_metadata retorna um XmpPacket. Este guia apresenta as primitivas de identidade de objeto, os wrappers de valor primitivo, Color, os enums de codificação de texto e o modelo de metadados XMP.

Identidade de objeto e o registro de objetos

PdfObjectID identifica um objeto indireto em um arquivo PDF por seu object_number e generation_number. PdfObjectRegistry atribui e rastreia esses identificadores à medida que os objetos são serializados, e PdfTrailerable é o contrato compartilhado para objetos que podem produzir o dicionário gravado em um trailer de 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)

Encapsuladores de valor primitivo

PdfNumber e PdfName encapsulam valores PDF brutos em objetos tipados Python. PdfNumber mantém seu value numérico como um Python nativo int ou float; PdfName contém uma string name e é o tipo usado para chaves de dicionário em todo o modelo de objeto de baixo nível — por exemplo, as chaves Font e Resources no dicionário de recursos de uma página. PdfNull representa o objeto nulo do PDF.

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")

Valores de cor

Color representa uma cor RGBA com propriedades de ponto flutuante r, g, b e a. Além do construtor de dois argumentos mais alfa, ele expõe um conjunto completo de fábricas de cores nomeadas — tanto em minúsculas (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) quanto PascalCase aliases (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()

Codificações de texto e filtros de fluxo

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifica uma codificação de texto, e Encoding expõe as constantes de codificação correspondentes (UTF8, UTF16, LATIN1, WIN_ANSI) juntamente com um método encode(text, encoding_type) que retorna o bytes codificado. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifica o filtro de fluxo aplicado ao conteúdo PDF comprimido.

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

Metadados XMP

XmpPacket é o modelo em memória para o pacote de metadados XMP de um documento — é o tipo retornado por Document.xmp_metadata. Ele contém uma coleção ordenada de fields (cada um um XmpField, XmpArray ou XmpProperty) e resolve os prefixos de namespace através de um XmpNamespaceProvider. Getters e setters tipados (get_value no estilo de acessores como get_bool, get_int, get_real, get_date, get_localized_text, get_array, e seus equivalentes set_*) leem e escrevem propriedades individuais por prefixo de namespace ou URI e nome da propriedade.

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 modela um valor estruturado (rdf:parseType="Resource") com sua própria pesquisa get(name), XmpArray modela um array ordenado com add(item) e remove(item), e XmpProperty é uma propriedade que carrega seus próprios qualificadores add_qualifier/remove_qualifier. Todos os quatro compartilham o mesmo bloco de construção XmpField para valores individuais.

Dicas e Melhores Práticas

• Leia Document.xmp_metadata para obter o XmpPacket do documento em vez de criar um do zero — ele já está preenchido a partir do arquivo carregado.
• Leia PdfNumber.value diretamente — ele já contém o Python nativo int ou float que você passou ao construtor; não há método de conversão to_double() ou to_int().
• Prefira as fábricas nomeadas Color (Color.red(), Color.Black() e assim por diante) em vez de tuplas feitas à mão r/g/b/a para cores comuns — elas são mais legíveis nos locais de chamada.
• Faça coincidir o EncodingType que você passa para Encoding.encode() com a codificação que o destino (fonte, fluxo ou visualizador) realmente espera; incompatibilidades de codificação de texto PDF são uma fonte comum de saída corrompida.
• Trate PdfObjectRegistry e PdfObjectID como tipos de baixo nível, voltados ao mecanismo — a maioria do código da aplicação lê o conteúdo do documento através de Document e Page em vez de registrar objetos diretamente.

Problemas Comuns

FAQ

Preciso instanciar PdfObjectID ou PdfObjectRegistry eu mesmo?

Raramente. Eles sustentam o processo de serialização do mecanismo; a maioria do código da aplicação nunca os instancia diretamente, a menos que esteja trabalhando com o modelo de objetos de baixo nível.

Qual é a diferença entre XmpField, XmpArray, XmpStruct e XmpProperty?

XmpField é um valor escalar único. XmpArray é uma lista ordenada de valores, XmpStruct é um agrupamento estruturado (rdf:parseType="Resource") de campos, e XmpProperty é um valor que também possui seus próprios qualificadores.

Como obtenho os metadados XMP de um documento?

Leia a propriedade xmp_metadata em um Document carregado — ela retorna um XmpPacket que você pode consultar e atualizar no local.

As fábricas de cor minúsculas e PascalCase são cores diferentes?

Não — Color.red() e Color.Red() são alias que retornam a mesma cor; ambas as grafias são fornecidas por conveniência.

API Reference Resumo

Ver também

• Aspose.PDF for Python — Enterprise Documentation