Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 1 | :mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files |
| 2 | ================================================================ |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 3 | |
| 4 | .. module:: plistlib |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 5 | :synopsis: Generate and parse Mac OS X plist files. |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 6 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 7 | .. moduleauthor:: Jack Jansen |
| 8 | .. sectionauthor:: Georg Brandl <georg@python.org> |
| 9 | .. (harvested from docstrings in the original file) |
| 10 | |
Terry Jan Reedy | fa089b9 | 2016-06-11 15:02:54 -0400 | [diff] [blame] | 11 | **Source code:** :source:`Lib/plistlib.py` |
| 12 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 13 | .. index:: |
| 14 | pair: plist; file |
| 15 | single: property list |
| 16 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 17 | -------------- |
| 18 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 19 | This module provides an interface for reading and writing the "property list" |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 20 | files used mainly by Mac OS X and supports both binary and XML plist files. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 21 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 22 | The property list (``.plist``) file format is a simple serialization supporting |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 23 | basic object types, like dictionaries, lists, numbers and strings. Usually the |
| 24 | top level object is a dictionary. |
| 25 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 26 | To write out and to parse a plist file, use the :func:`dump` and |
| 27 | :func:`load` functions. |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 28 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 29 | To work with plist data in bytes objects, use :func:`dumps` |
| 30 | and :func:`loads`. |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 31 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 32 | Values can be strings, integers, floats, booleans, tuples, lists, dictionaries |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 33 | (but only with string keys), :class:`Data`, :class:`bytes`, :class:`bytesarray` |
| 34 | or :class:`datetime.datetime` objects. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 35 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 36 | .. versionchanged:: 3.4 |
| 37 | New API, old API deprecated. Support for binary format plists added. |
| 38 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 39 | .. seealso:: |
| 40 | |
Georg Brandl | 525d355 | 2014-10-29 10:26:56 +0100 | [diff] [blame] | 41 | `PList manual page <https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_ |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 42 | Apple's documentation of the file format. |
| 43 | |
| 44 | |
| 45 | This module defines the following functions: |
| 46 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 47 | .. function:: load(fp, \*, fmt=None, use_builtin_types=True, dict_type=dict) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 48 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 49 | Read a plist file. *fp* should be a readable and binary file object. |
| 50 | Return the unpacked root object (which usually is a |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 51 | dictionary). |
| 52 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Serhiy Storchaka | 0e90e99 | 2013-11-29 12:19:53 +0200 | [diff] [blame] | 61 | If *use_builtin_types* is true (the default) binary data will be returned |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Ronald Oussoren | 6db6653 | 2014-01-15 11:32:35 +0100 | [diff] [blame] | 86 | .. versionadded:: 3.4 |
| 87 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Ronald Oussoren | 6db6653 | 2014-01-15 11:32:35 +0100 | [diff] [blame] | 111 | An :exc:`OverflowError` will be raised for integer values that cannot |
| 112 | be represented in (binary) plist files. |
| 113 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 114 | .. versionadded:: 3.4 |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 123 | .. versionadded:: 3.4 |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Senthil Kumaran | b4760ef | 2015-06-14 17:35:37 -0700 | [diff] [blame] | 133 | This function calls :func:`load` to do the actual work, see the documentation |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 142 | .. deprecated:: 3.4 Use :func:`load` instead. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 143 | |
| 144 | |
| 145 | .. function:: writePlist(rootObject, pathOrFile) |
| 146 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 147 | Write *rootObject* to an XML plist file. *pathOrFile* may be either a file name |
| 148 | or a (writable and binary) file object |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 149 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 150 | .. deprecated:: 3.4 Use :func:`dump` instead. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 151 | |
| 152 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 153 | .. function:: readPlistFromBytes(data) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 154 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 155 | Read a plist data from a bytes object. Return the root object. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 156 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 167 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 168 | .. function:: writePlistToBytes(rootObject) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 169 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 170 | Return *rootObject* as an XML plist-formatted bytes object. |
| 171 | |
| 172 | .. deprecated:: 3.4 Use :func:`dumps` instead. |
| 173 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 174 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 188 | |
| 189 | .. class:: Data(data) |
| 190 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 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 |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 193 | available in plists. |
| 194 | |
| 195 | It has one attribute, :attr:`data`, that can be used to retrieve the Python |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 196 | bytes object stored in it. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 197 | |
Martin Panter | d21e0b5 | 2015-10-10 10:36:22 +0000 | [diff] [blame] | 198 | .. deprecated:: 3.4 Use a :class:`bytes` object instead. |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 199 | |
| 200 | |
Larry Hastings | 3732ed2 | 2014-03-15 21:13:56 -0700 | [diff] [blame] | 201 | The following constants are available: |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 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 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 216 | |
| 217 | Examples |
| 218 | -------- |
| 219 | |
| 220 | Generating a plist:: |
| 221 | |
| 222 | pl = dict( |
Ezio Melotti | 985e24d | 2009-09-13 07:54:02 +0000 | [diff] [blame] | 223 | aString = "Doodah", |
| 224 | aList = ["A", "B", 12, 32.1, [1, 2, 3]], |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 225 | aFloat = 0.1, |
| 226 | anInt = 728, |
Ezio Melotti | 985e24d | 2009-09-13 07:54:02 +0000 | [diff] [blame] | 227 | aDict = dict( |
| 228 | anotherString = "<hello & hi there!>", |
| 229 | aThirdString = "M\xe4ssig, Ma\xdf", |
| 230 | aTrueValue = True, |
| 231 | aFalseValue = False, |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 232 | ), |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 233 | someData = b"<binary gunk>", |
| 234 | someMoreData = b"<lots of binary gunk>" * 10, |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 235 | aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())), |
| 236 | ) |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 237 | with open(fileName, 'wb') as fp: |
| 238 | dump(pl, fp) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 239 | |
| 240 | Parsing a plist:: |
| 241 | |
Ronald Oussoren | c5cf797 | 2013-11-21 15:46:49 +0100 | [diff] [blame] | 242 | with open(fileName, 'rb') as fp: |
| 243 | pl = load(fp) |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 244 | print(pl["aKey"]) |