1 """plistlib.py -- a tool to generate and parse MacOSX .plist files.

     2 

     3 The PropertyList (.plist) file format is a simple XML pickle supporting

     4 basic object types, like dictionaries, lists, numbers and strings.

     5 Usually the top level object is a dictionary.

     6 

     7 To write out a plist file, use the writePlist(rootObject, pathOrFile)

     8 function. 'rootObject' is the top level object, 'pathOrFile' is a

     9 filename or a (writable) file object.

    10 

    11 To parse a plist from a file, use the readPlist(pathOrFile) function,

    12 with a file name or a (readable) file object as the only argument. It

    13 returns the top level object (again, usually a dictionary).

    14 

    15 To work with plist data in strings, you can use readPlistFromString()

    16 and writePlistToString().

    17 

    18 Values can be strings, integers, floats, booleans, tuples, lists,

    19 dictionaries, Data or datetime.datetime objects. String values (including

    20 dictionary keys) may be unicode strings -- they will be written out as

    21 UTF-8.

    22 

    23 The <data> plist type is supported through the Data class. This is a

    24 thin wrapper around a Python string.

    25 

    26 Generate Plist example:

    27 

    28     pl = dict(

    29         aString="Doodah",

    30         aList=["A", "B", 12, 32.1, [1, 2, 3]],

    31         aFloat=0.1,

    32         anInt=728,

    33         aDict=dict(

    34             anotherString="<hello & hi there!>",

    35             aUnicodeValue=u'M\xe4ssig, Ma\xdf',

    36             aTrueValue=True,

    37             aFalseValue=False,

    38         ),

    39         someData=Data("<binary gunk>"),

    40         someMoreData=Data("<lots of binary gunk>" * 10),

    41         aDate=datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),

    42     )

    43     # unicode keys are possible, but a little awkward to use:

    44     pl[u'\xc5benraa'] = "That was a unicode key."

    45     writePlist(pl, fileName)

    46 

    47 Parse Plist example:

    48 

    49     pl = readPlist(pathOrFile)

    50     print pl["aKey"]

    51 """

    52 

    53 

    54 __all__ = [

    55     "readPlist", "writePlist", "readPlistFromString", "writePlistToString",

    56     "readPlistFromResource", "writePlistToResource",

    57     "Plist", "Data", "Dict"

    58 ]

    59 # Note: the Plist and Dict classes have been deprecated.

    60 

    61 import binascii

    62 import datetime

    63 from cStringIO import StringIO

    64 import re

    65 import warnings

    66 

    67 

    68 def readPlist(pathOrFile):

    69     """Read a .plist file. 'pathOrFile' may either be a file name or a

    70     (readable) file object. Return the unpacked root object (which

    71     usually is a dictionary).

    72     """

    73     didOpen = 0

    74     if isinstance(pathOrFile, (str, unicode)):

    75         pathOrFile = open(pathOrFile)

    76         didOpen = 1

    77     p = PlistParser()

    78     rootObject = p.parse(pathOrFile)

    79     if didOpen:

    80         pathOrFile.close()

    81     return rootObject

    82 

    83 

    84 def writePlist(rootObject, pathOrFile):

    85     """Write 'rootObject' to a .plist file. 'pathOrFile' may either be a

    86     file name or a (writable) file object.

    87     """

    88     didOpen = 0

    89     if isinstance(pathOrFile, (str, unicode)):

    90         pathOrFile = open(pathOrFile, "w")

    91         didOpen = 1

    92     writer = PlistWriter(pathOrFile)

    93     writer.writeln("<plist version=\"1.0\">")

    94     writer.writeValue(rootObject)

    95     writer.writeln("</plist>")

    96     if didOpen:

    97         pathOrFile.close()

    98 

    99 

   100 def readPlistFromString(data):

   101     """Read a plist data from a string. Return the root object.

   102     """

   103     return readPlist(StringIO(data))

   104 

   105 

   106 def writePlistToString(rootObject):

   107     """Return 'rootObject' as a plist-formatted string.

   108     """

   109     f = StringIO()

   110     writePlist(rootObject, f)

   111     return f.getvalue()

   112 

   113 

   114 def readPlistFromResource(path, restype='plst', resid=0):

   115     """Read plst resource from the resource fork of path.

   116     """

   117     warnings.warnpy3k("In 3.x, readPlistFromResource is removed.")

   118     from Carbon.File import FSRef, FSGetResourceForkName

   119     from Carbon.Files import fsRdPerm

   120     from Carbon import Res

   121     fsRef = FSRef(path)

   122     resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdPerm)

   123     Res.UseResFile(resNum)

   124     plistData = Res.Get1Resource(restype, resid).data

   125     Res.CloseResFile(resNum)

   126     return readPlistFromString(plistData)

   127 

   128 

   129 def writePlistToResource(rootObject, path, restype='plst', resid=0):

   130     """Write 'rootObject' as a plst resource to the resource fork of path.

   131     """

   132     warnings.warnpy3k("In 3.x, writePlistToResource is removed.")

   133     from Carbon.File import FSRef, FSGetResourceForkName

   134     from Carbon.Files import fsRdWrPerm

   135     from Carbon import Res

   136     plistData = writePlistToString(rootObject)

   137     fsRef = FSRef(path)

   138     resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdWrPerm)

   139     Res.UseResFile(resNum)

   140     try:

   141         Res.Get1Resource(restype, resid).RemoveResource()

   142     except Res.Error:

   143         pass

   144     res = Res.Resource(plistData)

   145     res.AddResource(restype, resid, '')

   146     res.WriteResource()

   147     Res.CloseResFile(resNum)

   148 

   149 

   150 class DumbXMLWriter:

   151 

   152     def __init__(self, file, indentLevel=0, indent="\t"):

   153         self.file = file

   154         self.stack = []

   155         self.indentLevel = indentLevel

   156         self.indent = indent

   157 

   158     def beginElement(self, element):

   159         self.stack.append(element)

   160         self.writeln("<%s>" % element)

   161         self.indentLevel += 1

   162 

   163     def endElement(self, element):

   164         assert self.indentLevel > 0

   165         assert self.stack.pop() == element

   166         self.indentLevel -= 1

   167         self.writeln("</%s>" % element)

   168 

   169     def simpleElement(self, element, value=None):

   170         if value is not None:

   171             value = _escapeAndEncode(value)

   172             self.writeln("<%s>%s</%s>" % (element, value, element))

   173         else:

   174             self.writeln("<%s/>" % element)

   175 

   176     def writeln(self, line):

   177         if line:

   178             self.file.write(self.indentLevel * self.indent + line + "\n")

   179         else:

   180             self.file.write("\n")

   181 

   182 

   183 # Contents should conform to a subset of ISO 8601

   184 # (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'.  Smaller units may be omitted with

   185 #  a loss of precision)

   186 _dateParser = re.compile(r"(?P<year>\d\d\d\d)(?:-(?P<month>\d\d)(?:-(?P<day>\d\d)(?:T(?P<hour>\d\d)(?::(?P<minute>\d\d)(?::(?P<second>\d\d))?)?)?)?)?Z")

   187 

   188 def _dateFromString(s):

   189     order = ('year', 'month', 'day', 'hour', 'minute', 'second')

   190     gd = _dateParser.match(s).groupdict()

   191     lst = []

   192     for key in order:

   193         val = gd[key]

   194         if val is None:

   195             break

   196         lst.append(int(val))

   197     return datetime.datetime(*lst)

   198 

   199 def _dateToString(d):

   200     return '%04d-%02d-%02dT%02d:%02d:%02dZ' % (

   201         d.year, d.month, d.day,

   202         d.hour, d.minute, d.second

   203     )

   204 

   205 

   206 # Regex to find any control chars, except for \t \n and \r

   207 _controlCharPat = re.compile(

   208     r"[\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0b\x0c\x0e\x0f"

   209     r"\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f]")

   210 

   211 def _escapeAndEncode(text):

   212     m = _controlCharPat.search(text)

   213     if m is not None:

   214         raise ValueError("strings can't contains control characters; "

   215                          "use plistlib.Data instead")

   216     text = text.replace("\r\n", "\n")       # convert DOS line endings

   217     text = text.replace("\r", "\n")         # convert Mac line endings

   218     text = text.replace("&", "&")       # escape '&'

   219     text = text.replace("<", "&lt;")        # escape '<'

   220     text = text.replace(">", ">")        # escape '>'

   221     return text.encode("utf-8")             # encode as UTF-8

   222 

   223 

   224 PLISTHEADER = """\

   225 <?xml version="1.0" encoding="UTF-8"?>

   226 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

   227 """

   228 

   229 class PlistWriter(DumbXMLWriter):

   230 

   231     def __init__(self, file, indentLevel=0, indent="\t", writeHeader=1):

   232         if writeHeader:

   233             file.write(PLISTHEADER)

   234         DumbXMLWriter.__init__(self, file, indentLevel, indent)

   235 

   236     def writeValue(self, value):

   237         if isinstance(value, (str, unicode)):

   238             self.simpleElement("string", value)

   239         elif isinstance(value, bool):

   240             # must switch for bool before int, as bool is a

   241             # subclass of int...

   242             if value:

   243                 self.simpleElement("true")

   244             else:

   245                 self.simpleElement("false")

   246         elif isinstance(value, (int, long)):

   247             self.simpleElement("integer", "%d" % value)

   248         elif isinstance(value, float):

   249             self.simpleElement("real", repr(value))

   250         elif isinstance(value, dict):

   251             self.writeDict(value)

   252         elif isinstance(value, Data):

   253             self.writeData(value)

   254         elif isinstance(value, datetime.datetime):

   255             self.simpleElement("date", _dateToString(value))

   256         elif isinstance(value, (tuple, list)):

   257             self.writeArray(value)

   258         else:

   259             raise TypeError("unsuported type: %s" % type(value))

   260 

   261     def writeData(self, data):

   262         self.beginElement("data")

   263         self.indentLevel -= 1

   264         maxlinelength = 76 - len(self.indent.replace("\t", " " * 8) *

   265                                  self.indentLevel)

   266         for line in data.asBase64(maxlinelength).split("\n"):

   267             if line:

   268                 self.writeln(line)

   269         self.indentLevel += 1

   270         self.endElement("data")

   271 

   272     def writeDict(self, d):

   273         self.beginElement("dict")

   274         items = d.items()

   275         items.sort()

   276         for key, value in items:

   277             if not isinstance(key, (str, unicode)):

   278                 raise TypeError("keys must be strings")

   279             self.simpleElement("key", key)

   280             self.writeValue(value)

   281         self.endElement("dict")

   282 

   283     def writeArray(self, array):

   284         self.beginElement("array")

   285         for value in array:

   286             self.writeValue(value)

   287         self.endElement("array")

   288 

   289 

   290 class _InternalDict(dict):

   291 

   292     # This class is needed while Dict is scheduled for deprecation:

   293     # we only need to warn when a *user* instantiates Dict or when

   294     # the "attribute notation for dict keys" is used.

   295 

   296     def __getattr__(self, attr):

   297         try:

   298             value = self[attr]

   299         except KeyError:

   300             raise AttributeError, attr

   301         from warnings import warn

   302         warn("Attribute access from plist dicts is deprecated, use d[key] "

   303              "notation instead", PendingDeprecationWarning)

   304         return value

   305 

   306     def __setattr__(self, attr, value):

   307         from warnings import warn

   308         warn("Attribute access from plist dicts is deprecated, use d[key] "

   309              "notation instead", PendingDeprecationWarning)

   310         self[attr] = value

   311 

   312     def __delattr__(self, attr):

   313         try:

   314             del self[attr]

   315         except KeyError:

   316             raise AttributeError, attr

   317         from warnings import warn

   318         warn("Attribute access from plist dicts is deprecated, use d[key] "

   319              "notation instead", PendingDeprecationWarning)

   320 

   321 class Dict(_InternalDict):

   322 

   323     def __init__(self, **kwargs):

   324         from warnings import warn

   325         warn("The plistlib.Dict class is deprecated, use builtin dict instead",

   326              PendingDeprecationWarning)

   327         super(Dict, self).__init__(**kwargs)

   328 

   329 

   330 class Plist(_InternalDict):

   331 

   332     """This class has been deprecated. Use readPlist() and writePlist()

   333     functions instead, together with regular dict objects.

   334     """

   335 

   336     def __init__(self, **kwargs):

   337         from warnings import warn

   338         warn("The Plist class is deprecated, use the readPlist() and "

   339              "writePlist() functions instead", PendingDeprecationWarning)

   340         super(Plist, self).__init__(**kwargs)

   341 

   342     def fromFile(cls, pathOrFile):

   343         """Deprecated. Use the readPlist() function instead."""

   344         rootObject = readPlist(pathOrFile)

   345         plist = cls()

   346         plist.update(rootObject)

   347         return plist

   348     fromFile = classmethod(fromFile)

   349 

   350     def write(self, pathOrFile):

   351         """Deprecated. Use the writePlist() function instead."""

   352         writePlist(self, pathOrFile)

   353 

   354 

   355 def _encodeBase64(s, maxlinelength=76):

   356     # copied from base64.encodestring(), with added maxlinelength argument

   357     maxbinsize = (maxlinelength//4)*3

   358     pieces = []

   359     for i in range(0, len(s), maxbinsize):

   360         chunk = s[i : i + maxbinsize]

   361         pieces.append(binascii.b2a_base64(chunk))

   362     return "".join(pieces)

   363 

   364 class Data:

   365 

   366     """Wrapper for binary data."""

   367 

   368     def __init__(self, data):

   369         self.data = data

   370 

   371     def fromBase64(cls, data):

   372         # base64.decodestring just calls binascii.a2b_base64;

   373         # it seems overkill to use both base64 and binascii.

   374         return cls(binascii.a2b_base64(data))

   375     fromBase64 = classmethod(fromBase64)

   376 

   377     def asBase64(self, maxlinelength=76):

   378         return _encodeBase64(self.data, maxlinelength)

   379 

   380     def __cmp__(self, other):

   381         if isinstance(other, self.__class__):

   382             return cmp(self.data, other.data)

   383         elif isinstance(other, str):

   384             return cmp(self.data, other)

   385         else:

   386             return cmp(id(self), id(other))

   387 

   388     def __repr__(self):

   389         return "%s(%s)" % (self.__class__.__name__, repr(self.data))

   390 

   391 

   392 class PlistParser:

   393 

   394     def __init__(self):

   395         self.stack = []

   396         self.currentKey = None

   397         self.root = None

   398 

   399     def parse(self, fileobj):

   400         from xml.parsers.expat import ParserCreate

   401         parser = ParserCreate()

   402         parser.StartElementHandler = self.handleBeginElement

   403         parser.EndElementHandler = self.handleEndElement

   404         parser.CharacterDataHandler = self.handleData

   405         parser.ParseFile(fileobj)

   406         return self.root

   407 

   408     def handleBeginElement(self, element, attrs):

   409         self.data = []

   410         handler = getattr(self, "begin_" + element, None)

   411         if handler is not None:

   412             handler(attrs)

   413 

   414     def handleEndElement(self, element):

   415         handler = getattr(self, "end_" + element, None)

   416         if handler is not None:

   417             handler()

   418 

   419     def handleData(self, data):

   420         self.data.append(data)

   421 

   422     def addObject(self, value):

   423         if self.currentKey is not None:

   424             self.stack[-1][self.currentKey] = value

   425             self.currentKey = None

   426         elif not self.stack:

   427             # this is the root object

   428             self.root = value

   429         else:

   430             self.stack[-1].append(value)

   431 

   432     def getData(self):

   433         data = "".join(self.data)

   434         try:

   435             data = data.encode("ascii")

   436         except UnicodeError:

   437             pass

   438         self.data = []

   439         return data

   440 

   441     # element handlers

   442 

   443     def begin_dict(self, attrs):

   444         d = _InternalDict()

   445         self.addObject(d)

   446         self.stack.append(d)

   447     def end_dict(self):

   448         self.stack.pop()

   449 

   450     def end_key(self):

   451         self.currentKey = self.getData()

   452 

   453     def begin_array(self, attrs):

   454         a = []

   455         self.addObject(a)

   456         self.stack.append(a)

   457     def end_array(self):

   458         self.stack.pop()

   459 

   460     def end_true(self):

   461         self.addObject(True)

   462     def end_false(self):

   463         self.addObject(False)

   464     def end_integer(self):

   465         self.addObject(int(self.getData()))

   466     def end_real(self):

   467         self.addObject(float(self.getData()))

   468     def end_string(self):

   469         self.addObject(self.getData())

   470     def end_data(self):

   471         self.addObject(Data.fromBase64(self.getData()))

   472     def end_date(self):

   473         self.addObject(_dateFromString(self.getData()))