Data Primitives and XMP Metadata

Data Primitives and XMP Metadata

Aspose.PDF FOSS for Python builds its higher-level API — Document, Page, and the annotation and form classes — on top of a small set of primitive data types defined in aspose_pdf.engine.data. You will rarely construct most of these directly, but they surface constantly as property types and return values: a page’s resources dictionary is keyed by PdfName values, colors are Color instances, and Document.xmp_metadata returns an XmpPacket. This guide introduces the object-identity primitives, the primitive value wrappers, Color, the text-encoding enums, and the XMP metadata model.

Object identity and the object registry

PdfObjectID identifies an indirect object in a PDF file by its object_number and generation_number. PdfObjectRegistry assigns and tracks these identifiers as objects are serialized, and PdfTrailerable is the shared contract for objects that can produce the dictionary written into a PDF trailer.

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)

Primitive value wrappers

PdfNumber and PdfName wrap raw PDF values in typed Python objects. PdfNumber holds a numeric value and converts it with to_double() or to_int(); PdfName holds a name string and is the type used for dictionary keys throughout the low-level object model — for example, the Font and Resources keys on a page’s resource dictionary. PdfNull represents the PDF null object.

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

number = PdfNumber(3.14)
as_float = number.to_double()
as_int = number.to_int()

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

Color values

Color represents an RGBA color with r, g, b, and a float properties. Besides the two-argument-plus-alpha constructor, it exposes a full set of named color factories — both lowercase (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) and 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()

Text encodings and stream filters

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifies a text encoding, and Encoding exposes the matching encoding constants (UTF8, UTF16, LATIN1, WIN_ANSI) alongside an encode(text, encoding_type) method that returns the encoded bytes. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifies the stream filter applied to compressed PDF content.

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 metadata

XmpPacket is the in-memory model for a document’s XMP metadata packet — it is the type returned by Document.xmp_metadata. It holds an ordered collection of fields (each a XmpField, XmpArray, or XmpProperty) and resolves namespace prefixes through an XmpNamespaceProvider. Typed getters and setters (get_value-style accessors such as get_bool, get_int, get_real, get_date, get_localized_text, get_array, and their set_* counterparts) read and write individual properties by namespace prefix or URI and property name.

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 models a structured (rdf:parseType="Resource") value with its own get(name) lookup, XmpArray models an ordered array with add(item) and remove(item), and XmpProperty is a property that carries its own add_qualifier/remove_qualifier qualifiers. All four share the same XmpField building block for individual values.

Tips and Best Practices

• Read Document.xmp_metadata to get the document’s XmpPacket rather than building one from scratch — it is already populated from the loaded file.
• Use PdfNumber.to_double() or to_int() rather than assuming the underlying value is already the Python numeric type you expect.
• Prefer the named Color factories (Color.red(), Color.Black(), and so on) over hand-rolled r/g/b/a tuples for common colors — they read more clearly at call sites.
• Match the EncodingType you pass to Encoding.encode() to the encoding the destination (font, stream, or viewer) actually expects; PDF text encoding mismatches are a common source of garbled output.
• Treat PdfObjectRegistry and PdfObjectID as low-level, engine-facing types — most application code reads document content through Document and Page rather than registering objects directly.

Common Issues

FAQ

Do I need to construct PdfObjectID or PdfObjectRegistry myself?

Rarely. They back the engine’s serialization process; most application code never instantiates them directly unless it is working with the low-level object model.

What is the difference between XmpField, XmpArray, XmpStruct, and XmpProperty?

XmpField is a single scalar value. XmpArray is an ordered list of values, XmpStruct is a structured (rdf:parseType="Resource") grouping of fields, and XmpProperty is a value that also carries its own qualifiers.

How do I get a document’s XMP metadata?

Read the xmp_metadata property on a loaded Document — it returns an XmpPacket you can query and update in place.

Are the lowercase and PascalCase Color factories different colors?

No — Color.red() and Color.Red() are aliases that return the same color; both spellings are provided for convenience.

API Reference Summary

See Also

• Aspose.PDF — Enterprise Documentation