1:mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files
2================================================================
3
4.. module:: plistlib
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)
9
10.. versionchanged:: 2.6
11   This module was previously only available in the Mac-specific library, it is
12   now available for all platforms.
13
14.. index::
15   pair: plist; file
16   single: property list
17
18**Source code:** :source:`Lib/plistlib.py`
19
20--------------
21
22This module provides an interface for reading and writing the "property list"
23XML files used mainly by Mac OS X.
24
25The property list (``.plist``) file format is a simple XML pickle supporting
26basic object types, like dictionaries, lists, numbers and strings.  Usually the
27top level object is a dictionary.
28
29Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
30(but only with string keys), :class:`Data` or :class:`datetime.datetime`
31objects.  String values (including dictionary keys) may be unicode strings --
32they will be written out as UTF-8.
33
34The ``<data>`` plist type is supported through the :class:`Data` class.  This is
35a thin wrapper around a Python string.  Use :class:`Data` if your strings
36contain control characters.
37
38.. seealso::
39
40   `PList manual page <https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
41      Apple's documentation of the file format.
42
43
44This module defines the following functions:
45
46.. function:: readPlist(pathOrFile)
47
48   Read a plist file. *pathOrFile* may either be a file name or a (readable)
49   file object.  Return the unpacked root object (which usually is a
50   dictionary).
51
52   The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`
53   -- see its documentation for possible exceptions on ill-formed XML.
54   Unknown elements will simply be ignored by the plist parser.
55
56
57.. function:: writePlist(rootObject, pathOrFile)
58
59    Write *rootObject* to a plist file. *pathOrFile* may either be a file name
60    or a (writable) file object.
61
62    A :exc:`TypeError` will be raised if the object is of an unsupported type or
63    a container that contains objects of unsupported types.
64
65
66.. function:: readPlistFromString(data)
67
68   Read a plist from a string.  Return the root object.
69
70
71.. function:: writePlistToString(rootObject)
72
73   Return *rootObject* as a plist-formatted string.
74
75
76
77.. function:: readPlistFromResource(path, restype='plst', resid=0)
78
79    Read a plist from the resource with type *restype* from the resource fork of
80    *path*.  Availability: Mac OS X.
81
82    .. note::
83
84       In Python 3.x, this function has been removed.
85
86
87.. function:: writePlistToResource(rootObject, path, restype='plst', resid=0)
88
89    Write *rootObject* as a resource with type *restype* to the resource fork of
90    *path*.  Availability: Mac OS X.
91
92    .. note::
93
94       In Python 3.x, this function has been removed.
95
96
97
98The following class is available:
99
100.. class:: Data(data)
101
102   Return a "data" wrapper object around the string *data*.  This is used in
103   functions converting from/to plists to represent the ``<data>`` type
104   available in plists.
105
106   It has one attribute, :attr:`data`, that can be used to retrieve the Python
107   string stored in it.
108
109
110Examples
111--------
112
113Generating a plist::
114
115    pl = dict(
116        aString="Doodah",
117        aList=["A", "B", 12, 32.1, [1, 2, 3]],
118        aFloat = 0.1,
119        anInt = 728,
120        aDict=dict(
121            anotherString="<hello & hi there!>",
122            aUnicodeValue=u'M\xe4ssig, Ma\xdf',
123            aTrueValue=True,
124            aFalseValue=False,
125        ),
126        someData = Data("<binary gunk>"),
127        someMoreData = Data("<lots of binary gunk>" * 10),
128        aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
129    )
130    # unicode keys are possible, but a little awkward to use:
131    pl[u'\xc5benraa'] = "That was a unicode key."
132    writePlist(pl, fileName)
133
134Parsing a plist::
135
136    pl = readPlist(pathOrFile)
137    print pl["aKey"]
138