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

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 ``writePlist()`` and
``readPlist()`` functions.

To work with plist data in bytes objects, use ``writePlistToBytes()``
and ``readPlistFromBytes()``.

Values can be strings, integers, floats, booleans, tuples, lists,
dictionaries (but only with string keys), ``Data`` or
``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 ``Data`` class.
This is a thin wrapper around a Python bytes object.  Use ``Data`` if
your strings contain control characters.

See also:

   PList manual page
      Apple's documentation of the file format.

This module defines the following functions:

plistlib.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
   ``xml.parsers.expat`` -- see its documentation for possible
   exceptions on ill-formed XML. Unknown elements will simply be
   ignored by the plist parser.

plistlib.writePlist(rootObject, pathOrFile)

   Write *rootObject* to a plist file. *pathOrFile* may either be a
   file name or a (writable) file object.

   A ``TypeError`` will be raised if the object is of an unsupported
   type or a container that contains objects of unsupported types.

plistlib.readPlistFromBytes(data)

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

plistlib.writePlistToBytes(rootObject)

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

The following class is available:

class class plistlib.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, ``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"])
