[Python-checkins] r74814 - in python/branches/release31-maint: Doc/library/plistlib.rst Lib/plistlib.py
ezio.melotti
python-checkins at python.org
Wed Sep 16 02:57:27 CEST 2009
Author: ezio.melotti
Date: Wed Sep 16 02:57:27 2009
New Revision: 74814
Log:
Merged revisions 74813 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r74813 | ezio.melotti | 2009-09-16 03:49:03 +0300 (Wed, 16 Sep 2009) | 1 line
updated the doc to match the module docstring, fixed a couple of errors in the doc markup and in the module
........
Modified:
python/branches/release31-maint/ (props changed)
python/branches/release31-maint/Doc/library/plistlib.rst
python/branches/release31-maint/Lib/plistlib.py
Modified: python/branches/release31-maint/Doc/library/plistlib.rst
==============================================================================
--- python/branches/release31-maint/Doc/library/plistlib.rst (original)
+++ python/branches/release31-maint/Doc/library/plistlib.rst Wed Sep 16 02:57:27 2009
@@ -18,18 +18,24 @@
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 :func:`writePlist` and
+:func:`readPlist` functions.
+
+To work with plist data in bytes objects, use :func:`writePlistToBytes`
+and :func:`readPlistFromBytes`.
+
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) have to 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
+a thin wrapper around a Python bytes object. Use :class:`Data` if your strings
contain control characters.
.. seealso::
- `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`
+ `PList manual page <http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html>`_
Apple's documentation of the file format.
@@ -55,26 +61,26 @@
a container that contains objects of unsupported types.
-.. function:: readPlistFromString(data)
+.. function:: readPlistFromBytes(data)
- Read a plist from a string. Return the root object.
+ Read a plist data from a bytes object. Return the root object.
-.. function:: writePlistToString(rootObject)
+.. function:: writePlistToBytes(rootObject)
- Return *rootObject* as a plist-formatted string.
+ Return *rootObject* as a plist-formatted bytes object.
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
+ 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, :attr:`data`, that can be used to retrieve the Python
- string stored in it.
+ bytes object stored in it.
Examples
@@ -93,8 +99,8 @@
aTrueValue = True,
aFalseValue = False,
),
- someData = Data("<binary gunk>"),
- someMoreData = Data("<lots of binary gunk>" * 10),
+ someData = Data(b"<binary gunk>"),
+ someMoreData = Data(b"<lots of binary gunk>" * 10),
aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
)
writePlist(pl, fileName)
Modified: python/branches/release31-maint/Lib/plistlib.py
==============================================================================
--- python/branches/release31-maint/Lib/plistlib.py (original)
+++ python/branches/release31-maint/Lib/plistlib.py Wed Sep 16 02:57:27 2009
@@ -1,6 +1,6 @@
r"""plistlib.py -- a tool to generate and parse MacOSX .plist files.
-The PropertList (.plist) file format is a simple XML pickle supporting
+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.
@@ -16,32 +16,31 @@
and writePlistToBytes().
Values can be strings, integers, floats, booleans, tuples, lists,
-dictionaries, Data or datetime.datetime objects. String values (including
-dictionary keys) may be unicode strings -- they will be written out as
-UTF-8.
+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.
+thin wrapper around a Python bytes object. Use 'Data' if your strings
+contain control characters.
Generate Plist example:
pl = dict(
- aString="Doodah",
- aList=["A", "B", 12, 32.1, [1, 2, 3]],
+ 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,
+ aDict = dict(
+ anotherString = "<hello & hi there!>",
+ aUnicodeValue = "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())),
)
- # unicode keys are possible, but a little awkward to use:
- pl[u'\xc5benraa'] = "That was a unicode key."
writePlist(pl, fileName)
Parse Plist example:
@@ -220,7 +219,7 @@
elif isinstance(value, (tuple, list)):
self.writeArray(value)
else:
- raise TypeError("unsuported type: %s" % type(value))
+ raise TypeError("unsupported type: %s" % type(value))
def writeData(self, data):
self.beginElement("data")
More information about the Python-checkins
mailing list