1Using Python XMP Toolkit
2============================
3
4This little tutorial will show you two different methods for how to
5read/write XMP documents from files as well as manipulate them metadata
6once extracted from the file.
7
8The tutorial is meant to be understood without prior knowledge of
9XMP. However, readers who decides to use the library are strongly
10encouraged to gain basic knowledge and understanding of:
11
12  * XMP Data Model
13  * XMP Serialization
14
15A basic understanding of these two concepts can save yourself from common
16misunderstandings of what XMP is and what XMP can do. Good resources
17are e.g. the wiki page or the XMP Specification Part 1 available from:
18
19 * http://en.wikipedia.org/wiki/Extensible_Metadata_Platform
20 * http://www.adobe.com/devnet/xmp/
21
22Method 1: Read XMP
23------------------
24One of the most basic uses of the library is:
25
26>>> from libxmp.utils import file_to_dict
27>>> xmp = file_to_dict( "test/samples/BlueSquare.xmp" )
28
29
30This will read the XMP embedded in the file and return it as a
31dictionary. The keys in the dictionary are XMP namespaces so to e.g. get
32all Dublin Core properties use:
33
34
35>>> from libxmp import consts
36>>> dc = xmp[consts.XMP_NS_DC]
37
38or to be explicit:
39
40>>> dc = xmp["http://purl.org/dc/elements/1.1/"]
41
42This will give you a list of all Dublin Core properties, where each
43element in the list is a tuple. The first element is the property name,
44the second element is the value and the third element is options associated
45with the element (describing e.g the type of the property):
46
47First tuple element:
48
49>>> print(dc[0][0])
50dc:format
51
52Second tuple element:
53
54>>> print(dc[0][1])
55application/vnd.adobe.photoshop
56
57Third tuple element is a dict with options:
58
59>>> dc[0][2]['IS_SCHEMA']
60False
61
62Method 2: Read/Write XMP
63------------------------
64Example 1 focused on just extracting the XMP from a file an determine the
65value of a property. If you however want to extract the XMP from a file,
66update it, *and* write it back again you need to do like the following
67
68Read file:
69
70>>> from libxmp import XMPFiles, consts
71>>> xmpfile = XMPFiles( file_path="test/samples/BlueSquare.jpg", open_forupdate=True )
72
73Get XMP from file:
74
75>>> xmp = xmpfile.get_xmp()
76
77Print the property ``dc:format``:
78
79>>> print(xmp.get_property(consts.XMP_NS_DC, 'format' ))
80image/jpeg
81
82Change the XMP property:
83
84>>> xmp.set_property(consts.XMP_NS_DC, u'format', u'application/vnd.adobe.illustrator' )
85>>> print(xmp.get_property(consts.XMP_NS_DC, 'format' ))
86application/vnd.adobe.illustrator
87
88Check if XMP document can be written to file and write it:
89
90>>> xmpfile.can_put_xmp(xmp)
91True
92
93XMP document is not written to the file, before the file
94is closed:
95
96>>> xmpfile.close_file()
97
98Further Examples
99-------------
100Append an array item to the XMP packet.::
101
102Read file:
103
104>>> from libxmp import XMPFiles, consts
105>>> xmpfile = XMPFiles( file_path="test/samples/BlueSquare.xmp" )
106
107Get XMP from file:
108
109>>> xmp = xmpfile.get_xmp()
110
111Create a new array item and append a value:
112
113>>> xmp.append_array_item(consts.XMP_NS_DC, 'creator', 'Your Name Here', {'prop_array_is_ordered': True, 'prop_value_is_array': True})
114