: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)

.. 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.

To write out and to parse a plist file, use the :func:`writePlist` and
:func:`readPlist` functions.

To work with plist data in bytes objects, use :func:`writePlistToBytes`
and :func:`readPlistFromBytes`.

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) have to 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 bytes object.  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:: readPlistFromBytes(data)

   Read a plist data from a bytes object.  Return the root object.


.. function:: writePlistToBytes(rootObject)

   Return *rootObject* as a plist-formatted bytes object.


The following class is available:

.. class:: Data(data)

   Return a "data" wrapper object around the bytes object *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
   bytes object 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!>",
            aThirdString = "M\xe4ssig, Ma\xdf",
            aTrueValue = True,
            aFalseValue = False,
        ),
        someData = Data(b"<binary gunk>"),
        someMoreData = Data(b"<lots of binary gunk>" * 10),
        aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
    )
    writePlist(pl, fileName)

Parsing a plist::

    pl = readPlist(pathOrFile)
    print(pl["aKey"])