Fix duplicate test numbers in extra.decTest
[python.git] / Lib / plistlib.py
blob0b1748cd481e04aac5d95ce7e4ea1d1b35223cac
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
21 UTF-8.
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:
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,
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)
47 Parse Plist example:
49 pl = readPlist(pathOrFile)
50 print pl["aKey"]
51 """
54 __all__ = [
55 "readPlist", "writePlist", "readPlistFromString", "writePlistToString",
56 "readPlistFromResource", "writePlistToResource",
57 "Plist", "Data", "Dict"
59 # Note: the Plist and Dict classes have been deprecated.
61 import binascii
62 import datetime
63 from cStringIO import StringIO
64 import re
65 import warnings
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
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()
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.
109 f = StringIO()
110 writePlist(rootObject, f)
111 return f.getvalue()
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 stacklevel=2)
119 from Carbon.File import FSRef, FSGetResourceForkName
120 from Carbon.Files import fsRdPerm
121 from Carbon import Res
122 fsRef = FSRef(path)
123 resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdPerm)
124 Res.UseResFile(resNum)
125 plistData = Res.Get1Resource(restype, resid).data
126 Res.CloseResFile(resNum)
127 return readPlistFromString(plistData)
130 def writePlistToResource(rootObject, path, restype='plst', resid=0):
131 """Write 'rootObject' as a plst resource to the resource fork of path.
133 warnings.warnpy3k("In 3.x, writePlistToResource is removed.", stacklevel=2)
134 from Carbon.File import FSRef, FSGetResourceForkName
135 from Carbon.Files import fsRdWrPerm
136 from Carbon import Res
137 plistData = writePlistToString(rootObject)
138 fsRef = FSRef(path)
139 resNum = Res.FSOpenResourceFile(fsRef, FSGetResourceForkName(), fsRdWrPerm)
140 Res.UseResFile(resNum)
141 try:
142 Res.Get1Resource(restype, resid).RemoveResource()
143 except Res.Error:
144 pass
145 res = Res.Resource(plistData)
146 res.AddResource(restype, resid, '')
147 res.WriteResource()
148 Res.CloseResFile(resNum)
151 class DumbXMLWriter:
153 def __init__(self, file, indentLevel=0, indent="\t"):
154 self.file = file
155 self.stack = []
156 self.indentLevel = indentLevel
157 self.indent = indent
159 def beginElement(self, element):
160 self.stack.append(element)
161 self.writeln("<%s>" % element)
162 self.indentLevel += 1
164 def endElement(self, element):
165 assert self.indentLevel > 0
166 assert self.stack.pop() == element
167 self.indentLevel -= 1
168 self.writeln("</%s>" % element)
170 def simpleElement(self, element, value=None):
171 if value is not None:
172 value = _escapeAndEncode(value)
173 self.writeln("<%s>%s</%s>" % (element, value, element))
174 else:
175 self.writeln("<%s/>" % element)
177 def writeln(self, line):
178 if line:
179 self.file.write(self.indentLevel * self.indent + line + "\n")
180 else:
181 self.file.write("\n")
184 # Contents should conform to a subset of ISO 8601
185 # (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'. Smaller units may be omitted with
186 # a loss of precision)
187 _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")
189 def _dateFromString(s):
190 order = ('year', 'month', 'day', 'hour', 'minute', 'second')
191 gd = _dateParser.match(s).groupdict()
192 lst = []
193 for key in order:
194 val = gd[key]
195 if val is None:
196 break
197 lst.append(int(val))
198 return datetime.datetime(*lst)
200 def _dateToString(d):
201 return '%04d-%02d-%02dT%02d:%02d:%02dZ' % (
202 d.year, d.month, d.day,
203 d.hour, d.minute, d.second
207 # Regex to find any control chars, except for \t \n and \r
208 _controlCharPat = re.compile(
209 r"[\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0b\x0c\x0e\x0f"
210 r"\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f]")
212 def _escapeAndEncode(text):
213 m = _controlCharPat.search(text)
214 if m is not None:
215 raise ValueError("strings can't contains control characters; "
216 "use plistlib.Data instead")
217 text = text.replace("\r\n", "\n") # convert DOS line endings
218 text = text.replace("\r", "\n") # convert Mac line endings
219 text = text.replace("&", "&amp;") # escape '&'
220 text = text.replace("<", "&lt;") # escape '<'
221 text = text.replace(">", "&gt;") # escape '>'
222 return text.encode("utf-8") # encode as UTF-8
225 PLISTHEADER = """\
226 <?xml version="1.0" encoding="UTF-8"?>
227 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
230 class PlistWriter(DumbXMLWriter):
232 def __init__(self, file, indentLevel=0, indent="\t", writeHeader=1):
233 if writeHeader:
234 file.write(PLISTHEADER)
235 DumbXMLWriter.__init__(self, file, indentLevel, indent)
237 def writeValue(self, value):
238 if isinstance(value, (str, unicode)):
239 self.simpleElement("string", value)
240 elif isinstance(value, bool):
241 # must switch for bool before int, as bool is a
242 # subclass of int...
243 if value:
244 self.simpleElement("true")
245 else:
246 self.simpleElement("false")
247 elif isinstance(value, (int, long)):
248 self.simpleElement("integer", "%d" % value)
249 elif isinstance(value, float):
250 self.simpleElement("real", repr(value))
251 elif isinstance(value, dict):
252 self.writeDict(value)
253 elif isinstance(value, Data):
254 self.writeData(value)
255 elif isinstance(value, datetime.datetime):
256 self.simpleElement("date", _dateToString(value))
257 elif isinstance(value, (tuple, list)):
258 self.writeArray(value)
259 else:
260 raise TypeError("unsuported type: %s" % type(value))
262 def writeData(self, data):
263 self.beginElement("data")
264 self.indentLevel -= 1
265 maxlinelength = 76 - len(self.indent.replace("\t", " " * 8) *
266 self.indentLevel)
267 for line in data.asBase64(maxlinelength).split("\n"):
268 if line:
269 self.writeln(line)
270 self.indentLevel += 1
271 self.endElement("data")
273 def writeDict(self, d):
274 self.beginElement("dict")
275 items = d.items()
276 items.sort()
277 for key, value in items:
278 if not isinstance(key, (str, unicode)):
279 raise TypeError("keys must be strings")
280 self.simpleElement("key", key)
281 self.writeValue(value)
282 self.endElement("dict")
284 def writeArray(self, array):
285 self.beginElement("array")
286 for value in array:
287 self.writeValue(value)
288 self.endElement("array")
291 class _InternalDict(dict):
293 # This class is needed while Dict is scheduled for deprecation:
294 # we only need to warn when a *user* instantiates Dict or when
295 # the "attribute notation for dict keys" is used.
297 def __getattr__(self, attr):
298 try:
299 value = self[attr]
300 except KeyError:
301 raise AttributeError, attr
302 from warnings import warn
303 warn("Attribute access from plist dicts is deprecated, use d[key] "
304 "notation instead", PendingDeprecationWarning, 2)
305 return value
307 def __setattr__(self, attr, value):
308 from warnings import warn
309 warn("Attribute access from plist dicts is deprecated, use d[key] "
310 "notation instead", PendingDeprecationWarning, 2)
311 self[attr] = value
313 def __delattr__(self, attr):
314 try:
315 del self[attr]
316 except KeyError:
317 raise AttributeError, attr
318 from warnings import warn
319 warn("Attribute access from plist dicts is deprecated, use d[key] "
320 "notation instead", PendingDeprecationWarning, 2)
322 class Dict(_InternalDict):
324 def __init__(self, **kwargs):
325 from warnings import warn
326 warn("The plistlib.Dict class is deprecated, use builtin dict instead",
327 PendingDeprecationWarning, 2)
328 super(Dict, self).__init__(**kwargs)
331 class Plist(_InternalDict):
333 """This class has been deprecated. Use readPlist() and writePlist()
334 functions instead, together with regular dict objects.
337 def __init__(self, **kwargs):
338 from warnings import warn
339 warn("The Plist class is deprecated, use the readPlist() and "
340 "writePlist() functions instead", PendingDeprecationWarning, 2)
341 super(Plist, self).__init__(**kwargs)
343 def fromFile(cls, pathOrFile):
344 """Deprecated. Use the readPlist() function instead."""
345 rootObject = readPlist(pathOrFile)
346 plist = cls()
347 plist.update(rootObject)
348 return plist
349 fromFile = classmethod(fromFile)
351 def write(self, pathOrFile):
352 """Deprecated. Use the writePlist() function instead."""
353 writePlist(self, pathOrFile)
356 def _encodeBase64(s, maxlinelength=76):
357 # copied from base64.encodestring(), with added maxlinelength argument
358 maxbinsize = (maxlinelength//4)*3
359 pieces = []
360 for i in range(0, len(s), maxbinsize):
361 chunk = s[i : i + maxbinsize]
362 pieces.append(binascii.b2a_base64(chunk))
363 return "".join(pieces)
365 class Data:
367 """Wrapper for binary data."""
369 def __init__(self, data):
370 self.data = data
372 def fromBase64(cls, data):
373 # base64.decodestring just calls binascii.a2b_base64;
374 # it seems overkill to use both base64 and binascii.
375 return cls(binascii.a2b_base64(data))
376 fromBase64 = classmethod(fromBase64)
378 def asBase64(self, maxlinelength=76):
379 return _encodeBase64(self.data, maxlinelength)
381 def __cmp__(self, other):
382 if isinstance(other, self.__class__):
383 return cmp(self.data, other.data)
384 elif isinstance(other, str):
385 return cmp(self.data, other)
386 else:
387 return cmp(id(self), id(other))
389 def __repr__(self):
390 return "%s(%s)" % (self.__class__.__name__, repr(self.data))
393 class PlistParser:
395 def __init__(self):
396 self.stack = []
397 self.currentKey = None
398 self.root = None
400 def parse(self, fileobj):
401 from xml.parsers.expat import ParserCreate
402 parser = ParserCreate()
403 parser.StartElementHandler = self.handleBeginElement
404 parser.EndElementHandler = self.handleEndElement
405 parser.CharacterDataHandler = self.handleData
406 parser.ParseFile(fileobj)
407 return self.root
409 def handleBeginElement(self, element, attrs):
410 self.data = []
411 handler = getattr(self, "begin_" + element, None)
412 if handler is not None:
413 handler(attrs)
415 def handleEndElement(self, element):
416 handler = getattr(self, "end_" + element, None)
417 if handler is not None:
418 handler()
420 def handleData(self, data):
421 self.data.append(data)
423 def addObject(self, value):
424 if self.currentKey is not None:
425 self.stack[-1][self.currentKey] = value
426 self.currentKey = None
427 elif not self.stack:
428 # this is the root object
429 self.root = value
430 else:
431 self.stack[-1].append(value)
433 def getData(self):
434 data = "".join(self.data)
435 try:
436 data = data.encode("ascii")
437 except UnicodeError:
438 pass
439 self.data = []
440 return data
442 # element handlers
444 def begin_dict(self, attrs):
445 d = _InternalDict()
446 self.addObject(d)
447 self.stack.append(d)
448 def end_dict(self):
449 self.stack.pop()
451 def end_key(self):
452 self.currentKey = self.getData()
454 def begin_array(self, attrs):
455 a = []
456 self.addObject(a)
457 self.stack.append(a)
458 def end_array(self):
459 self.stack.pop()
461 def end_true(self):
462 self.addObject(True)
463 def end_false(self):
464 self.addObject(False)
465 def end_integer(self):
466 self.addObject(int(self.getData()))
467 def end_real(self):
468 self.addObject(float(self.getData()))
469 def end_string(self):
470 self.addObject(self.getData())
471 def end_data(self):
472 self.addObject(Data.fromBase64(self.getData()))
473 def end_date(self):
474 self.addObject(_dateFromString(self.getData()))