0
# Python XMP Toolkit
1

2
A Python library for working with XMP (Extensible Metadata Platform) metadata in files. This library provides a comprehensive interface for reading, writing, and manipulating XMP metadata stored in various file formats through a Python wrapper around the Exempi library.
3

4
## Package Information
5

6
- **Package Name**: python-xmp-toolkit
7
- **Language**: Python
8
- **Installation**: `pip install python-xmp-toolkit`
9
- **Version**: 2.0.1
10
- **License**: BSD
11

12
## Core Imports
13

14
```python
15
import libxmp
16
```
17

18
Common imports for working with XMP metadata:
19

20
```python
21
from libxmp import XMPMeta, XMPFiles, XMPError
22
```
23

24
## Basic Usage
25

26
```python
27
from libxmp import XMPMeta, XMPFiles
28

29
# Working with XMP metadata in memory
30
xmp = XMPMeta()
31
xmp.set_property("http://ns.adobe.com/xap/1.0/", "CreatorTool", "Python XMP Toolkit")
32
xmp.set_property("http://purl.org/dc/elements/1.1/", "creator", "John Doe")
33

34
# Serialize XMP to string
35
xmp_str = xmp.serialize_to_str()
36
print(xmp_str)
37

38
# Working with files
39
xmpfile = XMPFiles(file_path="example.jpg")
40
xmp_data = xmpfile.get_xmp()
41
if xmp_data:
42
    creator = xmp_data.get_property("http://purl.org/dc/elements/1.1/", "creator")
43
    print(f"Creator: {creator}")
44
xmpfile.close_file()
45
```
46

47
## Architecture
48

49
The library provides three main layers of XMP metadata access:
50

51
- **XMPMeta**: Core metadata object for parsing, manipulating, and serializing XMP data
52
- **XMPFiles**: File-based XMP access with smart handlers for different file formats  
53
- **Exempi Interface**: Low-level ctypes interface to the underlying Exempi C library
54

55
This design enables both high-level object-oriented operations and fine-grained control over XMP metadata processing, supporting the complete XMP specification including arrays, structures, localized text, and standard namespace handling.
56

57
## Capabilities
58

59
### Core Metadata Operations
60

61
XMP metadata parsing, manipulation, and serialization with support for all XMP data types including simple properties, arrays, structures, and localized text. Provides comprehensive property access methods and namespace management.
62

63
```python { .api }
64
class XMPMeta:
65
    def __init__(self, **kwargs): ...
66
    def get_property(self, schema_ns, prop_name): ...
67
    def set_property(self, schema_ns, prop_name, prop_value, **kwargs): ...
68
    def serialize_to_str(self, padding=0, **kwargs): ...
69
    def parse_from_str(self, xmp_packet_str, xmpmeta_wrap=False, input_encoding=None): ...
70
```
71

72
[Core Metadata Operations](./core-metadata.md)
73

74
### File Operations
75

76
File-based XMP metadata access with smart handlers for various file formats. Provides convenient reading and writing of XMP metadata directly from image files, PDFs, and other supported formats.
77

78
```python { .api }
79
class XMPFiles:
80
    def __init__(self, **kwargs): ...
81
    def open_file(self, file_path, **kwargs): ...
82
    def get_xmp(self): ...
83
    def put_xmp(self, xmp_obj): ...
84
    def close_file(self, close_flags=0): ...
85
```
86

87
[File Operations](./file-operations.md)
88

89
### Utilities and Constants
90

91
Utility functions for extracting XMP data to Python dictionaries, comprehensive XMP constants for namespaces and options, and library management functions.
92

93
```python { .api }
94
def object_to_dict(xmp): ...
95
def file_to_dict(file_path): ...
96
def terminate(): ...
97
```
98

99
[Utilities and Constants](./utilities.md)
100

101
## Exception Handling
102

103
```python { .api }
104
class XMPError(Exception):
105
    """General XMP Error for all XMP-related operations"""
106

107
class ExempiLoadError(Exception):
108
    """Error signaling that the Exempi library cannot be loaded"""
109
```
110

111
Common error handling pattern:
112

113
```python
114
from libxmp import XMPFiles, XMPError
115

116
try:
117
    xmpfile = XMPFiles(file_path="example.jpg")
118
    xmp_data = xmpfile.get_xmp()
119
    # ... work with XMP data
120
except XMPError as e:
121
    print(f"XMP operation failed: {e}")
122
finally:
123
    if 'xmpfile' in locals():
124
        xmpfile.close_file()
125
```