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 7 .. moduleauthor:: Jack Jansen 8 .. sectionauthor:: Georg Brandl <georg (a] python.org> 9 .. (harvested from docstrings in the original file) 10 11 **Source code:** :source:`Lib/plistlib.py` 12 13 .. index:: 14 pair: plist; file 15 single: property list 16 17 -------------- 18 19 This module provides an interface for reading and writing the "property list" 20 files used mainly by Mac OS X and supports both binary and XML plist files. 21 22 The property list (``.plist``) file format is a simple serialization supporting 23 basic object types, like dictionaries, lists, numbers and strings. Usually the 24 top level object is a dictionary. 25 26 To write out and to parse a plist file, use the :func:`dump` and 27 :func:`load` functions. 28 29 To work with plist data in bytes objects, use :func:`dumps` 30 and :func:`loads`. 31 32 Values can be strings, integers, floats, booleans, tuples, lists, dictionaries 33 (but only with string keys), :class:`Data`, :class:`bytes`, :class:`bytesarray` 34 or :class:`datetime.datetime` objects. 35 36 .. versionchanged:: 3.4 37 New API, old API deprecated. Support for binary format plists added. 38 39 .. seealso:: 40 41 `PList manual page <https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_ 42 Apple's documentation of the file format. 43 44 45 This module defines the following functions: 46 47 .. function:: load(fp, \*, fmt=None, use_builtin_types=True, dict_type=dict) 48 49 Read a plist file. *fp* should be a readable and binary file object. 50 Return the unpacked root object (which usually is a 51 dictionary). 52 53 The *fmt* is the format of the file and the following values are valid: 54 55 * :data:`None`: Autodetect the file format 56 57 * :data:`FMT_XML`: XML file format 58 59 * :data:`FMT_BINARY`: Binary plist format 60 61 If *use_builtin_types* is true (the default) binary data will be returned 62 as instances of :class:`bytes`, otherwise it is returned as instances of 63 :class:`Data`. 64 65 The *dict_type* is the type used for dictionaries that are read from the 66 plist file. The exact structure of the plist can be recovered by using 67 :class:`collections.OrderedDict` (although the order of keys shouldn't be 68 important in plist files). 69 70 XML data for the :data:`FMT_XML` format is parsed using the Expat parser 71 from :mod:`xml.parsers.expat` -- see its documentation for possible 72 exceptions on ill-formed XML. Unknown elements will simply be ignored 73 by the plist parser. 74 75 The parser for the binary format raises :exc:`InvalidFileException` 76 when the file cannot be parsed. 77 78 .. versionadded:: 3.4 79 80 81 .. function:: loads(data, \*, fmt=None, use_builtin_types=True, dict_type=dict) 82 83 Load a plist from a bytes object. See :func:`load` for an explanation of 84 the keyword arguments. 85 86 .. versionadded:: 3.4 87 88 89 .. function:: dump(value, fp, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False) 90 91 Write *value* to a plist file. *Fp* should be a writable, binary 92 file object. 93 94 The *fmt* argument specifies the format of the plist file and can be 95 one of the following values: 96 97 * :data:`FMT_XML`: XML formatted plist file 98 99 * :data:`FMT_BINARY`: Binary formatted plist file 100 101 When *sort_keys* is true (the default) the keys for dictionaries will be 102 written to the plist in sorted order, otherwise they will be written in 103 the iteration order of the dictionary. 104 105 When *skipkeys* is false (the default) the function raises :exc:`TypeError` 106 when a key of a dictionary is not a string, otherwise such keys are skipped. 107 108 A :exc:`TypeError` will be raised if the object is of an unsupported type or 109 a container that contains objects of unsupported types. 110 111 An :exc:`OverflowError` will be raised for integer values that cannot 112 be represented in (binary) plist files. 113 114 .. versionadded:: 3.4 115 116 117 .. function:: dumps(value, \*, fmt=FMT_XML, sort_keys=True, skipkeys=False) 118 119 Return *value* as a plist-formatted bytes object. See 120 the documentation for :func:`dump` for an explanation of the keyword 121 arguments of this function. 122 123 .. versionadded:: 3.4 124 125 The following functions are deprecated: 126 127 .. function:: readPlist(pathOrFile) 128 129 Read a plist file. *pathOrFile* may be either a file name or a (readable 130 and binary) file object. Returns the unpacked root object (which usually 131 is a dictionary). 132 133 This function calls :func:`load` to do the actual work, see the documentation 134 of :func:`that function <load>` for an explanation of the keyword arguments. 135 136 .. note:: 137 138 Dict values in the result have a ``__getattr__`` method that defers 139 to ``__getitem_``. This means that you can use attribute access to 140 access items of these dictionaries. 141 142 .. deprecated:: 3.4 Use :func:`load` instead. 143 144 145 .. function:: writePlist(rootObject, pathOrFile) 146 147 Write *rootObject* to an XML plist file. *pathOrFile* may be either a file name 148 or a (writable and binary) file object 149 150 .. deprecated:: 3.4 Use :func:`dump` instead. 151 152 153 .. function:: readPlistFromBytes(data) 154 155 Read a plist data from a bytes object. Return the root object. 156 157 See :func:`load` for a description of the keyword arguments. 158 159 .. note:: 160 161 Dict values in the result have a ``__getattr__`` method that defers 162 to ``__getitem_``. This means that you can use attribute access to 163 access items of these dictionaries. 164 165 .. deprecated:: 3.4 Use :func:`loads` instead. 166 167 168 .. function:: writePlistToBytes(rootObject) 169 170 Return *rootObject* as an XML plist-formatted bytes object. 171 172 .. deprecated:: 3.4 Use :func:`dumps` instead. 173 174 175 The following classes are available: 176 177 .. class:: Dict([dict]): 178 179 Return an extended mapping object with the same value as dictionary 180 *dict*. 181 182 This class is a subclass of :class:`dict` where attribute access can 183 be used to access items. That is, ``aDict.key`` is the same as 184 ``aDict['key']`` for getting, setting and deleting items in the mapping. 185 186 .. deprecated:: 3.0 187 188 189 .. class:: Data(data) 190 191 Return a "data" wrapper object around the bytes object *data*. This is used 192 in functions converting from/to plists to represent the ``<data>`` type 193 available in plists. 194 195 It has one attribute, :attr:`data`, that can be used to retrieve the Python 196 bytes object stored in it. 197 198 .. deprecated:: 3.4 Use a :class:`bytes` object instead. 199 200 201 The following constants are available: 202 203 .. data:: FMT_XML 204 205 The XML format for plist files. 206 207 .. versionadded:: 3.4 208 209 210 .. data:: FMT_BINARY 211 212 The binary format for plist files 213 214 .. versionadded:: 3.4 215 216 217 Examples 218 -------- 219 220 Generating a plist:: 221 222 pl = dict( 223 aString = "Doodah", 224 aList = ["A", "B", 12, 32.1, [1, 2, 3]], 225 aFloat = 0.1, 226 anInt = 728, 227 aDict = dict( 228 anotherString = "<hello & hi there!>", 229 aThirdString = "M\xe4ssig, Ma\xdf", 230 aTrueValue = True, 231 aFalseValue = False, 232 ), 233 someData = b"<binary gunk>", 234 someMoreData = b"<lots of binary gunk>" * 10, 235 aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())), 236 ) 237 with open(fileName, 'wb') as fp: 238 dump(pl, fp) 239 240 Parsing a plist:: 241 242 with open(fileName, 'rb') as fp: 243 pl = load(fp) 244 print(pl["aKey"]) 245
