← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/library/plistlib.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

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