1:mod:`!plistlib` --- Generate and parse Apple ``.plist`` files 2============================================================== 3 4.. module:: plistlib 5 :synopsis: Generate and parse Apple plist files. 6 7.. moduleauthor:: Jack Jansen 8.. sectionauthor:: Georg Brandl <georg@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 19This module provides an interface for reading and writing the "property list" 20files used by Apple, primarily on macOS and iOS. This module supports both binary 21and XML plist files. 22 23The property list (``.plist``) file format is a simple serialization supporting 24basic object types, like dictionaries, lists, numbers and strings. Usually the 25top level object is a dictionary. 26 27To write out and to parse a plist file, use the :func:`dump` and 28:func:`load` functions. 29 30To work with plist data in bytes or string objects, use :func:`dumps` 31and :func:`loads`. 32 33Values can be strings, integers, floats, booleans, tuples, lists, dictionaries 34(but only with string keys), :class:`bytes`, :class:`bytearray` 35or :class:`datetime.datetime` objects. 36 37.. versionchanged:: 3.4 38 New API, old API deprecated. Support for binary format plists added. 39 40.. versionchanged:: 3.8 41 Support added for reading and writing :class:`UID` tokens in binary plists as used 42 by NSKeyedArchiver and NSKeyedUnarchiver. 43 44.. versionchanged:: 3.9 45 Old API removed. 46 47.. seealso:: 48 49 `PList manual page <https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/>`_ 50 Apple's documentation of the file format. 51 52 53This module defines the following functions: 54 55.. function:: load(fp, *, fmt=None, dict_type=dict, aware_datetime=False) 56 57 Read a plist file. *fp* should be a readable and binary file object. 58 Return the unpacked root object (which usually is a 59 dictionary). 60 61 The *fmt* is the format of the file and the following values are valid: 62 63 * :data:`None`: Autodetect the file format 64 65 * :data:`FMT_XML`: XML file format 66 67 * :data:`FMT_BINARY`: Binary plist format 68 69 The *dict_type* is the type used for dictionaries that are read from the 70 plist file. 71 72 When *aware_datetime* is true, fields with type ``datetime.datetime`` will 73 be created as :ref:`aware object <datetime-naive-aware>`, with 74 :attr:`!tzinfo` as :attr:`datetime.UTC`. 75 76 XML data for the :data:`FMT_XML` format is parsed using the Expat parser 77 from :mod:`xml.parsers.expat` -- see its documentation for possible 78 exceptions on ill-formed XML. Unknown elements will simply be ignored 79 by the plist parser. 80 81 The parser for the binary format raises :exc:`InvalidFileException` 82 when the file cannot be parsed. 83 84 .. versionadded:: 3.4 85 86 .. versionchanged:: 3.13 87 The keyword-only parameter *aware_datetime* has been added. 88 89 90.. function:: loads(data, *, fmt=None, dict_type=dict, aware_datetime=False) 91 92 Load a plist from a bytes or string object. See :func:`load` for an 93 explanation of the keyword arguments. 94 95 .. versionadded:: 3.4 96 97 .. versionchanged:: 3.13 98 *data* can be a string when *fmt* equals :data:`FMT_XML`. 99 100.. function:: dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False) 101 102 Write *value* to a plist file. *Fp* should be a writable, binary 103 file object. 104 105 The *fmt* argument specifies the format of the plist file and can be 106 one of the following values: 107 108 * :data:`FMT_XML`: XML formatted plist file 109 110 * :data:`FMT_BINARY`: Binary formatted plist file 111 112 When *sort_keys* is true (the default) the keys for dictionaries will be 113 written to the plist in sorted order, otherwise they will be written in 114 the iteration order of the dictionary. 115 116 When *skipkeys* is false (the default) the function raises :exc:`TypeError` 117 when a key of a dictionary is not a string, otherwise such keys are skipped. 118 119 When *aware_datetime* is true and any field with type ``datetime.datetime`` 120 is set as an :ref:`aware object <datetime-naive-aware>`, it will convert to 121 UTC timezone before writing it. 122 123 A :exc:`TypeError` will be raised if the object is of an unsupported type or 124 a container that contains objects of unsupported types. 125 126 An :exc:`OverflowError` will be raised for integer values that cannot 127 be represented in (binary) plist files. 128 129 .. versionadded:: 3.4 130 131 .. versionchanged:: 3.13 132 The keyword-only parameter *aware_datetime* has been added. 133 134 135.. function:: dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False, aware_datetime=False) 136 137 Return *value* as a plist-formatted bytes object. See 138 the documentation for :func:`dump` for an explanation of the keyword 139 arguments of this function. 140 141 .. versionadded:: 3.4 142 143 144The following classes are available: 145 146.. class:: UID(data) 147 148 Wraps an :class:`int`. This is used when reading or writing NSKeyedArchiver 149 encoded data, which contains UID (see PList manual). 150 151 It has one attribute, :attr:`data`, which can be used to retrieve the int value 152 of the UID. :attr:`data` must be in the range ``0 <= data < 2**64``. 153 154 .. versionadded:: 3.8 155 156 157The following constants are available: 158 159.. data:: FMT_XML 160 161 The XML format for plist files. 162 163 .. versionadded:: 3.4 164 165 166.. data:: FMT_BINARY 167 168 The binary format for plist files 169 170 .. versionadded:: 3.4 171 172 173Examples 174-------- 175 176Generating a plist:: 177 178 import datetime 179 import plistlib 180 181 pl = dict( 182 aString = "Doodah", 183 aList = ["A", "B", 12, 32.1, [1, 2, 3]], 184 aFloat = 0.1, 185 anInt = 728, 186 aDict = dict( 187 anotherString = "<hello & hi there!>", 188 aThirdString = "M\xe4ssig, Ma\xdf", 189 aTrueValue = True, 190 aFalseValue = False, 191 ), 192 someData = b"<binary gunk>", 193 someMoreData = b"<lots of binary gunk>" * 10, 194 aDate = datetime.datetime.now() 195 ) 196 print(plistlib.dumps(pl).decode()) 197 198Parsing a plist:: 199 200 import plistlib 201 202 plist = b"""<plist version="1.0"> 203 <dict> 204 <key>foo</key> 205 <string>bar</string> 206 </dict> 207 </plist>""" 208 pl = plistlib.loads(plist) 209 print(pl["foo"]) 210