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"]