From 1e112baf6aedad75af6b91987bbd1731a5fb3e1f Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 16 Sep 2009 00:57:27 +0000 Subject: [PATCH] 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 ........ --- Doc/library/plistlib.rst | 28 +++++++++++++++++----------- Lib/plistlib.py | 29 ++++++++++++++--------------- 2 files changed, 31 insertions(+), 26 deletions(-) diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst index 55b84e020ff..36c9eb30873 100644 --- a/Doc/library/plistlib.rst +++ b/Doc/library/plistlib.rst @@ -18,18 +18,24 @@ 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 :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 ```` 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 ` + `PList manual page `_ Apple's documentation of the file format. @@ -55,26 +61,26 @@ This module defines the following functions: 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 ```` type + Return a "data" wrapper object around the bytes object *data*. This is used + in functions converting from/to plists to represent the ```` 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 @@ Generating a plist:: aTrueValue = True, aFalseValue = False, ), - someData = Data(""), - someMoreData = Data("" * 10), + someData = Data(b""), + someMoreData = Data(b"" * 10), aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())), ) writePlist(pl, fileName) diff --git a/Lib/plistlib.py b/Lib/plistlib.py index 5460e2b5dfe..fbba791ce57 100644 --- a/Lib/plistlib.py +++ b/Lib/plistlib.py @@ -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 @@ To work with plist data in bytes objects, you can use readPlistFromBytes() 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 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="", - aUnicodeValue=u'M\xe4ssig, Ma\xdf', - aTrueValue=True, - aFalseValue=False, + aDict = dict( + anotherString = "", + aUnicodeValue = "M\xe4ssig, Ma\xdf", + aTrueValue = True, + aFalseValue = False, ), someData = Data(b""), someMoreData = Data(b"" * 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 @@ class PlistWriter(DumbXMLWriter): 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")