Home | History | Annotate | Download | only in library 
      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 (a] 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 **Source code:** :source:`Lib/plistlib.py`
     19 
     20 --------------
     21 
     22 This module provides an interface for reading and writing the "property list"
     23 XML files used mainly by Mac OS X.
     24 
     25 The property list (``.plist``) file format is a simple XML pickle supporting
     26 basic object types, like dictionaries, lists, numbers and strings.  Usually the
     27 top level object is a dictionary.
     28 
     29 Values can be strings, integers, floats, booleans, tuples, lists, dictionaries
     30 (but only with string keys), :class:`Data` or :class:`datetime.datetime`
     31 objects.  String values (including dictionary keys) may be unicode strings --
     32 they will be written out as UTF-8.
     33 
     34 The ``<data>`` plist type is supported through the :class:`Data` class.  This is
     35 a thin wrapper around a Python string.  Use :class:`Data` if your strings
     36 contain control characters.
     37 
     38 .. seealso::
     39 
     40    `PList manual page <https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
     41       Apple's documentation of the file format.
     42 
     43 
     44 This module defines the following functions:
     45 
     46 .. function:: readPlist(pathOrFile)
     47 
     48    Read a plist file. *pathOrFile* may either be a file name or a (readable)
     49    file object.  Return the unpacked root object (which usually is a
     50    dictionary).
     51 
     52    The XML data is parsed using the Expat parser from :mod:`xml.parsers.expat`
     53    -- see its documentation for possible exceptions on ill-formed XML.
     54    Unknown elements will simply be ignored by the plist parser.
     55 
     56 
     57 .. function:: writePlist(rootObject, pathOrFile)
     58 
     59     Write *rootObject* to a plist file. *pathOrFile* may either be a file name
     60     or a (writable) file object.
     61 
     62     A :exc:`TypeError` will be raised if the object is of an unsupported type or
     63     a container that contains objects of unsupported types.
     64 
     65 
     66 .. function:: readPlistFromString(data)
     67 
     68    Read a plist from a string.  Return the root object.
     69 
     70 
     71 .. function:: writePlistToString(rootObject)
     72 
     73    Return *rootObject* as a plist-formatted string.
     74 
     75 
     76 
     77 .. function:: readPlistFromResource(path, restype='plst', resid=0)
     78 
     79     Read a plist from the resource with type *restype* from the resource fork of
     80     *path*.  Availability: Mac OS X.
     81 
     82     .. note::
     83 
     84        In Python 3.x, this function has been removed.
     85 
     86 
     87 .. function:: writePlistToResource(rootObject, path, restype='plst', resid=0)
     88 
     89     Write *rootObject* as a resource with type *restype* to the resource fork of
     90     *path*.  Availability: Mac OS X.
     91 
     92     .. note::
     93 
     94        In Python 3.x, this function has been removed.
     95 
     96 
     97 
     98 The following class is available:
     99 
    100 .. class:: Data(data)
    101 
    102    Return a "data" wrapper object around the string *data*.  This is used in
    103    functions converting from/to plists to represent the ``<data>`` type
    104    available in plists.
    105 
    106    It has one attribute, :attr:`data`, that can be used to retrieve the Python
    107    string stored in it.
    108 
    109 
    110 Examples
    111 --------
    112 
    113 Generating a plist::
    114 
    115     pl = dict(
    116         aString="Doodah",
    117         aList=["A", "B", 12, 32.1, [1, 2, 3]],
    118         aFloat = 0.1,
    119         anInt = 728,
    120         aDict=dict(
    121             anotherString="<hello & hi there!>",
    122             aUnicodeValue=u'M\xe4ssig, Ma\xdf',
    123             aTrueValue=True,
    124             aFalseValue=False,
    125         ),
    126         someData = Data("<binary gunk>"),
    127         someMoreData = Data("<lots of binary gunk>" * 10),
    128         aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
    129     )
    130     # unicode keys are possible, but a little awkward to use:
    131     pl[u'\xc5benraa'] = "That was a unicode key."
    132     writePlist(pl, fileName)
    133 
    134 Parsing a plist::
    135 
    136     pl = readPlist(pathOrFile)
    137     print pl["aKey"]
    138