1 r
"""plistlib.py -- a tool to generate and parse MacOSX .plist files.
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.
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.
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).
15 To work with plist data in strings, you can use readPlistFromString()
16 and writePlistToString().
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
23 The <data> plist type is supported through the Data class. This is a
24 thin wrapper around a Python string.
26 Generate Plist example:
30 aList=["A", "B", 12, 32.1, [1, 2, 3]],
34 anotherString="<hello & hi there!>",
35 aUnicodeValue=u'M\xe4ssig, Ma\xdf',
39 someData=Data("<binary gunk>"),
40 someMoreData=Data("<lots of binary gunk>" * 10),
41 aDate=datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
43 # unicode keys are possible, but a little awkward to use:
44 pl[u'\xc5benraa'] = "That was a unicode key."
45 writePlist(pl, fileName)
49 pl = readPlist(pathOrFile)
55 "readPlist", "writePlist", "readPlistFromString", "writePlistToString",
56 "readPlistFromResource", "writePlistToResource",
57 "Plist", "Data", "Dict"
59 # Note: the Plist and Dict classes have been deprecated.
63 from cStringIO
import StringIO
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).
74 if isinstance(pathOrFile
, (str, unicode)):
75 pathOrFile
= open(pathOrFile
)
78 rootObject
= p
.parse(pathOrFile
)
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.
89 if isinstance(pathOrFile
, (str, unicode)):
90 pathOrFile
= open(pathOrFile
, "w")
92 writer
= PlistWriter(pathOrFile
)
93 writer
.writeln("<plist version=\"1.0\">")
94 writer
.writeValue(rootObject
)
95 writer
.writeln("</plist>")
100 def readPlistFromString(data
):
101 """Read a plist data from a string. Return the root object.
103 return readPlist(StringIO(data
))
106 def writePlistToString(rootObject
):
107 """Return 'rootObject' as a plist-formatted string.
110 writePlist(rootObject
, f
)
114 def readPlistFromResource(path
, restype
='plst', resid
=0):
115 """Read plst resource from the resource fork of path.
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
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
)
129 def writePlistToResource(rootObject
, path
, restype
='plst', resid
=0):
130 """Write 'rootObject' as a plst resource to the resource fork of path.
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
)
138 resNum
= Res
.FSOpenResourceFile(fsRef
, FSGetResourceForkName(), fsRdWrPerm
)
139 Res
.UseResFile(resNum
)
141 Res
.Get1Resource(restype
, resid
).RemoveResource()
144 res
= Res
.Resource(plistData
)
145 res
.AddResource(restype
, resid
, '')
147 Res
.CloseResFile(resNum
)
152 def __init__(self
, file, indentLevel
=0, indent
="\t"):
155 self
.indentLevel
= indentLevel
158 def beginElement(self
, element
):
159 self
.stack
.append(element
)
160 self
.writeln("<%s>" % element
)
161 self
.indentLevel
+= 1
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
)
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
))
174 self
.writeln("<%s/>" % element
)
176 def writeln(self
, line
):
178 self
.file.write(self
.indentLevel
* self
.indent
+ line
+ "\n")
180 self
.file.write("\n")
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")
188 def _dateFromString(s
):
189 order
= ('year', 'month', 'day', 'hour', 'minute', 'second')
190 gd
= _dateParser
.match(s
).groupdict()
197 return datetime
.datetime(*lst
)
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
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]")
211 def _escapeAndEncode(text
):
212 m
= _controlCharPat
.search(text
)
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("<", "<") # escape '<'
220 text
= text
.replace(">", ">") # escape '>'
221 return text
.encode("utf-8") # encode as UTF-8
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">
229 class PlistWriter(DumbXMLWriter
):
231 def __init__(self
, file, indentLevel
=0, indent
="\t", writeHeader
=1):
233 file.write(PLISTHEADER
)
234 DumbXMLWriter
.__init
__(self
, file, indentLevel
, indent
)
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
243 self
.simpleElement("true")
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
)
259 raise TypeError("unsuported type: %s" % type(value
))
261 def writeData(self
, data
):
262 self
.beginElement("data")
263 self
.indentLevel
-= 1
264 maxlinelength
= 76 - len(self
.indent
.replace("\t", " " * 8) *
266 for line
in data
.asBase64(maxlinelength
).split("\n"):
269 self
.indentLevel
+= 1
270 self
.endElement("data")
272 def writeDict(self
, d
):
273 self
.beginElement("dict")
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")
283 def writeArray(self
, array
):
284 self
.beginElement("array")
286 self
.writeValue(value
)
287 self
.endElement("array")
290 class _InternalDict(dict):
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.
296 def __getattr__(self
, attr
):
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
)
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
)
312 def __delattr__(self
, attr
):
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
)
321 class Dict(_InternalDict
):
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
)
330 class Plist(_InternalDict
):
332 """This class has been deprecated. Use readPlist() and writePlist()
333 functions instead, together with regular dict objects.
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
)
342 def fromFile(cls
, pathOrFile
):
343 """Deprecated. Use the readPlist() function instead."""
344 rootObject
= readPlist(pathOrFile
)
346 plist
.update(rootObject
)
348 fromFile
= classmethod(fromFile
)
350 def write(self
, pathOrFile
):
351 """Deprecated. Use the writePlist() function instead."""
352 writePlist(self
, pathOrFile
)
355 def _encodeBase64(s
, maxlinelength
=76):
356 # copied from base64.encodestring(), with added maxlinelength argument
357 maxbinsize
= (maxlinelength
//4)*3
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
)
366 """Wrapper for binary data."""
368 def __init__(self
, data
):
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
)
377 def asBase64(self
, maxlinelength
=76):
378 return _encodeBase64(self
.data
, maxlinelength
)
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
)
386 return cmp(id(self
), id(other
))
389 return "%s(%s)" % (self
.__class
__.__name
__, repr(self
.data
))
396 self
.currentKey
= None
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
)
408 def handleBeginElement(self
, element
, attrs
):
410 handler
= getattr(self
, "begin_" + element
, None)
411 if handler
is not None:
414 def handleEndElement(self
, element
):
415 handler
= getattr(self
, "end_" + element
, None)
416 if handler
is not None:
419 def handleData(self
, data
):
420 self
.data
.append(data
)
422 def addObject(self
, value
):
423 if self
.currentKey
is not None:
424 self
.stack
[-1][self
.currentKey
] = value
425 self
.currentKey
= None
427 # this is the root object
430 self
.stack
[-1].append(value
)
433 data
= "".join(self
.data
)
435 data
= data
.encode("ascii")
443 def begin_dict(self
, attrs
):
451 self
.currentKey
= self
.getData()
453 def begin_array(self
, attrs
):
463 self
.addObject(False)
464 def end_integer(self
):
465 self
.addObject(int(self
.getData()))
467 self
.addObject(float(self
.getData()))
468 def end_string(self
):
469 self
.addObject(self
.getData())
471 self
.addObject(Data
.fromBase64(self
.getData()))
473 self
.addObject(_dateFromString(self
.getData()))