Doc/library/plistlib.rst

   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 .. moduleauthor:: Jack Jansen
   7 .. sectionauthor:: Georg Brandl <georg@python.org>
   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 Mac OS 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: Mac OS X.
  77
  78     .. warning::
  79
  80        In 3.0, this function is removed.
  81
  82
  83
  84 .. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])
  85
  86     Write *rootObject* as a resource with type *restype* to the resource fork of
  87     *path*.  Availability: Mac OS X.
  88
  89     .. warning::
  90
  91        In 3.0, this function is removed.
  92
  93
  94
  95 The following class is available:
  96
  97 .. class:: Data(data)
  98
  99    Return a "data" wrapper object around the string *data*.  This is used in
 100    functions converting from/to plists to represent the ``<data>`` type
 101    available in plists.
 102
 103    It has one attribute, :attr:`data`, that can be used to retrieve the Python
 104    string stored in it.
 105
 106
 107 Examples
 108 --------
 109
 110 Generating a plist::
 111
 112     pl = dict(
 113         aString="Doodah",
 114         aList=["A", "B", 12, 32.1, [1, 2, 3]],
 115         aFloat = 0.1,
 116         anInt = 728,
 117         aDict=dict(
 118             anotherString="<hello & hi there!>",
 119             aUnicodeValue=u'M\xe4ssig, Ma\xdf',
 120             aTrueValue=True,
 121             aFalseValue=False,
 122         ),
 123         someData = Data("<binary gunk>"),
 124         someMoreData = Data("<lots of binary gunk>" * 10),
 125         aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
 126     )
 127     # unicode keys are possible, but a little awkward to use:
 128     pl[u'\xc5benraa'] = "That was a unicode key."
 129     writePlist(pl, fileName)
 130
 131 Parsing a plist::
 132
 133     pl = readPlist(pathOrFile)
 134     print pl["aKey"]