0
# Core Metadata Operations
1
2
The XMPMeta class provides comprehensive functionality for parsing, manipulating, and serializing XMP metadata. It supports all XMP data types including simple properties, arrays, structures, localized text, and provides complete namespace management.
3
4
## Capabilities
5
6
### XMPMeta Class
7
8
The core metadata handling class that provides the main services of the library.
9
10
```python { .api }
11
class XMPMeta:
12
def __init__(self, **kwargs):
13
"""
14
Create a new XMPMeta instance.
15
16
Parameters:
17
- xmp_str (optional): XMP string to parse
18
- _xmp_internal_ref (optional): Internal reference for library use
19
"""
20
```
21
22
### Property Access Methods
23
24
#### Getting Properties
25
26
```python { .api }
27
def get_property(self, schema_ns, prop_name):
28
"""
29
Get a property value.
30
31
Parameters:
32
- schema_ns: str, namespace URI
33
- prop_name: str, property name
34
35
Returns:
36
Property value if exists, None otherwise
37
38
Raises:
39
IOError: if exempi routine fails
40
"""
41
42
def get_array_item(self, schema_ns, array_prop_name, index):
43
"""
44
Get an array item value.
45
46
Parameters:
47
- schema_ns: str, namespace URI
48
- array_prop_name: str, array property name
49
- index: int, 1-based index
50
51
Returns:
52
Array item value
53
"""
54
55
def get_property_bool(self, schema, name):
56
"""Get property value as boolean."""
57
58
def get_property_int(self, schema_ns, name):
59
"""Get property value as integer."""
60
61
def get_property_long(self, schema_ns, prop_name):
62
"""Get property value as 64-bit integer."""
63
64
def get_property_float(self, schema_ns, prop_name):
65
"""Get property value as float."""
66
67
def get_property_datetime(self, schema_ns, prop_name):
68
"""Get property value as datetime object."""
69
70
def get_localized_text(self, schema_ns, alt_text_name, generic_lang, specific_lang):
71
"""
72
Get localized text from alt-text array.
73
74
Parameters:
75
- schema_ns: str, namespace URI
76
- alt_text_name: str, alt-text property name
77
- generic_lang: str, generic language code
78
- specific_lang: str, specific language code
79
80
Returns:
81
Localized text value
82
"""
83
```
84
85
#### Setting Properties
86
87
```python { .api }
88
def set_property(self, schema_ns, prop_name, prop_value, **kwargs):
89
"""
90
Set a property value.
91
92
Parameters:
93
- schema_ns: str, namespace URI
94
- prop_name: str, property name
95
- prop_value: property value
96
- **kwargs: optional keyword arguments from XMP_PROP_OPTIONS
97
"""
98
99
def set_array_item(self, schema_ns, array_name, item_index, item_value, **kwargs):
100
"""
101
Set an array item value.
102
103
Parameters:
104
- schema_ns: str, namespace URI
105
- array_name: str, array property name
106
- item_index: int, 1-based index
107
- item_value: item value
108
- **kwargs: optional keyword arguments
109
"""
110
111
def append_array_item(self, schema_ns, array_name, item_value, array_options=None, **kwargs):
112
"""
113
Append item to array.
114
115
Parameters:
116
- schema_ns: str, namespace URI
117
- array_name: str, array property name
118
- item_value: value to append
119
- array_options: array options bitmask
120
- **kwargs: optional keyword arguments
121
"""
122
123
def set_property_bool(self, schema_ns, prop_name, prop_value, **kwargs):
124
"""Set property as boolean value."""
125
126
def set_property_int(self, schema_ns, prop_name, prop_value, **kwargs):
127
"""Set property as integer value."""
128
129
def set_property_long(self, schema_ns, prop_name, prop_value, **kwargs):
130
"""Set property as 64-bit integer value."""
131
132
def set_property_float(self, schema_ns, prop_name, prop_value, **kwargs):
133
"""Set property as float value."""
134
135
def set_property_datetime(self, schema_ns, prop_name, prop_value, **kwargs):
136
"""Set property as datetime value."""
137
138
def set_localized_text(self, schema_ns, alt_text_name, generic_lang, specific_lang, prop_value, **kwargs):
139
"""
140
Set localized text in alt-text array.
141
142
Parameters:
143
- schema_ns: str, namespace URI
144
- alt_text_name: str, alt-text property name
145
- generic_lang: str, generic language code
146
- specific_lang: str, specific language code
147
- prop_value: text value
148
- **kwargs: optional keyword arguments
149
"""
150
```
151
152
### Property Management
153
154
```python { .api }
155
def delete_property(self, schema_ns, prop_name):
156
"""Delete a property."""
157
158
def delete_localized_text(self, schema_ns, alt_text_name, generic_lang, specific_lang):
159
"""Delete localized text from alt-text array."""
160
161
def does_property_exist(self, schema_ns, prop_name):
162
"""
163
Check if property exists.
164
165
Returns:
166
bool: True if property exists
167
"""
168
169
def does_array_item_exist(self, schema_ns, array_name, item):
170
"""
171
Check if array item exists.
172
173
Returns:
174
bool: True if array item exists
175
"""
176
177
def count_array_items(self, schema_ns, array_name):
178
"""
179
Count items in array.
180
181
Returns:
182
int: Number of items in array
183
"""
184
```
185
186
### Serialization and Parsing
187
188
```python { .api }
189
def parse_from_str(self, xmp_packet_str, xmpmeta_wrap=False, input_encoding=None):
190
"""
191
Parse RDF from string into XMP object.
192
193
Parameters:
194
- xmp_packet_str: str, XMP packet string
195
- xmpmeta_wrap: bool, whether string includes xmpmeta wrapper
196
- input_encoding: str, input encoding
197
"""
198
199
def serialize_to_str(self, padding=0, **kwargs):
200
"""
201
Serialize XMP to string.
202
203
Parameters:
204
- padding: int, padding for packet wrapper
205
- **kwargs: optional serialization options
206
207
Returns:
208
str: Serialized XMP packet
209
"""
210
211
def serialize_to_unicode(self, **kwargs):
212
"""
213
Serialize XMP to unicode string.
214
215
Returns:
216
unicode: Serialized XMP packet
217
"""
218
219
def serialize_and_format(self, padding=0, newlinechr='\n', tabchr='\t', indent=0, **kwargs):
220
"""
221
Serialize XMP with custom formatting.
222
223
Parameters:
224
- padding: int, padding for packet wrapper
225
- newlinechr: str, newline character
226
- tabchr: str, tab character
227
- indent: int, indentation level
228
- **kwargs: optional serialization options
229
230
Returns:
231
str: Formatted XMP packet
232
"""
233
```
234
235
### Utility Methods
236
237
```python { .api }
238
def clone(self):
239
"""
240
Create a copy of XMP packet.
241
242
Returns:
243
XMPMeta: New XMPMeta instance with copied data
244
"""
245
```
246
247
### Static Namespace Methods
248
249
```python { .api }
250
@staticmethod
251
def get_prefix_for_namespace(namespace):
252
"""
253
Get namespace prefix for URI.
254
255
Parameters:
256
- namespace: str, namespace URI
257
258
Returns:
259
str: Namespace prefix
260
"""
261
262
@staticmethod
263
def get_namespace_for_prefix(prefix):
264
"""
265
Get namespace URI for prefix.
266
267
Parameters:
268
- prefix: str, namespace prefix
269
270
Returns:
271
str: Namespace URI
272
"""
273
274
@staticmethod
275
def register_namespace(namespace_uri, suggested_prefix):
276
"""
277
Register custom namespace.
278
279
Parameters:
280
- namespace_uri: str, namespace URI
281
- suggested_prefix: str, suggested prefix
282
283
Returns:
284
str: Actual registered prefix
285
"""
286
```
287
288
### XMPIterator Class
289
290
Provides uniform iteration over XMP properties.
291
292
```python { .api }
293
class XMPIterator:
294
def __init__(self, xmp_obj, schema_ns=None, prop_name=None, **kwargs):
295
"""
296
Create iterator for XMP object.
297
298
Parameters:
299
- xmp_obj: XMPMeta instance
300
- schema_ns (optional): str, namespace URI to restrict iteration
301
- prop_name (optional): str, property name to restrict iteration
302
- **kwargs: optional keyword arguments from XMP_ITERATOR_OPTIONS
303
"""
304
305
def __iter__(self):
306
"""Return iterator object."""
307
308
def __next__(self):
309
"""
310
Get next iteration item.
311
312
Returns:
313
tuple: (schema, name, value, options_dict)
314
"""
315
316
def skip(self, **kwargs):
317
"""
318
Skip portion of remaining iterations.
319
320
Parameters:
321
- **kwargs: keywords from XMP_SKIP_OPTIONS
322
"""
323
```
324
325
## Usage Examples
326
327
### Basic Property Operations
328
329
```python
330
from libxmp import XMPMeta
331
332
# Create XMP metadata object
333
xmp = XMPMeta()
334
335
# Set simple property
336
xmp.set_property("http://ns.adobe.com/xap/1.0/", "CreatorTool", "Python XMP Toolkit")
337
338
# Set localized text
339
xmp.set_localized_text(
340
"http://purl.org/dc/elements/1.1/",
341
"title",
342
"x-default",
343
"en-US",
344
"My Document Title"
345
)
346
347
# Get property
348
creator_tool = xmp.get_property("http://ns.adobe.com/xap/1.0/", "CreatorTool")
349
print(f"Creator Tool: {creator_tool}")
350
351
# Work with arrays
352
xmp.append_array_item(
353
"http://purl.org/dc/elements/1.1/",
354
"subject",
355
"keyword1"
356
)
357
xmp.append_array_item(
358
"http://purl.org/dc/elements/1.1/",
359
"subject",
360
"keyword2"
361
)
362
363
# Count array items
364
count = xmp.count_array_items("http://purl.org/dc/elements/1.1/", "subject")
365
print(f"Number of keywords: {count}")
366
```
367
368
### Iteration and Serialization
369
370
```python
371
from libxmp import XMPMeta, XMPIterator
372
373
# Create and populate XMP
374
xmp = XMPMeta()
375
xmp.set_property("http://ns.adobe.com/xap/1.0/", "CreatorTool", "Python")
376
xmp.set_property("http://purl.org/dc/elements/1.1/", "creator", "John Doe")
377
378
# Iterate over properties
379
for schema, name, value, options in XMPIterator(xmp):
380
print(f"{schema}:{name} = {value}")
381
382
# Serialize to string
383
xmp_packet = xmp.serialize_to_str()
384
print(xmp_packet)
385
386
# Parse from string
387
new_xmp = XMPMeta()
388
new_xmp.parse_from_str(xmp_packet)
389
```