:mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files

================================================================

.. module:: plistlib

   :synopsis: Generate and parse Mac OS X plist files.

.. moduleauthor:: Jack Jansen

.. sectionauthor:: Georg Brandl <georg@python.org>

.. (harvested from docstrings in the original file)

.. versionchanged:: 2.6

   This module was previously only available in the Mac-specific library, it is

   now available for all platforms.

.. index::

   pair: plist; file

   single: property list

This module provides an interface for reading and writing the "property list"

XML files used mainly by Mac OS X.

The property list (``.plist``) file format is a simple XML pickle supporting

basic object types, like dictionaries, lists, numbers and strings.  Usually the

top level object is a dictionary.

Values can be strings, integers, floats, booleans, tuples, lists, dictionaries

(but only with string keys), :class:`Data` or :class:`datetime.datetime`

objects.  String values (including dictionary keys) may be unicode strings --

they will be written out as UTF-8.

The ``<data>`` plist type is supported through the :class:`Data` class.  This is

a thin wrapper around a Python string.  Use :class:`Data` if your strings

contain control characters.

.. seealso::

   `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`

      Apple's documentation of the file format.

This module defines the following functions:

.. function:: readPlist(pathOrFile)

   Read a plist file. *pathOrFile* may either be a file name or a (readable)

   file object.  Return the unpacked root object (which usually is a

   dictionary).

   The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`

   -- see its documentation for possible exceptions on ill-formed XML.

   Unknown elements will simply be ignored by the plist parser.

.. function:: writePlist(rootObject, pathOrFile)

    Write *rootObject* to a plist file. *pathOrFile* may either be a file name

    or a (writable) file object.

    A :exc:`TypeError` will be raised if the object is of an unsupported type or

    a container that contains objects of unsupported types.

.. function:: readPlistFromString(data)

   Read a plist from a string.  Return the root object.

.. function:: writePlistToString(rootObject)

   Return *rootObject* as a plist-formatted string.

.. function:: readPlistFromResource(path[, restype='plst'[, resid=0]])

    Read a plist from the resource with type *restype* from the resource fork of

    *path*.  Availability: Mac OS X.

    .. warning::

       In 3.0, this function is removed.

.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])

    Write *rootObject* as a resource with type *restype* to the resource fork of

    *path*.  Availability: Mac OS X.

    .. warning::

       In 3.0, this function is removed.

The following class is available:

.. class:: Data(data)

   Return a "data" wrapper object around the string *data*.  This is used in

   functions converting from/to plists to represent the ``<data>`` type

   available in plists.

   It has one attribute, :attr:`data`, that can be used to retrieve the Python

   string stored in it.

Examples

--------

Generating a plist::

    pl = dict(

        aString="Doodah",

        aList=["A", "B", 12, 32.1, [1, 2, 3]],

        aFloat = 0.1,

        anInt = 728,

        aDict=dict(

            anotherString="<hello & hi there!>",

            aUnicodeValue=u'M\xe4ssig, Ma\xdf',

            aTrueValue=True,

            aFalseValue=False,

        ),

        someData = Data("<binary gunk>"),

        someMoreData = Data("<lots of binary gunk>" * 10),

        aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),

    )

    # unicode keys are possible, but a little awkward to use:

    pl[u'\xc5benraa'] = "That was a unicode key."

    writePlist(pl, fileName)

Parsing a plist::

    pl = readPlist(pathOrFile)

    print pl["aKey"]