From 864de8274c5d2904e1df6837450408cfdb6f9e11 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 21 Jan 2008 16:34:07 +0000 Subject: #1555501: document plistlib and move it to the general library. --- Doc/library/fileformats.rst | 1 + Doc/library/plistlib.rst | 124 ++++++++++++ Lib/plat-mac/plistlib.py | 470 -------------------------------------------- Lib/plistlib.py | 470 ++++++++++++++++++++++++++++++++++++++++++++ Misc/NEWS | 2 + 5 files changed, 597 insertions(+), 470 deletions(-) create mode 100644 Doc/library/plistlib.rst delete mode 100644 Lib/plat-mac/plistlib.py create mode 100644 Lib/plistlib.py diff --git a/Doc/library/fileformats.rst b/Doc/library/fileformats.rst index c0c2eed..d2f0639 100644 --- a/Doc/library/fileformats.rst +++ b/Doc/library/fileformats.rst @@ -16,3 +16,4 @@ that aren't markup languages or are related to e-mail. robotparser.rst netrc.rst xdrlib.rst + plistlib.rst diff --git a/Doc/library/plistlib.rst b/Doc/library/plistlib.rst new file mode 100644 index 0000000..508f8e8 --- /dev/null +++ b/Doc/library/plistlib.rst @@ -0,0 +1,124 @@ +:mod:`plistlib` --- Generate and parse MacOS X ``.plist`` files +=============================================================== + +.. module:: plistlib + :synopsis: Generate and parse MacOS X plist files. +.. moduleauthor:: Jack Jansen +.. sectionauthor:: Georg Brandl +.. (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" +XML files used mainly by MacOS X. + +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 ```` 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:: + + `PList manual page ` + 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 + *path*. Availability: MacOS X. + + +.. function:: writePlistToResource(rootObject, path[, restype='plst'[, resid=0]]) + + Write *rootObject* as a resource with type *restype* to the resource fork of + *path*. Availability: MacOS X. + + +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 + 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="", + aUnicodeValue=u'M\xe4ssig, Ma\xdf', + aTrueValue=True, + aFalseValue=False, + ), + someData = Data(""), + someMoreData = Data("" * 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"] diff --git a/Lib/plat-mac/plistlib.py b/Lib/plat-mac/plistlib.py deleted file mode 100644 index e61c4a4..0000000 --- a/Lib/plat-mac/plistlib.py +++ /dev/null @@ -1,470 +0,0 @@ -"""plistlib.py -- a tool to generate and parse MacOSX .plist files. - -The PropertList (.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 a plist file, use the writePlist(rootObject, pathOrFile) -function. 'rootObject' is the top level object, 'pathOrFile' is a -filename or a (writable) file object. - -To parse a plist from a file, use the readPlist(pathOrFile) function, -with a file name or a (readable) file object as the only argument. It -returns the top level object (again, usually a dictionary). - -To work with plist data in strings, you can use readPlistFromString() -and writePlistToString(). - -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. - -The plist type is supported through the Data class. This is a -thin wrapper around a Python string. - -Generate Plist example: - - pl = dict( - 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, - ), - someData = Data(""), - someMoreData = Data("" * 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: - - pl = readPlist(pathOrFile) - print pl["aKey"] -""" - - -__all__ = [ - "readPlist", "writePlist", "readPlistFromString", "writePlistToString", - "readPlistFromResource", "writePlistToResource", - "Plist", "Data", "Dict" -] -# Note: the Plist and Dict classes have been deprecated. - -import binascii -import datetime -from cStringIO import StringIO -import re - - -def 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). - """ - didOpen = 0 - if isinstance(pathOrFile, (str, unicode)): - pathOrFile = open(pathOrFile) - didOpen = 1 - p = PlistParser() - rootObject = p.parse(pathOrFile) - if didOpen: - pathOrFile.close() - return rootObject - - -def writePlist(rootObject, pathOrFile): - """Write 'rootObject' to a .plist file. 'pathOrFile' may either be a - file name or a (writable) file object. - """ - didOpen = 0 - if isinstance(pathOrFile, (str, unicode)): - pathOrFile = open(pathOrFile, "w") - didOpen = 1 - writer = PlistWriter(pathOrFile) - writer.writeln("") - writer.writeValue(rootObject) - writer.writeln("") - if didOpen: - pathOrFile.close() - - -def readPlistFromString(data): - """Read a plist data from a string. Return the root object. - """ - return readPlist(StringIO(data)) - - -def writePlistToString(rootObject): - """Return 'rootObject' as a plist-formatted string. - """ - f = StringIO() - writePlist(rootObject, f) - return f.getvalue() - - -def readPlistFromResource(path, restype='plst', resid=0): - """Read plst resource from the resource fork of path. - """ - from Carbon.File import FSRef, FSGetResourceForkName - from Carbon.Files import fsRdPerm - from Carbon import Res - fsRef = FSRef(path) - resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdPerm) - Res.UseResFile(resNum) - plistData = Res.Get1Resource(restype, resid).data - Res.CloseResFile(resNum) - return readPlistFromString(plistData) - - -def writePlistToResource(rootObject, path, restype='plst', resid=0): - """Write 'rootObject' as a plst resource to the resource fork of path. - """ - from Carbon.File import FSRef, FSGetResourceForkName - from Carbon.Files import fsRdWrPerm - from Carbon import Res - plistData = writePlistToString(rootObject) - fsRef = FSRef(path) - resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdWrPerm) - Res.UseResFile(resNum) - try: - Res.Get1Resource(restype, resid).RemoveResource() - except Res.Error: - pass - res = Res.Resource(plistData) - res.AddResource(restype, resid, '') - res.WriteResource() - Res.CloseResFile(resNum) - - -class DumbXMLWriter: - - def __init__(self, file, indentLevel=0, indent="\t"): - self.file = file - self.stack = [] - self.indentLevel = indentLevel - self.indent = indent - - def beginElement(self, element): - self.stack.append(element) - self.writeln("<%s>" % element) - self.indentLevel += 1 - - def endElement(self, element): - assert self.indentLevel > 0 - assert self.stack.pop() == element - self.indentLevel -= 1 - self.writeln("" % element) - - def simpleElement(self, element, value=None): - if value is not None: - value = _escapeAndEncode(value) - self.writeln("<%s>%s" % (element, value, element)) - else: - self.writeln("<%s/>" % element) - - def writeln(self, line): - if line: - self.file.write(self.indentLevel * self.indent + line + "\n") - else: - self.file.write("\n") - - -# Contents should conform to a subset of ISO 8601 -# (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'. Smaller units may be omitted with -# a loss of precision) -_dateParser = re.compile(r"(?P\d\d\d\d)(?:-(?P\d\d)(?:-(?P\d\d)(?:T(?P\d\d)(?::(?P\d\d)(?::(?P\d\d))?)?)?)?)?Z") - -def _dateFromString(s): - order = ('year', 'month', 'day', 'hour', 'minute', 'second') - gd = _dateParser.match(s).groupdict() - lst = [] - for key in order: - val = gd[key] - if val is None: - break - lst.append(int(val)) - return datetime.datetime(*lst) - -def _dateToString(d): - return '%04d-%02d-%02dT%02d:%02d:%02dZ' % ( - d.year, d.month, d.day, - d.hour, d.minute, d.second - ) - - -# Regex to find any control chars, except for \t \n and \r -_controlCharPat = re.compile( - r"[\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0b\x0c\x0e\x0f" - r"\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f]") - -def _escapeAndEncode(text): - m = _controlCharPat.search(text) - if m is not None: - raise ValueError("strings can't contains control characters; " - "use plistlib.Data instead") - text = text.replace("\r\n", "\n") # convert DOS line endings - text = text.replace("\r", "\n") # convert Mac line endings - text = text.replace("&", "&") # escape '&' - text = text.replace("<", "<") # escape '<' - text = text.replace(">", ">") # escape '>' - return text.encode("utf-8") # encode as UTF-8 - - -PLISTHEADER = """\ - - -""" - -class PlistWriter(DumbXMLWriter): - - def __init__(self, file, indentLevel=0, indent="\t", writeHeader=1): - if writeHeader: - file.write(PLISTHEADER) - DumbXMLWriter.__init__(self, file, indentLevel, indent) - - def writeValue(self, value): - if isinstance(value, (str, unicode)): - self.simpleElement("string", value) - elif isinstance(value, bool): - # must switch for bool before int, as bool is a - # subclass of int... - if value: - self.simpleElement("true") - else: - self.simpleElement("false") - elif isinstance(value, (int, long)): - self.simpleElement("integer", "%d" % value) - elif isinstance(value, float): - self.simpleElement("real", repr(value)) - elif isinstance(value, dict): - self.writeDict(value) - elif isinstance(value, Data): - self.writeData(value) - elif isinstance(value, datetime.datetime): - self.simpleElement("date", _dateToString(value)) - elif isinstance(value, (tuple, list)): - self.writeArray(value) - else: - raise TypeError("unsuported type: %s" % type(value)) - - def writeData(self, data): - self.beginElement("data") - self.indentLevel -= 1 - maxlinelength = 76 - len(self.indent.replace("\t", " " * 8) * - self.indentLevel) - for line in data.asBase64(maxlinelength).split("\n"): - if line: - self.writeln(line) - self.indentLevel += 1 - self.endElement("data") - - def writeDict(self, d): - self.beginElement("dict") - items = d.items() - items.sort() - for key, value in items: - if not isinstance(key, (str, unicode)): - raise TypeError("keys must be strings") - self.simpleElement("key", key) - self.writeValue(value) - self.endElement("dict") - - def writeArray(self, array): - self.beginElement("array") - for value in array: - self.writeValue(value) - self.endElement("array") - - -class _InternalDict(dict): - - # This class is needed while Dict is scheduled for deprecation: - # we only need to warn when a *user* instantiates Dict or when - # the "attribute notation for dict keys" is used. - - def __getattr__(self, attr): - try: - value = self[attr] - except KeyError: - raise AttributeError, attr - from warnings import warn - warn("Attribute access from plist dicts is deprecated, use d[key] " - "notation instead", PendingDeprecationWarning) - return value - - def __setattr__(self, attr, value): - from warnings import warn - warn("Attribute access from plist dicts is deprecated, use d[key] " - "notation instead", PendingDeprecationWarning) - self[attr] = value - - def __delattr__(self, attr): - try: - del self[attr] - except KeyError: - raise AttributeError, attr - from warnings import warn - warn("Attribute access from plist dicts is deprecated, use d[key] " - "notation instead", PendingDeprecationWarning) - -class Dict(_InternalDict): - - def __init__(self, **kwargs): - from warnings import warn - warn("The plistlib.Dict class is deprecated, use builtin dict instead", - PendingDeprecationWarning) - super(Dict, self).__init__(**kwargs) - - -class Plist(_InternalDict): - - """This class has been deprecated. Use readPlist() and writePlist() - functions instead, together with regular dict objects. - """ - - def __init__(self, **kwargs): - from warnings import warn - warn("The Plist class is deprecated, use the readPlist() and " - "writePlist() functions instead", PendingDeprecationWarning) - super(Plist, self).__init__(**kwargs) - - def fromFile(cls, pathOrFile): - """Deprecated. Use the readPlist() function instead.""" - rootObject = readPlist(pathOrFile) - plist = cls() - plist.update(rootObject) - return plist - fromFile = classmethod(fromFile) - - def write(self, pathOrFile): - """Deprecated. Use the writePlist() function instead.""" - writePlist(self, pathOrFile) - - -def _encodeBase64(s, maxlinelength=76): - # copied from base64.encodestring(), with added maxlinelength argument - maxbinsize = (maxlinelength//4)*3 - pieces = [] - for i in range(0, len(s), maxbinsize): - chunk = s[i : i + maxbinsize] - pieces.append(binascii.b2a_base64(chunk)) - return "".join(pieces) - -class Data: - - """Wrapper for binary data.""" - - def __init__(self, data): - self.data = data - - def fromBase64(cls, data): - # base64.decodestring just calls binascii.a2b_base64; - # it seems overkill to use both base64 and binascii. - return cls(binascii.a2b_base64(data)) - fromBase64 = classmethod(fromBase64) - - def asBase64(self, maxlinelength=76): - return _encodeBase64(self.data, maxlinelength) - - def __cmp__(self, other): - if isinstance(other, self.__class__): - return cmp(self.data, other.data) - elif isinstance(other, str): - return cmp(self.data, other) - else: - return cmp(id(self), id(other)) - - def __repr__(self): - return "%s(%s)" % (self.__class__.__name__, repr(self.data)) - - -class PlistParser: - - def __init__(self): - self.stack = [] - self.currentKey = None - self.root = None - - def parse(self, fileobj): - from xml.parsers.expat import ParserCreate - parser = ParserCreate() - parser.StartElementHandler = self.handleBeginElement - parser.EndElementHandler = self.handleEndElement - parser.CharacterDataHandler = self.handleData - parser.ParseFile(fileobj) - return self.root - - def handleBeginElement(self, element, attrs): - self.data = [] - handler = getattr(self, "begin_" + element, None) - if handler is not None: - handler(attrs) - - def handleEndElement(self, element): - handler = getattr(self, "end_" + element, None) - if handler is not None: - handler() - - def handleData(self, data): - self.data.append(data) - - def addObject(self, value): - if self.currentKey is not None: - self.stack[-1][self.currentKey] = value - self.currentKey = None - elif not self.stack: - # this is the root object - self.root = value - else: - self.stack[-1].append(value) - - def getData(self): - data = "".join(self.data) - try: - data = data.encode("ascii") - except UnicodeError: - pass - self.data = [] - return data - - # element handlers - - def begin_dict(self, attrs): - d = _InternalDict() - self.addObject(d) - self.stack.append(d) - def end_dict(self): - self.stack.pop() - - def end_key(self): - self.currentKey = self.getData() - - def begin_array(self, attrs): - a = [] - self.addObject(a) - self.stack.append(a) - def end_array(self): - self.stack.pop() - - def end_true(self): - self.addObject(True) - def end_false(self): - self.addObject(False) - def end_integer(self): - self.addObject(int(self.getData())) - def end_real(self): - self.addObject(float(self.getData())) - def end_string(self): - self.addObject(self.getData()) - def end_data(self): - self.addObject(Data.fromBase64(self.getData())) - def end_date(self): - self.addObject(_dateFromString(self.getData())) diff --git a/Lib/plistlib.py b/Lib/plistlib.py new file mode 100644 index 0000000..5e107b6 --- /dev/null +++ b/Lib/plistlib.py @@ -0,0 +1,470 @@ +"""plistlib.py -- a tool to generate and parse MacOSX .plist files. + +The PropertyList (.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 a plist file, use the writePlist(rootObject, pathOrFile) +function. 'rootObject' is the top level object, 'pathOrFile' is a +filename or a (writable) file object. + +To parse a plist from a file, use the readPlist(pathOrFile) function, +with a file name or a (readable) file object as the only argument. It +returns the top level object (again, usually a dictionary). + +To work with plist data in strings, you can use readPlistFromString() +and writePlistToString(). + +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. + +The plist type is supported through the Data class. This is a +thin wrapper around a Python string. + +Generate Plist example: + + pl = dict( + 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, + ), + someData = Data(""), + someMoreData = Data("" * 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: + + pl = readPlist(pathOrFile) + print pl["aKey"] +""" + + +__all__ = [ + "readPlist", "writePlist", "readPlistFromString", "writePlistToString", + "readPlistFromResource", "writePlistToResource", + "Plist", "Data", "Dict" +] +# Note: the Plist and Dict classes have been deprecated. + +import binascii +import datetime +from cStringIO import StringIO +import re + + +def 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). + """ + didOpen = 0 + if isinstance(pathOrFile, (str, unicode)): + pathOrFile = open(pathOrFile) + didOpen = 1 + p = PlistParser() + rootObject = p.parse(pathOrFile) + if didOpen: + pathOrFile.close() + return rootObject + + +def writePlist(rootObject, pathOrFile): + """Write 'rootObject' to a .plist file. 'pathOrFile' may either be a + file name or a (writable) file object. + """ + didOpen = 0 + if isinstance(pathOrFile, (str, unicode)): + pathOrFile = open(pathOrFile, "w") + didOpen = 1 + writer = PlistWriter(pathOrFile) + writer.writeln("") + writer.writeValue(rootObject) + writer.writeln("") + if didOpen: + pathOrFile.close() + + +def readPlistFromString(data): + """Read a plist data from a string. Return the root object. + """ + return readPlist(StringIO(data)) + + +def writePlistToString(rootObject): + """Return 'rootObject' as a plist-formatted string. + """ + f = StringIO() + writePlist(rootObject, f) + return f.getvalue() + + +def readPlistFromResource(path, restype='plst', resid=0): + """Read plst resource from the resource fork of path. + """ + from Carbon.File import FSRef, FSGetResourceForkName + from Carbon.Files import fsRdPerm + from Carbon import Res + fsRef = FSRef(path) + resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdPerm) + Res.UseResFile(resNum) + plistData = Res.Get1Resource(restype, resid).data + Res.CloseResFile(resNum) + return readPlistFromString(plistData) + + +def writePlistToResource(rootObject, path, restype='plst', resid=0): + """Write 'rootObject' as a plst resource to the resource fork of path. + """ + from Carbon.File import FSRef, FSGetResourceForkName + from Carbon.Files import fsRdWrPerm + from Carbon import Res + plistData = writePlistToString(rootObject) + fsRef = FSRef(path) + resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdWrPerm) + Res.UseResFile(resNum) + try: + Res.Get1Resource(restype, resid).RemoveResource() + except Res.Error: + pass + res = Res.Resource(plistData) + res.AddResource(restype, resid, '') + res.WriteResource() + Res.CloseResFile(resNum) + + +class DumbXMLWriter: + + def __init__(self, file, indentLevel=0, indent="\t"): + self.file = file + self.stack = [] + self.indentLevel = indentLevel + self.indent = indent + + def beginElement(self, element): + self.stack.append(element) + self.writeln("<%s>" % element) + self.indentLevel += 1 + + def endElement(self, element): + assert self.indentLevel > 0 + assert self.stack.pop() == element + self.indentLevel -= 1 + self.writeln("" % element) + + def simpleElement(self, element, value=None): + if value is not None: + value = _escapeAndEncode(value) + self.writeln("<%s>%s" % (element, value, element)) + else: + self.writeln("<%s/>" % element) + + def writeln(self, line): + if line: + self.file.write(self.indentLevel * self.indent + line + "\n") + else: + self.file.write("\n") + + +# Contents should conform to a subset of ISO 8601 +# (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'. Smaller units may be omitted with +# a loss of precision) +_dateParser = re.compile(r"(?P\d\d\d\d)(?:-(?P\d\d)(?:-(?P\d\d)(?:T(?P\d\d)(?::(?P\d\d)(?::(?P\d\d))?)?)?)?)?Z") + +def _dateFromString(s): + order = ('year', 'month', 'day', 'hour', 'minute', 'second') + gd = _dateParser.match(s).groupdict() + lst = [] + for key in order: + val = gd[key] + if val is None: + break + lst.append(int(val)) + return datetime.datetime(*lst) + +def _dateToString(d): + return '%04d-%02d-%02dT%02d:%02d:%02dZ' % ( + d.year, d.month, d.day, + d.hour, d.minute, d.second + ) + + +# Regex to find any control chars, except for \t \n and \r +_controlCharPat = re.compile( + r"[\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0b\x0c\x0e\x0f" + r"\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f]") + +def _escapeAndEncode(text): + m = _controlCharPat.search(text) + if m is not None: + raise ValueError("strings can't contains control characters; " + "use plistlib.Data instead") + text = text.replace("\r\n", "\n") # convert DOS line endings + text = text.replace("\r", "\n") # convert Mac line endings + text = text.replace("&", "&") # escape '&' + text = text.replace("<", "<") # escape '<' + text = text.replace(">", ">") # escape '>' + return text.encode("utf-8") # encode as UTF-8 + + +PLISTHEADER = """\ + + +""" + +class PlistWriter(DumbXMLWriter): + + def __init__(self, file, indentLevel=0, indent="\t", writeHeader=1): + if writeHeader: + file.write(PLISTHEADER) + DumbXMLWriter.__init__(self, file, indentLevel, indent) + + def writeValue(self, value): + if isinstance(value, (str, unicode)): + self.simpleElement("string", value) + elif isinstance(value, bool): + # must switch for bool before int, as bool is a + # subclass of int... + if value: + self.simpleElement("true") + else: + self.simpleElement("false") + elif isinstance(value, (int, long)): + self.simpleElement("integer", "%d" % value) + elif isinstance(value, float): + self.simpleElement("real", repr(value)) + elif isinstance(value, dict): + self.writeDict(value) + elif isinstance(value, Data): + self.writeData(value) + elif isinstance(value, datetime.datetime): + self.simpleElement("date", _dateToString(value)) + elif isinstance(value, (tuple, list)): + self.writeArray(value) + else: + raise TypeError("unsuported type: %s" % type(value)) + + def writeData(self, data): + self.beginElement("data") + self.indentLevel -= 1 + maxlinelength = 76 - len(self.indent.replace("\t", " " * 8) * + self.indentLevel) + for line in data.asBase64(maxlinelength).split("\n"): + if line: + self.writeln(line) + self.indentLevel += 1 + self.endElement("data") + + def writeDict(self, d): + self.beginElement("dict") + items = d.items() + items.sort() + for key, value in items: + if not isinstance(key, (str, unicode)): + raise TypeError("keys must be strings") + self.simpleElement("key", key) + self.writeValue(value) + self.endElement("dict") + + def writeArray(self, array): + self.beginElement("array") + for value in array: + self.writeValue(value) + self.endElement("array") + + +class _InternalDict(dict): + + # This class is needed while Dict is scheduled for deprecation: + # we only need to warn when a *user* instantiates Dict or when + # the "attribute notation for dict keys" is used. + + def __getattr__(self, attr): + try: + value = self[attr] + except KeyError: + raise AttributeError, attr + from warnings import warn + warn("Attribute access from plist dicts is deprecated, use d[key] " + "notation instead", PendingDeprecationWarning) + return value + + def __setattr__(self, attr, value): + from warnings import warn + warn("Attribute access from plist dicts is deprecated, use d[key] " + "notation instead", PendingDeprecationWarning) + self[attr] = value + + def __delattr__(self, attr): + try: + del self[attr] + except KeyError: + raise AttributeError, attr + from warnings import warn + warn("Attribute access from plist dicts is deprecated, use d[key] " + "notation instead", PendingDeprecationWarning) + +class Dict(_InternalDict): + + def __init__(self, **kwargs): + from warnings import warn + warn("The plistlib.Dict class is deprecated, use builtin dict instead", + PendingDeprecationWarning) + super(Dict, self).__init__(**kwargs) + + +class Plist(_InternalDict): + + """This class has been deprecated. Use readPlist() and writePlist() + functions instead, together with regular dict objects. + """ + + def __init__(self, **kwargs): + from warnings import warn + warn("The Plist class is deprecated, use the readPlist() and " + "writePlist() functions instead", PendingDeprecationWarning) + super(Plist, self).__init__(**kwargs) + + def fromFile(cls, pathOrFile): + """Deprecated. Use the readPlist() function instead.""" + rootObject = readPlist(pathOrFile) + plist = cls() + plist.update(rootObject) + return plist + fromFile = classmethod(fromFile) + + def write(self, pathOrFile): + """Deprecated. Use the writePlist() function instead.""" + writePlist(self, pathOrFile) + + +def _encodeBase64(s, maxlinelength=76): + # copied from base64.encodestring(), with added maxlinelength argument + maxbinsize = (maxlinelength//4)*3 + pieces = [] + for i in range(0, len(s), maxbinsize): + chunk = s[i : i + maxbinsize] + pieces.append(binascii.b2a_base64(chunk)) + return "".join(pieces) + +class Data: + + """Wrapper for binary data.""" + + def __init__(self, data): + self.data = data + + def fromBase64(cls, data): + # base64.decodestring just calls binascii.a2b_base64; + # it seems overkill to use both base64 and binascii. + return cls(binascii.a2b_base64(data)) + fromBase64 = classmethod(fromBase64) + + def asBase64(self, maxlinelength=76): + return _encodeBase64(self.data, maxlinelength) + + def __cmp__(self, other): + if isinstance(other, self.__class__): + return cmp(self.data, other.data) + elif isinstance(other, str): + return cmp(self.data, other) + else: + return cmp(id(self), id(other)) + + def __repr__(self): + return "%s(%s)" % (self.__class__.__name__, repr(self.data)) + + +class PlistParser: + + def __init__(self): + self.stack = [] + self.currentKey = None + self.root = None + + def parse(self, fileobj): + from xml.parsers.expat import ParserCreate + parser = ParserCreate() + parser.StartElementHandler = self.handleBeginElement + parser.EndElementHandler = self.handleEndElement + parser.CharacterDataHandler = self.handleData + parser.ParseFile(fileobj) + return self.root + + def handleBeginElement(self, element, attrs): + self.data = [] + handler = getattr(self, "begin_" + element, None) + if handler is not None: + handler(attrs) + + def handleEndElement(self, element): + handler = getattr(self, "end_" + element, None) + if handler is not None: + handler() + + def handleData(self, data): + self.data.append(data) + + def addObject(self, value): + if self.currentKey is not None: + self.stack[-1][self.currentKey] = value + self.currentKey = None + elif not self.stack: + # this is the root object + self.root = value + else: + self.stack[-1].append(value) + + def getData(self): + data = "".join(self.data) + try: + data = data.encode("ascii") + except UnicodeError: + pass + self.data = [] + return data + + # element handlers + + def begin_dict(self, attrs): + d = _InternalDict() + self.addObject(d) + self.stack.append(d) + def end_dict(self): + self.stack.pop() + + def end_key(self): + self.currentKey = self.getData() + + def begin_array(self, attrs): + a = [] + self.addObject(a) + self.stack.append(a) + def end_array(self): + self.stack.pop() + + def end_true(self): + self.addObject(True) + def end_false(self): + self.addObject(False) + def end_integer(self): + self.addObject(int(self.getData())) + def end_real(self): + self.addObject(float(self.getData())) + def end_string(self): + self.addObject(self.getData()) + def end_data(self): + self.addObject(Data.fromBase64(self.getData())) + def end_date(self): + self.addObject(_dateFromString(self.getData())) diff --git a/Misc/NEWS b/Misc/NEWS index 02bb149..5768951 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -369,6 +369,8 @@ Core and builtins Library ------- +- #1555501: move plistlib from plat-mac directory to general library. + - #1269: fix a bug in pstats.add_callers() and add a unit test file for pstats. -- cgit v0.12