Hogyan dolgozzunk PDF adatokkal a Python-ban

Aspose.PDF FOSS a Python számára egy PDF dokumentum XMP metaadatait egy memóriában lévő adatmodellként ábrázolja, amely XmpPacket, XmpField, XmpArray, XmpStruct és XmpProperty objektumokból épül fel, a NamespaceProvider pedig feloldja a névtér előtagokat URI-kra. Ez lehetővé teszi, hogy strukturált metaadatokat olvass, építs és újraírj — címek, dátumok, kulcsszavak listái, egyedi mezők — anélkül, hogy kézzel írnád a RDF/XML. A könyvtár tisztán Python, és az alábbi paranccsal telepíthető.

Lépésről-lépésre útmutató

1. lépés: A csomag telepítése

Telepítsd a Aspose.PDF FOSS csomagot:

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

Ellenőrizd a telepítést úgy, hogy importálod a XmpPacket modult és kiírsz egy megerősítő üzenetet:

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

2. lépés: Szükséges osztályok importálása

Importálja az XMP adatmodell osztályait és a névtér feloldót:

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

3. lépés: Csomag létrehozása és egyszerű tulajdonságok beállítása

XmpPacket() egy üres mezőlistával kezd. set_value(prefix, name, value, uri=...) beállít vagy felülír egy egyszerű tulajdonságot, és get(prefix_or_uri, name) visszaolvassa azt mint XmpField; get elfogadja a regisztrált előtagot vagy a teljes névtér-URI-t:

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"

4. lépés: Típusos értékek tárolása

XmpPacket típusos kényelmi accessor-okat biztosít, amelyek konvertálnak a XMP belsőleg tárolt egyszerű szöveges formátumba és vissza: set_date/get_date, set_int/get_int, set_real/get_real, és set_bool/get_bool. Minden getter None-t ad vissza, ha a tulajdonság nincs jelen, ahelyett, hogy hibát dobna:

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

5. lépés: Lokalizált szöveg és rendezett tömbök tárolása

set_localized_text egy nyelvi alternatív (rdf:Alt) tulajdonságot ír, például dc:title egy adott nyelven, alapértelmezés szerint "x-default". set_array egy rendezett (Seq), rendezetlen (Bag) vagy alternatív (Alt) tömböt ír egy egyszerű értéklistából, és get_array visszaolvassa azt karakterláncok listájaként:

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

6. lépés: Strukturált értékek létrehozása a XmpStruct segítségével

Néhány XMP tulajdonság (dimenziórekordok, előzménybejegyzések) strukturált érték, nem egyszerű szöveg. Hozzon létre egyet a XmpStruct segítségével, adjon hozzá XmpField objektumokat a add használatával, és olvasson vissza egy tagot név szerint a get segítségével, majd csatolja a struktúrát a csomaghoz a add használatával:

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

7. lépés: Egyedi XMP névtér regisztrálása

NamespaceProvider előre betöltve a szabványos XMP névterekkel (Dublin Core, Adobe XMP, PDF és egyebek). Hívja a register(prefix, uri) függvényt egy egyedi leképezés hozzáadásához — ez visszaadja a szolgáltatót, így a hívások láncolhatók — majd csatolja a szolgáltatót egy csomaghoz, hogy a sorosítás fel tudja oldani az egyedi előtagot a megfelelő URI-ra:

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

8. lépés: Csomag elemzése és sorosítása

XmpPacket.parse(data, provider=...) nyers XMP csomag bájtokat vagy szöveget olvas be egy XmpPacket-be. A serialize() és a to_bytes() egyaránt visszaállítja a csomagot XMP csomag bájtokká:

xmp_bytes = packet.to_bytes()

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

Gyakori problémák és megoldások

get() vagy egy típusos getter visszatér None bár csak most állítottam be a tulajdonságot

Ellenőrizze, hogy a prefix (vagy URI) argumentum a get/get_int/get_date/etc. hívásban pontosan megegyezik-e azzal, amit a megfelelő set_* hívásnál átadtak — a get egyezik a mező előtagjával és a névtér URI-jával is, de ha az egyik hívásnál egy nem egyező egyéni előtag, a másiknál pedig egy URI szerepel, akkor ez kimarad.

