2008-09-13 14:41:16 -03:00
|
|
|
:mod:`plistlib` --- Generate and parse Mac OS X ``.plist`` files
|
|
|
|
================================================================
|
2008-01-21 12:34:07 -04:00
|
|
|
|
|
|
|
.. module:: plistlib
|
2008-09-13 14:41:16 -03:00
|
|
|
:synopsis: Generate and parse Mac OS X plist files.
|
2008-01-21 12:34:07 -04:00
|
|
|
.. moduleauthor:: Jack Jansen
|
|
|
|
.. sectionauthor:: Georg Brandl <georg@python.org>
|
|
|
|
.. (harvested from docstrings in the original file)
|
|
|
|
|
|
|
|
.. versionchanged:: 2.6
|
|
|
|
This module was previously only available in the Mac-specific library, it is
|
|
|
|
now available for all platforms.
|
|
|
|
|
|
|
|
.. index::
|
|
|
|
pair: plist; file
|
|
|
|
single: property list
|
|
|
|
|
|
|
|
This module provides an interface for reading and writing the "property list"
|
2008-09-13 14:41:16 -03:00
|
|
|
XML files used mainly by Mac OS X.
|
2008-01-21 12:34:07 -04:00
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
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) may 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 string. Use :class:`Data` if your strings
|
|
|
|
contain control characters.
|
|
|
|
|
|
|
|
.. seealso::
|
|
|
|
|
2009-09-20 17:55:04 -03:00
|
|
|
`PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
|
2008-01-21 12:34:07 -04:00
|
|
|
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:: readPlistFromString(data)
|
|
|
|
|
|
|
|
Read a plist from a string. Return the root object.
|
|
|
|
|
|
|
|
|
|
|
|
.. function:: writePlistToString(rootObject)
|
|
|
|
|
|
|
|
Return *rootObject* as a plist-formatted string.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
.. function:: readPlistFromResource(path[, restype='plst'[, resid=0]])
|
|
|
|
|
|
|
|
Read a plist from the resource with type *restype* from the resource fork of
|
2008-09-13 14:41:16 -03:00
|
|
|
*path*. Availability: Mac OS X.
|
2008-01-21 12:34:07 -04:00
|
|
|
|
Merged revisions 72007-72010,72036-72037 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r72007 | georg.brandl | 2009-04-27 17:09:25 +0200 (Mo, 27 Apr 2009) | 1 line
#5856: fix typo s in traceback example.
........
r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line
Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items.
........
r72009 | georg.brandl | 2009-04-27 17:29:09 +0200 (Mo, 27 Apr 2009) | 3 lines
Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
should clutter the docs as possible. Part 1: stuff that gets merged to Py3k.
........
r72010 | georg.brandl | 2009-04-27 17:29:26 +0200 (Mo, 27 Apr 2009) | 2 lines
Demote warnings to notices, part 2: stuff that is 2.x-only.
........
r72036 | georg.brandl | 2009-04-27 19:04:23 +0200 (Mo, 27 Apr 2009) | 1 line
#5848: small unittest doc patch.
........
r72037 | georg.brandl | 2009-04-27 19:09:53 +0200 (Mo, 27 Apr 2009) | 1 line
#5840: dont claim we dont support TLS.
........
2009-04-28 15:23:28 -03:00
|
|
|
.. note::
|
2008-05-12 18:42:13 -03:00
|
|
|
|
Merged revisions 72007-72010,72036-72037 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r72007 | georg.brandl | 2009-04-27 17:09:25 +0200 (Mo, 27 Apr 2009) | 1 line
#5856: fix typo s in traceback example.
........
r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line
Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items.
........
r72009 | georg.brandl | 2009-04-27 17:29:09 +0200 (Mo, 27 Apr 2009) | 3 lines
Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
should clutter the docs as possible. Part 1: stuff that gets merged to Py3k.
........
r72010 | georg.brandl | 2009-04-27 17:29:26 +0200 (Mo, 27 Apr 2009) | 2 lines
Demote warnings to notices, part 2: stuff that is 2.x-only.
........
r72036 | georg.brandl | 2009-04-27 19:04:23 +0200 (Mo, 27 Apr 2009) | 1 line
#5848: small unittest doc patch.
........
r72037 | georg.brandl | 2009-04-27 19:09:53 +0200 (Mo, 27 Apr 2009) | 1 line
#5840: dont claim we dont support TLS.
........
2009-04-28 15:23:28 -03:00
|
|
|
In Python 3.x, this function has been removed.
|
2008-05-12 18:42:13 -03:00
|
|
|
|
2008-01-21 12:34:07 -04:00
|
|
|
|
|
|
|
.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]])
|
|
|
|
|
|
|
|
Write *rootObject* as a resource with type *restype* to the resource fork of
|
2008-09-13 14:41:16 -03:00
|
|
|
*path*. Availability: Mac OS X.
|
2008-01-21 12:34:07 -04:00
|
|
|
|
Merged revisions 72007-72010,72036-72037 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r72007 | georg.brandl | 2009-04-27 17:09:25 +0200 (Mo, 27 Apr 2009) | 1 line
#5856: fix typo s in traceback example.
........
r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line
Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items.
........
r72009 | georg.brandl | 2009-04-27 17:29:09 +0200 (Mo, 27 Apr 2009) | 3 lines
Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
should clutter the docs as possible. Part 1: stuff that gets merged to Py3k.
........
r72010 | georg.brandl | 2009-04-27 17:29:26 +0200 (Mo, 27 Apr 2009) | 2 lines
Demote warnings to notices, part 2: stuff that is 2.x-only.
........
r72036 | georg.brandl | 2009-04-27 19:04:23 +0200 (Mo, 27 Apr 2009) | 1 line
#5848: small unittest doc patch.
........
r72037 | georg.brandl | 2009-04-27 19:09:53 +0200 (Mo, 27 Apr 2009) | 1 line
#5840: dont claim we dont support TLS.
........
2009-04-28 15:23:28 -03:00
|
|
|
.. note::
|
2008-05-12 18:42:13 -03:00
|
|
|
|
Merged revisions 72007-72010,72036-72037 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r72007 | georg.brandl | 2009-04-27 17:09:25 +0200 (Mo, 27 Apr 2009) | 1 line
#5856: fix typo s in traceback example.
........
r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line
Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items.
........
r72009 | georg.brandl | 2009-04-27 17:29:09 +0200 (Mo, 27 Apr 2009) | 3 lines
Demote warnings to notices where appropriate, following the goal that as few "red box" warnings
should clutter the docs as possible. Part 1: stuff that gets merged to Py3k.
........
r72010 | georg.brandl | 2009-04-27 17:29:26 +0200 (Mo, 27 Apr 2009) | 2 lines
Demote warnings to notices, part 2: stuff that is 2.x-only.
........
r72036 | georg.brandl | 2009-04-27 19:04:23 +0200 (Mo, 27 Apr 2009) | 1 line
#5848: small unittest doc patch.
........
r72037 | georg.brandl | 2009-04-27 19:09:53 +0200 (Mo, 27 Apr 2009) | 1 line
#5840: dont claim we dont support TLS.
........
2009-04-28 15:23:28 -03:00
|
|
|
In Python 3.x, this function has been removed.
|
2008-05-12 18:42:13 -03:00
|
|
|
|
|
|
|
|
2008-01-21 12:34:07 -04:00
|
|
|
|
|
|
|
The following class is available:
|
|
|
|
|
|
|
|
.. class:: Data(data)
|
|
|
|
|
|
|
|
Return a "data" wrapper object around the string *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
|
|
|
|
string 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!>",
|
|
|
|
aUnicodeValue=u'M\xe4ssig, Ma\xdf',
|
|
|
|
aTrueValue=True,
|
|
|
|
aFalseValue=False,
|
|
|
|
),
|
|
|
|
someData = Data("<binary gunk>"),
|
|
|
|
someMoreData = Data("<lots of binary gunk>" * 10),
|
|
|
|
aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
|
|
|
|
)
|
|
|
|
# unicode keys are possible, but a little awkward to use:
|
|
|
|
pl[u'\xc5benraa'] = "That was a unicode key."
|
|
|
|
writePlist(pl, fileName)
|
|
|
|
|
|
|
|
Parsing a plist::
|
|
|
|
|
|
|
|
pl = readPlist(pathOrFile)
|
|
|
|
print pl["aKey"]
|