Primitivas de datos y metadatos XMP

Primitivas de datos y metadatos XMP

Aspose.PDF FOSS para Python construye su API de nivel superior — Document, Page, y las clases de anotación y formulario — sobre un pequeño conjunto de tipos de datos primitivos definidos en aspose_pdf.engine.data. Rara vez construirás la mayoría de estos directamente, pero aparecen constantemente como tipos de propiedades y valores de retorno: el diccionario de recursos de una página está indexado por valores PdfName, los colores son instancias Color, y Document.xmp_metadata devuelve un XmpPacket. Esta guía presenta las primitivas de identidad de objetos, los envoltorios de valores primitivos, Color, los enumerados de codificación de texto y el modelo de metadatos XMP.

Identidad de objeto y registro de objetos

PdfObjectID identifica un objeto indirecto en un archivo PDF por su object_number y generation_number. PdfObjectRegistry asigna y rastrea estos identificadores a medida que los objetos se serializan, y PdfTrailerable es el contrato compartido para los objetos que pueden producir el diccionario escrito en el trailer de un 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)

Envoltorios de valores primitivos

PdfNumber y PdfName envuelven valores PDF sin procesar en objetos tipados Python. PdfNumber almacena su value numérico como un Python nativo int o float; PdfName almacena una cadena name y es el tipo usado para las claves de diccionario en todo el modelo de objetos de bajo nivel — por ejemplo, las claves Font y Resources en el diccionario de recursos de una página. PdfNull representa el objeto nulo de 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 color

Color representa un color RGBA con propiedades de punto flotante r, g, b y a. Además del constructor de dos argumentos más alfa, expone un conjunto completo de fábricas de colores con nombre — tanto en minúsculas (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) como alias 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()

Codificaciones de texto y filtros de flujo

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifica una codificación de texto, y Encoding expone las constantes de codificación correspondientes (UTF8, UTF16, LATIN1, WIN_ANSI) junto con un método encode(text, encoding_type) que devuelve el bytes codificado. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifica el filtro de flujo aplicado al contenido 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

Metadatos XMP

XmpPacket es el modelo en memoria para el paquete de metadatos XMP de un documento — es el tipo devuelto por Document.xmp_metadata. Contiene una colección ordenada de fields (cada uno es un XmpField, XmpArray o XmpProperty) y resuelve los prefijos de espacio de nombres mediante un XmpNamespaceProvider. Los getters y setters tipados (accesores al estilo get_value como get_bool, get_int, get_real, get_date, get_localized_text, get_array, y sus equivalentes set_*) leen y escriben propiedades individuales por prefijo de espacio de nombres o URI y nombre de propiedad.

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 un valor estructurado (rdf:parseType="Resource") con su propia búsqueda get(name), XmpArray modela una matriz ordenada con add(item) y remove(item), y XmpProperty es una propiedad que lleva sus propios calificadores add_qualifier/remove_qualifier. Los cuatro comparten el mismo bloque de construcción XmpField para valores individuales.

Consejos y Mejores Prácticas

• Lea Document.xmp_metadata para obtener el XmpPacket del documento en lugar de crear uno desde cero — ya está poblado a partir del archivo cargado.
• Lea PdfNumber.value directamente — ya contiene el Python nativo int o float que pasó al constructor; no hay método de conversión to_double() o to_int().
• Prefiera las fábricas nombradas Color (Color.red(), Color.Black(), etc.) en lugar de tuplas hechas a mano r/g/b/a para colores comunes — se leen más claramente en los puntos de llamada.
• Haga coincidir el EncodingType que pasa a Encoding.encode() con la codificación que realmente espera el destino (fuente, flujo o visor); los desajustes de codificación de texto PDF son una fuente común de salida distorsionada.
• Trate PdfObjectRegistry y PdfObjectID como tipos de bajo nivel orientados al motor — la mayor parte del código de la aplicación lee el contenido del documento a través de Document y Page en lugar de registrar objetos directamente.

Problemas comunes

FAQ

¿Necesito construir PdfObjectID o PdfObjectRegistry yo mismo?

Rara vez. Respaldan el proceso de serialización del motor; la mayor parte del código de la aplicación nunca los instancia directamente a menos que esté trabajando con el modelo de objetos de bajo nivel.

¿Cuál es la diferencia entre XmpField, XmpArray, XmpStruct y XmpProperty?

XmpField es un valor escalar único. XmpArray es una lista ordenada de valores, XmpStruct es una agrupación estructurada (rdf:parseType="Resource") de campos, y XmpProperty es un valor que también lleva sus propios calificadores.

¿Cómo obtengo los metadatos XMP de un documento?

Lea la propiedad xmp_metadata en un Document cargado — devuelve un XmpPacket que puede consultar y actualizar in situ.

¿Son los factories de Color en minúsculas y PascalCase colores diferentes?

No — Color.red() y Color.Red() son alias que devuelven el mismo color; ambas ortografías se proporcionan por conveniencia.

API Reference Resumen

Ver también

• Aspose.PDF for Python — Enterprise Documentation