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