Comment travailler avec les données PDF dans Python

Aspose.PDF FOSS pour Python représente les métadonnées XMP d’un document PDF sous la forme d’un modèle de données en mémoire construit à partir des objets XmpPacket, XmpField, XmpArray, XmpStruct et XmpProperty, avec NamespaceProvider qui résout les préfixes d’espace de noms en URI. Cela vous permet de lire, créer et réécrire des métadonnées structurées — titres, dates, listes de mots-clés, champs personnalisés — sans écrire manuellement RDF/XML. La bibliothèque est pure Python et s’installe avec la commande ci-dessous.

Guide étape par étape

git clone https://github.com/aspose-pdf-foss/Aspose-PDF-FOSS-for-Python.git
cd Aspose-PDF-FOSS-for-Python
pip install -e .

from aspose_pdf import XmpPacket
print("aspose-pdf-foss-for-python is ready.")

from aspose_pdf import (
    NamespaceProvider,
    XmpArray,
    XmpField,
    XmpPacket,
    XmpProperty,
    XmpStruct,
)

from aspose_pdf import XmpPacket

packet = XmpPacket()
packet.set_value("dc", "title", "Quarterly Report")
packet.set_value(
    "dc", "creator", "Automation Pipeline",
    uri="http://purl.org/dc/elements/1.1/",
)

title_field = packet.get("dc", "title")
print(title_field.value)  # "Quarterly Report"

from datetime import datetime

packet.set_date("xmp", "CreateDate", datetime(2026, 7, 29, 9, 30))
packet.set_int("pdf", "PageCount", 42)
packet.set_real("custom", "ConfidenceScore", 0.97, uri="https://example.com/ns/custom/1.0/")
packet.set_bool("custom", "IsFinal", True, uri="https://example.com/ns/custom/1.0/")

print(packet.get_date("xmp", "CreateDate"))
print(packet.get_int("pdf", "PageCount"))
print(packet.get_real("custom", "ConfidenceScore"))
print(packet.get_bool("custom", "IsFinal"))

packet.set_localized_text("dc", "description", "Quarterly summary", lang="en")
packet.set_localized_text(
    "dc", "description", "Resumen trimestral",
    uri="http://purl.org/dc/elements/1.1/", lang="es",
)
print(packet.get_localized_text("dc", "description", lang="es"))

packet.set_array("dc", "subject", ["finance", "quarterly", "internal"], kind="Bag")
print(packet.get_array("dc", "subject"))

dimensions = XmpStruct()
dimensions.add(XmpField(prefix="stDim", name="w", value="612"))
dimensions.add(XmpField(prefix="stDim", name="h", value="792"))
dimensions.add(XmpField(prefix="stDim", name="unit", value="pt"))

print(dimensions.get("w").value)  # "612"

packet.add(XmpField(prefix="xmpTPg", name="MaxPageSize", value=dimensions))

from aspose_pdf import NamespaceProvider, XmpPacket

provider = NamespaceProvider()
provider.register("custom", "https://example.com/ns/custom/1.0/")

packet = XmpPacket(namespace_provider=provider)
packet.set_value("custom", "batch_id", "run-2026-07-29")

xmp_bytes = packet.to_bytes()

restored = XmpPacket.parse(xmp_bytes)
print(restored.get("dc", "title").value)

Problèmes courants et solutions

get() ou un getter typé renvoie None même si je viens de définir la propriété

Confirmez que l’argument prefix (ou URI) passé à get/get_int/get_date/etc. correspond exactement à ce qui a été fourni à l’appel set_* correspondant — get correspond à la fois au préfixe du champ et à son URI de namespace, mais un préfixe personnalisé incohérent dans un appel et un URI dans l’autre entraînera un échec.

Un préfixe de namespace personnalisé produit une sortie incomplète lors de la sérialisation

Un préfixe qui ne fait pas partie des namespaces XMP standards (dc, xmp, pdf, etc.) nécessite soit un argument uri= explicite à chaque appel set_*, soit un NamespaceProvider avec ce préfixe enregistré et attaché au paquet via XmpPacket(namespace_provider=provider) avant d’appeler serialize()/to_bytes().

get_bool, get_int, ou get_real returns None pour une valeur que je sais être définie

Ces getters typés renvoient None lorsque le texte stocké ne peut pas être analysé comme le type attendu — par exemple, get_int sur une propriété dont la valeur a été définie avec set_value comme texte libre plutôt qu’avec set_int. Utilisez le setter typé correspondant (set_int, set_real, set_bool) afin que la logique d’analyse du getter corresponde au chemin d’écriture.

XmpPacket.parse raises ValueError sur un paquet provenant d’une source non fiable

parse rejette toute déclaration <!DOCTYPE ou <!ENTITY en tant que garde contre les entrées hostiles contre les attaques XXE et billion-laughs. Un paquet XMP légitime n’a jamais besoin d’un DTD; considérez l’exception comme un signal que le flux source est malformé ou dangereux plutôt que de contourner la garde.

get_array returns None au lieu d’une liste

get_array renvoie None lorsque la propriété nommée n’existe pas ou n’a pas été stockée en tant que XmpArray (par exemple, si elle a été définie avec set_value au lieu de set_array). Utilisez set_array lors de l’écriture de la propriété afin que la valeur stockée corresponde à la forme attendue par get_array.

Foire aux questions

Quelle est la différence entre set_value et les setters typés comme set_int?

set_value stocke tel quel tout ce que value vous transmettez. Les setters typés (set_date, set_int, set_real, set_bool) convertissent leur entrée en la forme texte brute utilisée en interne par XMP et s’associent à un getter typé correspondant qui la reconvertit, utilisez-les donc lorsque vous avez besoin d’une sécurité de type aller-retour plutôt que de simples chaînes.

En quoi les types XmpArray (Bag, Seq, Alt) diffèrent-ils?

Bag est un ensemble non ordonné de valeurs, Seq est une liste ordonnée, et Alt contient des valeurs alternatives (le plus souvent des alternatives linguistiques, comme le utilise set_localized_text). Transmettez le type souhaité à set_array(..., kind="Bag") ou créez directement un XmpArray(kind=...).

Puis-je lire la liste brute des propriétés d’un paquet sans connaître leurs noms à l’avance?

Oui — itérez packet.fields, qui contient chaque XmpField, XmpArray et XmpProperty ajoutés au paquet dans l’ordre d’insertion.

Ai-je besoin d’un NamespaceProvider pour les espaces de noms XMP standard?

Non. dc, xmp, pdf et les autres préfixes standard se résolvent automatiquement. Un NamespaceProvider n’est nécessaire que pour les préfixes personnalisés que vous créez vous-même.

En quoi les qualificateurs XmpProperty diffèrent-ils d’un simple XmpField?

XmpProperty enveloppe un XmpField de base avec une liste de champs de qualification (ajoutés avec add_qualifier), utilisé pour le cas plus rare où une propriété elle-même nécessite des métadonnées RDF supplémentaires attachées à sa valeur, au-delà du qualificateur xml:lang que XmpField.language couvre déjà.

Voir aussi

• Gestion de documents (Guide du développeur)
• Comment charger un document dans Python
• Guide d’installation
• API Reference
• Dépôt GitHub
• Aspose.PDF for Python — Enterprise Knowledge Base