1 :mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files
2 ================================================================
5 :synopsis: Generate and parse Mac OS X plist files.
6 .. moduleauthor:: Jack Jansen
7 .. sectionauthor:: Georg Brandl <georg@python.org>
8 .. (harvested from docstrings in the original file)
10 .. versionchanged:: 2.6
11 This module was previously only available in the Mac-specific library, it is
12 now available for all platforms.
18 This module provides an interface for reading and writing the "property list"
19 XML files used mainly by Mac OS X.
21 The property list (``.plist``) file format is a simple XML pickle supporting
22 basic object types, like dictionaries, lists, numbers and strings. Usually the
23 top level object is a dictionary.
25 Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
26 (but only with string keys), :class:`Data` or :class:`datetime.datetime`
27 objects. String values (including dictionary keys) may be unicode strings --
28 they will be written out as UTF-8.
30 The ``<data>`` plist type is supported through the :class:`Data` class. This is
31 a thin wrapper around a Python string. Use :class:`Data` if your strings
32 contain control characters.
36 `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
37 Apple's documentation of the file format.
40 This module defines the following functions:
42 .. function:: readPlist(pathOrFile)
44 Read a plist file. *pathOrFile* may either be a file name or a (readable)
45 file object. Return the unpacked root object (which usually is a
48 The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`
49 -- see its documentation for possible exceptions on ill-formed XML.
50 Unknown elements will simply be ignored by the plist parser.
53 .. function:: writePlist(rootObject, pathOrFile)
55 Write *rootObject* to a plist file. *pathOrFile* may either be a file name
56 or a (writable) file object.
58 A :exc:`TypeError` will be raised if the object is of an unsupported type or
59 a container that contains objects of unsupported types.
62 .. function:: readPlistFromString(data)
64 Read a plist from a string. Return the root object.
67 .. function:: writePlistToString(rootObject)
69 Return *rootObject* as a plist-formatted string.
73 .. function:: readPlistFromResource(path[, restype='plst'[, resid=0]])
75 Read a plist from the resource with type *restype* from the resource fork of
76 *path*. Availability: Mac OS X.
80 In Python 3.x, this function has been removed.
83 .. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])
85 Write *rootObject* as a resource with type *restype* to the resource fork of
86 *path*. Availability: Mac OS X.
90 In Python 3.x, this function has been removed.
94 The following class is available:
98 Return a "data" wrapper object around the string *data*. This is used in
99 functions converting from/to plists to represent the ``<data>`` type
102 It has one attribute, :attr:`data`, that can be used to retrieve the Python
113 aList=["A", "B", 12, 32.1, [1, 2, 3]],
117 anotherString="<hello & hi there!>",
118 aUnicodeValue=u'M\xe4ssig, Ma\xdf',
122 someData = Data("<binary gunk>"),
123 someMoreData = Data("<lots of binary gunk>" * 10),
124 aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
126 # unicode keys are possible, but a little awkward to use:
127 pl[u'\xc5benraa'] = "That was a unicode key."
128 writePlist(pl, fileName)
132 pl = readPlist(pathOrFile)