Az egyedi névtér előtag nem teljes kimenetet eredményez sorosításkor

Az a előtag, amely nem a szabványos XMP névterek (dc, xmp, pdf és hasonló) egyike, vagy minden set_* hívásnál egy explicit uri= argumentumot igényel, vagy egy NamespaceProvider-t, amelyben az előtag regisztrálva van, és a csomaghoz XmpPacket(namespace_provider=provider) segítségével csatolva van, mielőtt a serialize()/to_bytes() hívás megtörténik.

get_bool, get_int, vagy get_real returns None egy olyan értékhez, amelyről tudom, hogy be van állítva

Az ilyen típusú lekérdezők None-t adnak vissza, amikor a tárolt szöveg nem értelmezhető a várt típusnak — például get_int egy olyan tulajdonságon, amelynek értékét set_value-vel szabad szövegként állították be a set_int helyett. Használja a megfelelő típusú beállítót (set_int, set_real, set_bool), hogy a lekérdező elemzési logikája egyezzen az írási úttal.

XmpPacket.parse raises ValueError egy nem megbízható forrásból származó csomagon

parse elutasít minden <!DOCTYPE vagy <!ENTITY deklarációt, mint egy ellenséges bemenet elleni védelmet az XXE és a milliárd-nevetés (billion-laughs) támadások ellen. Egy legitim XMP csomagnak soha nincs szüksége DTD-re; tekintse a kivételt jelzésnek arra, hogy a forrás adatfolyam hibás vagy nem biztonságos, a védelem megkerülése helyett.

get_array returns None lista helyett

get_array visszaad None-t, ha a név szerint megadott tulajdonság vagy nem létezik, vagy nem XmpArray formában van tárolva (például ha set_value-val lett beállítva set_array helyett). Használja a set_array-t a tulajdonság írásakor, hogy a tárolt érték megfeleljen a get_array által elvárt alaknak.

Gyakran Ismételt Kérdések

Mi a különbség a `set_value` és az olyan típusos beállítók, mint a `set_int` között?

set_value úgy tárolja, ahogy kapja value-t. A típusos beállítók (set_date, set_int, set_real, set_bool) a bemenetet az XMP belsőleg használt egyszerű szöveges formába konvertálják, és párosulnak egy megfelelő típusos lekérővel, amely visszafejti azt, ezért használja őket, ha körkörös típusbiztonságra van szükség nyers karakterláncok helyett.

Miben különböznek a `XmpArray` típusok (`Bag`, `Seq`, `Alt`)?

Bag egy rendezett nélküli értékhalmaz, Seq egy rendezett lista, és Alt alternatív értékeket tartalmaz (leggyakrabban nyelvi alternatívákat, ahogy a set_localized_text használja). Adja át a kívánt típust a set_array(..., kind="Bag")-nek, vagy építsen közvetlenül egy XmpArray(kind=...)-t.

Olvashatom a csomag nyers tulajdonságlistáját anélkül, hogy előre ismerném a neveiket?

Igen — iterálja a packet.fields elemet, amely a csomaghoz a beszúrási sorrendben hozzáadott minden XmpField, XmpArray és XmpProperty elemet tartalmazza.

Kell egy `NamespaceProvider` a szabványos XMP névterekhez?

Nem. A dc, xmp, pdf és a többi szabványos előtag automatikusan feloldódik. Egy NamespaceProvider csak akkor szükséges, ha saját, egyedi előtagokat találsz ki.

Miben különböznek a `XmpProperty` minősítők egy egyszerű `XmpField`-től?

XmpProperty egy alap XmpField-t csomagol egy minősítő mezők listájával (a add_qualifier segítségével hozzáadva), amely a ritkább esetben használható, amikor egy tulajdonságnak magának további RDF metaadatokra van szüksége az értékéhez csatolva, a xml:lang minősítőn túl, amelyet a XmpField.language már lefed.