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