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. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 6 | .. moduleauthor:: Jack Jansen |
| 7 | .. sectionauthor:: Georg Brandl <georg@python.org> |
| 8 | .. (harvested from docstrings in the original file) |
| 9 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 10 | .. index:: |
| 11 | pair: plist; file |
| 12 | single: property list |
| 13 | |
Raymond Hettinger | 469271d | 2011-01-27 20:38:46 +0000 | [diff] [blame] | 14 | **Source code:** :source:`Lib/plistlib.py` |
| 15 | |
| 16 | -------------- |
| 17 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 18 | This module provides an interface for reading and writing the "property list" |
Georg Brandl | c575c90 | 2008-09-13 17:46:05 +0000 | [diff] [blame] | 19 | XML files used mainly by Mac OS X. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 20 | |
| 21 | The property list (``.plist``) file format is a simple XML pickle supporting |
| 22 | basic object types, like dictionaries, lists, numbers and strings. Usually the |
| 23 | top level object is a dictionary. |
| 24 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 25 | To write out and to parse a plist file, use the :func:`writePlist` and |
| 26 | :func:`readPlist` functions. |
| 27 | |
| 28 | To work with plist data in bytes objects, use :func:`writePlistToBytes` |
| 29 | and :func:`readPlistFromBytes`. |
| 30 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 31 | Values can be strings, integers, floats, booleans, tuples, lists, dictionaries |
| 32 | (but only with string keys), :class:`Data` or :class:`datetime.datetime` |
Ezio Melotti | dc2b8ec | 2009-09-13 08:01:06 +0000 | [diff] [blame] | 33 | objects. String values (including dictionary keys) have to be unicode strings -- |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 34 | they will be written out as UTF-8. |
| 35 | |
| 36 | The ``<data>`` plist type is supported through the :class:`Data` class. This is |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 37 | a thin wrapper around a Python bytes object. Use :class:`Data` if your strings |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 38 | contain control characters. |
| 39 | |
| 40 | .. seealso:: |
| 41 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 42 | `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_ |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 43 | Apple's documentation of the file format. |
| 44 | |
| 45 | |
| 46 | This module defines the following functions: |
| 47 | |
| 48 | .. function:: readPlist(pathOrFile) |
| 49 | |
| 50 | Read a plist file. *pathOrFile* may either be a file name or a (readable) |
| 51 | file object. Return the unpacked root object (which usually is a |
| 52 | dictionary). |
| 53 | |
| 54 | The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat` |
| 55 | -- see its documentation for possible exceptions on ill-formed XML. |
| 56 | Unknown elements will simply be ignored by the plist parser. |
| 57 | |
| 58 | |
| 59 | .. function:: writePlist(rootObject, pathOrFile) |
| 60 | |
| 61 | Write *rootObject* to a plist file. *pathOrFile* may either be a file name |
| 62 | or a (writable) file object. |
| 63 | |
| 64 | A :exc:`TypeError` will be raised if the object is of an unsupported type or |
| 65 | a container that contains objects of unsupported types. |
| 66 | |
| 67 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 68 | .. function:: readPlistFromBytes(data) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 69 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 70 | Read a plist data from a bytes object. Return the root object. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 71 | |
| 72 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 73 | .. function:: writePlistToBytes(rootObject) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 74 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 75 | Return *rootObject* as a plist-formatted bytes object. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 76 | |
| 77 | |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 78 | The following class is available: |
| 79 | |
| 80 | .. class:: Data(data) |
| 81 | |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 82 | Return a "data" wrapper object around the bytes object *data*. This is used |
| 83 | in functions converting from/to plists to represent the ``<data>`` type |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 84 | available in plists. |
| 85 | |
| 86 | 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] | 87 | bytes object stored in it. |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 88 | |
| 89 | |
| 90 | Examples |
| 91 | -------- |
| 92 | |
| 93 | Generating a plist:: |
| 94 | |
| 95 | pl = dict( |
Ezio Melotti | 985e24d | 2009-09-13 07:54:02 +0000 | [diff] [blame] | 96 | aString = "Doodah", |
| 97 | aList = ["A", "B", 12, 32.1, [1, 2, 3]], |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 98 | aFloat = 0.1, |
| 99 | anInt = 728, |
Ezio Melotti | 985e24d | 2009-09-13 07:54:02 +0000 | [diff] [blame] | 100 | aDict = dict( |
| 101 | anotherString = "<hello & hi there!>", |
| 102 | aThirdString = "M\xe4ssig, Ma\xdf", |
| 103 | aTrueValue = True, |
| 104 | aFalseValue = False, |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 105 | ), |
Ezio Melotti | 6e9b1df | 2009-09-16 00:49:03 +0000 | [diff] [blame] | 106 | someData = Data(b"<binary gunk>"), |
| 107 | someMoreData = Data(b"<lots of binary gunk>" * 10), |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 108 | aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())), |
| 109 | ) |
Georg Brandl | 86def6c | 2008-01-21 20:36:10 +0000 | [diff] [blame] | 110 | writePlist(pl, fileName) |
| 111 | |
| 112 | Parsing a plist:: |
| 113 | |
| 114 | pl = readPlist(pathOrFile) |
Neal Norwitz | 752abd0 | 2008-05-13 04:55:24 +0000 | [diff] [blame] | 115 | print(pl["aKey"]) |