|
| 1 | +:mod:`plistlib` --- Generate and parse MacOS X ``.plist`` files |
| 2 | +=============================================================== |
| 3 | + |
| 4 | +.. module:: plistlib |
| 5 | + :synopsis: Generate and parse MacOS X plist files. |
| 6 | +.. moduleauthor:: Jack Jansen |
| 7 | +.. sectionauthor:: Georg Brandl <[email protected]> |
| 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 | +This module provides an interface for reading and writing the "property list" |
| 19 | +XML files used mainly by MacOS X. |
| 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 | + |
| 25 | +Values can be strings, integers, floats, booleans, tuples, lists, dictionaries |
| 26 | +(but only with string keys), :class:`Data` or :class:`datetime.datetime` |
| 27 | +objects. String values (including dictionary keys) may be unicode strings -- |
| 28 | +they will be written out as UTF-8. |
| 29 | + |
| 30 | +The ``<data>`` plist type is supported through the :class:`Data` class. This is |
| 31 | +a thin wrapper around a Python string. Use :class:`Data` if your strings |
| 32 | +contain control characters. |
| 33 | + |
| 34 | +.. seealso:: |
| 35 | + |
| 36 | + `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>` |
| 37 | + Apple's documentation of the file format. |
| 38 | + |
| 39 | + |
| 40 | +This module defines the following functions: |
| 41 | + |
| 42 | +.. function:: readPlist(pathOrFile) |
| 43 | + |
| 44 | + Read a plist file. *pathOrFile* may either be a file name or a (readable) |
| 45 | + file object. Return the unpacked root object (which usually is a |
| 46 | + dictionary). |
| 47 | + |
| 48 | + The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat` |
| 49 | + -- see its documentation for possible exceptions on ill-formed XML. |
| 50 | + Unknown elements will simply be ignored by the plist parser. |
| 51 | + |
| 52 | + |
| 53 | +.. function:: writePlist(rootObject, pathOrFile) |
| 54 | + |
| 55 | + Write *rootObject* to a plist file. *pathOrFile* may either be a file name |
| 56 | + or a (writable) file object. |
| 57 | + |
| 58 | + A :exc:`TypeError` will be raised if the object is of an unsupported type or |
| 59 | + a container that contains objects of unsupported types. |
| 60 | + |
| 61 | + |
| 62 | +.. function:: readPlistFromString(data) |
| 63 | + |
| 64 | + Read a plist from a string. Return the root object. |
| 65 | + |
| 66 | + |
| 67 | +.. function:: writePlistToString(rootObject) |
| 68 | + |
| 69 | + Return *rootObject* as a plist-formatted string. |
| 70 | + |
| 71 | + |
| 72 | + |
| 73 | +.. function:: readPlistFromResource(path[, restype='plst'[, resid=0]]) |
| 74 | + |
| 75 | + Read a plist from the resource with type *restype* from the resource fork of |
| 76 | + *path*. Availability: MacOS X. |
| 77 | + |
| 78 | + |
| 79 | +.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]]) |
| 80 | + |
| 81 | + Write *rootObject* as a resource with type *restype* to the resource fork of |
| 82 | + *path*. Availability: MacOS X. |
| 83 | + |
| 84 | + |
| 85 | +The following class is available: |
| 86 | + |
| 87 | +.. class:: Data(data) |
| 88 | + |
| 89 | + Return a "data" wrapper object around the string *data*. This is used in |
| 90 | + functions converting from/to plists to represent the ``<data>`` type |
| 91 | + available in plists. |
| 92 | + |
| 93 | + It has one attribute, :attr:`data`, that can be used to retrieve the Python |
| 94 | + string stored in it. |
| 95 | + |
| 96 | + |
| 97 | +Examples |
| 98 | +-------- |
| 99 | + |
| 100 | +Generating a plist:: |
| 101 | + |
| 102 | + pl = dict( |
| 103 | + aString="Doodah", |
| 104 | + aList=["A", "B", 12, 32.1, [1, 2, 3]], |
| 105 | + aFloat = 0.1, |
| 106 | + anInt = 728, |
| 107 | + aDict=dict( |
| 108 | + anotherString="<hello & hi there!>", |
| 109 | + aUnicodeValue=u'M\xe4ssig, Ma\xdf', |
| 110 | + aTrueValue=True, |
| 111 | + aFalseValue=False, |
| 112 | + ), |
| 113 | + someData = Data("<binary gunk>"), |
| 114 | + someMoreData = Data("<lots of binary gunk>" * 10), |
| 115 | + aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())), |
| 116 | + ) |
| 117 | + # unicode keys are possible, but a little awkward to use: |
| 118 | + pl[u'\xc5benraa'] = "That was a unicode key." |
| 119 | + writePlist(pl, fileName) |
| 120 | + |
| 121 | +Parsing a plist:: |
| 122 | + |
| 123 | + pl = readPlist(pathOrFile) |
| 124 | + print pl["aKey"] |
0 commit comments