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

**Source code:** Lib/plistlib.py

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

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 and binary) 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 and binary) 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"])
