Primitives de données et métadonnées XMP

Primitives de données et métadonnées XMP

Aspose.PDF FOSS for Python construit ses API de niveau supérieur — Document, Page, et les classes d’annotation et de formulaire — au-dessus d’un petit ensemble de types de données primitives définis dans aspose_pdf.engine.data. Vous construirez rarement la plupart de ceux-ci directement, mais ils apparaissent constamment comme types de propriétés et valeurs de retour: le dictionnaire des ressources d’une page est indexé par des valeurs PdfName, les couleurs sont des instances Color, et Document.xmp_metadata renvoie un XmpPacket. Ce guide présente les primitives d’identité d’objet, les enveloppes de valeurs primitives, Color, les énumérations d’encodage de texte et le modèle de métadonnées XMP.

Identité d’objet et registre d’objets

PdfObjectID identifie un objet indirect dans un fichier PDF par son object_number et generation_number. PdfObjectRegistry assigne et suit ces identifiants au fur et à mesure que les objets sont sérialisés, et PdfTrailerable est le contrat partagé pour les objets pouvant produire le dictionnaire écrit dans le trailer d’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)

Enveloppes de valeurs primitives

PdfNumber et PdfName encapsulent des valeurs PDF brutes dans des objets Python typés. PdfNumber conserve son value numérique comme un Python natif int ou float; PdfName conserve une chaîne de caractères name et est le type utilisé pour les clés de dictionnaire tout au long du modèle d’objet bas-niveau — par exemple, les clés Font et Resources du dictionnaire des ressources d’une page. PdfNull représente l’objet nul 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")

Valeurs de couleur

Color représente une couleur RGBA avec les propriétés flottantes r, g, b et a. En plus du constructeur à deux arguments plus alpha, il expose un ensemble complet de factories de couleurs nommées — à la fois en minuscules (aqua(), blue(), azure(), red(), green(), yellow(), black(), white(), gray()) et des 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()

Encodages de texte et filtres de flux

EncodingType (WIN_ANSI, MAC_ROMAN, MAC_EXPERT, PDF_DOC, UNICODE) identifie un encodage de texte, et Encoding expose les constantes d’encodage correspondantes (UTF8, UTF16, LATIN1, WIN_ANSI) ainsi qu’une méthode encode(text, encoding_type) qui renvoie le bytes encodé. FilterType (NONE, FLATE_DECODE, LZW_DECODE, DCT_DECODE, JPX_DECODE, CCITT_FAX_DECODE, JBIG2_DECODE) identifie le filtre de flux appliqué au contenu PDF compressé.

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

Métadonnées XMP

XmpPacket est le modèle en mémoire du paquet de métadonnées XMP d’un document — c’est le type renvoyé par Document.xmp_metadata. Il contient une collection ordonnée de fields (chacun étant un XmpField, XmpArray ou XmpProperty) et résout les préfixes d’espace de noms via un XmpNamespaceProvider. Les getters et setters typés (accesseurs de style get_value tels que get_bool, get_int, get_real, get_date, get_localized_text, get_array, et leurs homologues set_*) lisent et écrivent des propriétés individuelles par préfixe d’espace de noms ou URI et nom de propriété.

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 modélise une valeur structurée (rdf:parseType="Resource") avec son propre lookup get(name), XmpArray modélise un tableau ordonné avec add(item) et remove(item), et XmpProperty est une propriété qui porte ses propres qualificateurs add_qualifier/remove_qualifier. Les quatre partagent le même composant de construction XmpField pour les valeurs individuelles.

Conseils et bonnes pratiques

• Lisez Document.xmp_metadata pour obtenir le XmpPacket du document plutôt que d’en créer un à partir de zéro — il est déjà rempli à partir du fichier chargé.
• Lisez PdfNumber.value directement — il contient déjà le Python natif int ou float que vous avez passé au constructeur ; il n’existe aucune méthode de conversion to_double() ou to_int().
• Privilégiez les usines nommées Color (Color.red(), Color.Black(), etc.) plutôt que les tuples faits maison r/g/b/a pour les couleurs courantes — ils sont plus lisibles dans les appels.
• Faites correspondre le EncodingType que vous transmettez à Encoding.encode() avec l’encodage réellement attendu par la destination (police, flux ou visualiseur) ; les incompatibilités d’encodage de texte PDF sont une source fréquente de sortie brouillée.
• Considérez PdfObjectRegistry et PdfObjectID comme des types de bas niveau, orientés moteur — la plupart du code applicatif lit le contenu du document via Document et Page plutôt que d’enregistrer les objets directement.

Problèmes courants

FAQ

Dois-je créer PdfObjectID ou PdfObjectRegistry moi-même ?

Rarement. Ils soutiennent le processus de sérialisation du moteur ; la plupart du code applicatif ne les instancie jamais directement, sauf s’il travaille avec le modèle d’objet de bas niveau.

Quelle est la différence entre XmpField, XmpArray, XmpStruct et XmpProperty ?

XmpField est une valeur scalaire unique. XmpArray est une liste ordonnée de valeurs, XmpStruct est un regroupement structuré (rdf:parseType="Resource") de champs, et XmpProperty est une valeur qui porte également ses propres qualificateurs.

Comment obtenir les métadonnées XMP d’un document ?

Lisez la propriété xmp_metadata d’un Document chargé — elle renvoie un XmpPacket que vous pouvez interroger et mettre à jour sur place.

Les usines de couleur minuscules et PascalCase sont-elles des couleurs différentes ?

Non — Color.red() et Color.Red() sont des alias qui renvoient la même couleur; les deux orthographes sont fournies par commodité.

API Reference Résumé

Voir aussi

• Aspose.PDF for Python — Enterprise Documentation