Python code coverage for Lib/plistlib.py

#	count	content
1	n/a	r"""plistlib.py -- a tool to generate and parse MacOSX .plist files.
2	n/a
3	n/a	The property list (.plist) file format is a simple XML pickle supporting
4	n/a	basic object types, like dictionaries, lists, numbers and strings.
5	n/a	Usually the top level object is a dictionary.
6	n/a
7	n/a	To write out a plist file, use the dump(value, file)
8	n/a	function. 'value' is the top level object, 'file' is
9	n/a	a (writable) file object.
10	n/a
11	n/a	To parse a plist from a file, use the load(file) function,
12	n/a	with a (readable) file object as the only argument. It
13	n/a	returns the top level object (again, usually a dictionary).
14	n/a
15	n/a	To work with plist data in bytes objects, you can use loads()
16	n/a	and dumps().
17	n/a
18	n/a	Values can be strings, integers, floats, booleans, tuples, lists,
19	n/a	dictionaries (but only with string keys), Data, bytes, bytearray, or
20	n/a	datetime.datetime objects.
21	n/a
22	n/a	Generate Plist example:
23	n/a
24	n/a	pl = dict(
25	n/a	aString = "Doodah",
26	n/a	aList = ["A", "B", 12, 32.1, [1, 2, 3]],
27	n/a	aFloat = 0.1,
28	n/a	anInt = 728,
29	n/a	aDict = dict(
30	n/a	anotherString = "<hello & hi there!>",
31	n/a	aUnicodeValue = "M\xe4ssig, Ma\xdf",
32	n/a	aTrueValue = True,
33	n/a	aFalseValue = False,
34	n/a	),
35	n/a	someData = b"<binary gunk>",
36	n/a	someMoreData = b"<lots of binary gunk>" * 10,
37	n/a	aDate = datetime.datetime.fromtimestamp(time.mktime(time.gmtime())),
38	n/a	)
39	n/a	with open(fileName, 'wb') as fp:
40	n/a	dump(pl, fp)
41	n/a
42	n/a	Parse Plist example:
43	n/a
44	n/a	with open(fileName, 'rb') as fp:
45	n/a	pl = load(fp)
46	n/a	print(pl["aKey"])
47	n/a	"""
48	n/a	__all__ = [
49	n/a	"readPlist", "writePlist", "readPlistFromBytes", "writePlistToBytes",
50	n/a	"Plist", "Data", "Dict", "InvalidFileException", "FMT_XML", "FMT_BINARY",
51	n/a	"load", "dump", "loads", "dumps"
52	n/a	]
53	n/a
54	n/a	import binascii
55	n/a	import codecs
56	n/a	import contextlib
57	n/a	import datetime
58	n/a	import enum
59	n/a	from io import BytesIO
60	n/a	import itertools
61	n/a	import os
62	n/a	import re
63	n/a	import struct
64	n/a	from warnings import warn
65	n/a	from xml.parsers.expat import ParserCreate
66	n/a
67	n/a
68	n/a	PlistFormat = enum.Enum('PlistFormat', 'FMT_XML FMT_BINARY', module=__name__)
69	n/a	globals().update(PlistFormat.__members__)
70	n/a
71	n/a
72	n/a	#
73	n/a	#
74	n/a	# Deprecated functionality
75	n/a	#
76	n/a	#
77	n/a
78	n/a
79	n/a	class _InternalDict(dict):
80	n/a
81	n/a	# This class is needed while Dict is scheduled for deprecation:
82	n/a	# we only need to warn when a user instantiates Dict or when
83	n/a	# the "attribute notation for dict keys" is used.
84	n/a	__slots__ = ()
85	n/a
86	n/a	def __getattr__(self, attr):
87	n/a	try:
88	n/a	value = self[attr]
89	n/a	except KeyError:
90	n/a	raise AttributeError(attr)
91	n/a	warn("Attribute access from plist dicts is deprecated, use d[key] "
92	n/a	"notation instead", DeprecationWarning, 2)
93	n/a	return value
94	n/a
95	n/a	def __setattr__(self, attr, value):
96	n/a	warn("Attribute access from plist dicts is deprecated, use d[key] "
97	n/a	"notation instead", DeprecationWarning, 2)
98	n/a	self[attr] = value
99	n/a
100	n/a	def __delattr__(self, attr):
101	n/a	try:
102	n/a	del self[attr]
103	n/a	except KeyError:
104	n/a	raise AttributeError(attr)
105	n/a	warn("Attribute access from plist dicts is deprecated, use d[key] "
106	n/a	"notation instead", DeprecationWarning, 2)
107	n/a
108	n/a
109	n/a	class Dict(_InternalDict):
110	n/a
111	n/a	def __init__(self, **kwargs):
112	n/a	warn("The plistlib.Dict class is deprecated, use builtin dict instead",
113	n/a	DeprecationWarning, 2)
114	n/a	super().__init__(**kwargs)
115	n/a
116	n/a
117	n/a	@contextlib.contextmanager
118	n/a	def _maybe_open(pathOrFile, mode):
119	n/a	if isinstance(pathOrFile, str):
120	n/a	with open(pathOrFile, mode) as fp:
121	n/a	yield fp
122	n/a
123	n/a	else:
124	n/a	yield pathOrFile
125	n/a
126	n/a
127	n/a	class Plist(_InternalDict):
128	n/a	"""This class has been deprecated. Use dump() and load()
129	n/a	functions instead, together with regular dict objects.
130	n/a	"""
131	n/a
132	n/a	def __init__(self, **kwargs):
133	n/a	warn("The Plist class is deprecated, use the load() and "
134	n/a	"dump() functions instead", DeprecationWarning, 2)
135	n/a	super().__init__(**kwargs)
136	n/a
137	n/a	@classmethod
138	n/a	def fromFile(cls, pathOrFile):
139	n/a	"""Deprecated. Use the load() function instead."""
140	n/a	with _maybe_open(pathOrFile, 'rb') as fp:
141	n/a	value = load(fp)
142	n/a	plist = cls()
143	n/a	plist.update(value)
144	n/a	return plist
145	n/a
146	n/a	def write(self, pathOrFile):
147	n/a	"""Deprecated. Use the dump() function instead."""
148	n/a	with _maybe_open(pathOrFile, 'wb') as fp:
149	n/a	dump(self, fp)
150	n/a
151	n/a
152	n/a	def readPlist(pathOrFile):
153	n/a	"""
154	n/a	Read a .plist from a path or file. pathOrFile should either
155	n/a	be a file name, or a readable binary file object.
156	n/a
157	n/a	This function is deprecated, use load instead.
158	n/a	"""
159	n/a	warn("The readPlist function is deprecated, use load() instead",
160	n/a	DeprecationWarning, 2)
161	n/a
162	n/a	with _maybe_open(pathOrFile, 'rb') as fp:
163	n/a	return load(fp, fmt=None, use_builtin_types=False,
164	n/a	dict_type=_InternalDict)
165	n/a
166	n/a	def writePlist(value, pathOrFile):
167	n/a	"""
168	n/a	Write 'value' to a .plist file. 'pathOrFile' may either be a
169	n/a	file name or a (writable) file object.
170	n/a
171	n/a	This function is deprecated, use dump instead.
172	n/a	"""
173	n/a	warn("The writePlist function is deprecated, use dump() instead",
174	n/a	DeprecationWarning, 2)
175	n/a	with _maybe_open(pathOrFile, 'wb') as fp:
176	n/a	dump(value, fp, fmt=FMT_XML, sort_keys=True, skipkeys=False)
177	n/a
178	n/a
179	n/a	def readPlistFromBytes(data):
180	n/a	"""
181	n/a	Read a plist data from a bytes object. Return the root object.
182	n/a
183	n/a	This function is deprecated, use loads instead.
184	n/a	"""
185	n/a	warn("The readPlistFromBytes function is deprecated, use loads() instead",
186	n/a	DeprecationWarning, 2)
187	n/a	return load(BytesIO(data), fmt=None, use_builtin_types=False,
188	n/a	dict_type=_InternalDict)
189	n/a
190	n/a
191	n/a	def writePlistToBytes(value):
192	n/a	"""
193	n/a	Return 'value' as a plist-formatted bytes object.
194	n/a
195	n/a	This function is deprecated, use dumps instead.
196	n/a	"""
197	n/a	warn("The writePlistToBytes function is deprecated, use dumps() instead",
198	n/a	DeprecationWarning, 2)
199	n/a	f = BytesIO()
200	n/a	dump(value, f, fmt=FMT_XML, sort_keys=True, skipkeys=False)
201	n/a	return f.getvalue()
202	n/a
203	n/a
204	n/a	class Data:
205	n/a	"""
206	n/a	Wrapper for binary data.
207	n/a
208	n/a	This class is deprecated, use a bytes object instead.
209	n/a	"""
210	n/a
211	n/a	def __init__(self, data):
212	n/a	if not isinstance(data, bytes):
213	n/a	raise TypeError("data must be as bytes")
214	n/a	self.data = data
215	n/a
216	n/a	@classmethod
217	n/a	def fromBase64(cls, data):
218	n/a	# base64.decodebytes just calls binascii.a2b_base64;
219	n/a	# it seems overkill to use both base64 and binascii.
220	n/a	return cls(_decode_base64(data))
221	n/a
222	n/a	def asBase64(self, maxlinelength=76):
223	n/a	return _encode_base64(self.data, maxlinelength)
224	n/a
225	n/a	def __eq__(self, other):
226	n/a	if isinstance(other, self.__class__):
227	n/a	return self.data == other.data
228	n/a	elif isinstance(other, bytes):
229	n/a	return self.data == other
230	n/a	else:
231	n/a	return NotImplemented
232	n/a
233	n/a	def __repr__(self):
234	n/a	return "%s(%s)" % (self.__class__.__name__, repr(self.data))
235	n/a
236	n/a	#
237	n/a	#
238	n/a	# End of deprecated functionality
239	n/a	#
240	n/a	#
241	n/a
242	n/a
243	n/a	#
244	n/a	# XML support
245	n/a	#
246	n/a
247	n/a
248	n/a	# XML 'header'
249	n/a	PLISTHEADER = b"""\
250	n/a	<?xml version="1.0" encoding="UTF-8"?>
251	n/a	<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
252	n/a	"""
253	n/a
254	n/a
255	n/a	# Regex to find any control chars, except for \t \n and \r
256	n/a	_controlCharPat = re.compile(
257	n/a	r"[\x00\x01\x02\x03\x04\x05\x06\x07\x08\x0b\x0c\x0e\x0f"
258	n/a	r"\x10\x11\x12\x13\x14\x15\x16\x17\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f]")
259	n/a
260	n/a	def _encode_base64(s, maxlinelength=76):
261	n/a	# copied from base64.encodebytes(), with added maxlinelength argument
262	n/a	maxbinsize = (maxlinelength//4)*3
263	n/a	pieces = []
264	n/a	for i in range(0, len(s), maxbinsize):
265	n/a	chunk = s[i : i + maxbinsize]
266	n/a	pieces.append(binascii.b2a_base64(chunk))
267	n/a	return b''.join(pieces)
268	n/a
269	n/a	def _decode_base64(s):
270	n/a	if isinstance(s, str):
271	n/a	return binascii.a2b_base64(s.encode("utf-8"))
272	n/a
273	n/a	else:
274	n/a	return binascii.a2b_base64(s)
275	n/a
276	n/a	# Contents should conform to a subset of ISO 8601
277	n/a	# (in particular, YYYY '-' MM '-' DD 'T' HH ':' MM ':' SS 'Z'. Smaller units
278	n/a	# may be omitted with # a loss of precision)
279	n/a	_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", re.ASCII)
280	n/a
281	n/a
282	n/a	def _date_from_string(s):
283	n/a	order = ('year', 'month', 'day', 'hour', 'minute', 'second')
284	n/a	gd = _dateParser.match(s).groupdict()
285	n/a	lst = []
286	n/a	for key in order:
287	n/a	val = gd[key]
288	n/a	if val is None:
289	n/a	break
290	n/a	lst.append(int(val))
291	n/a	return datetime.datetime(*lst)
292	n/a
293	n/a
294	n/a	def _date_to_string(d):
295	n/a	return '%04d-%02d-%02dT%02d:%02d:%02dZ' % (
296	n/a	d.year, d.month, d.day,
297	n/a	d.hour, d.minute, d.second
298	n/a	)
299	n/a
300	n/a	def _escape(text):
301	n/a	m = _controlCharPat.search(text)
302	n/a	if m is not None:
303	n/a	raise ValueError("strings can't contains control characters; "
304	n/a	"use bytes instead")
305	n/a	text = text.replace("\r\n", "\n") # convert DOS line endings
306	n/a	text = text.replace("\r", "\n") # convert Mac line endings
307	n/a	text = text.replace("&", "&") # escape '&'
308	n/a	text = text.replace("<", "<") # escape '<'
309	n/a	text = text.replace(">", ">") # escape '>'
310	n/a	return text
311	n/a
312	n/a	class _PlistParser:
313	n/a	def __init__(self, use_builtin_types, dict_type):
314	n/a	self.stack = []
315	n/a	self.current_key = None
316	n/a	self.root = None
317	n/a	self._use_builtin_types = use_builtin_types
318	n/a	self._dict_type = dict_type
319	n/a
320	n/a	def parse(self, fileobj):
321	n/a	self.parser = ParserCreate()
322	n/a	self.parser.StartElementHandler = self.handle_begin_element
323	n/a	self.parser.EndElementHandler = self.handle_end_element
324	n/a	self.parser.CharacterDataHandler = self.handle_data
325	n/a	self.parser.ParseFile(fileobj)
326	n/a	return self.root
327	n/a
328	n/a	def handle_begin_element(self, element, attrs):
329	n/a	self.data = []
330	n/a	handler = getattr(self, "begin_" + element, None)
331	n/a	if handler is not None:
332	n/a	handler(attrs)
333	n/a
334	n/a	def handle_end_element(self, element):
335	n/a	handler = getattr(self, "end_" + element, None)
336	n/a	if handler is not None:
337	n/a	handler()
338	n/a
339	n/a	def handle_data(self, data):
340	n/a	self.data.append(data)
341	n/a
342	n/a	def add_object(self, value):
343	n/a	if self.current_key is not None:
344	n/a	if not isinstance(self.stack[-1], type({})):
345	n/a	raise ValueError("unexpected element at line %d" %
346	n/a	self.parser.CurrentLineNumber)
347	n/a	self.stack[-1][self.current_key] = value
348	n/a	self.current_key = None
349	n/a	elif not self.stack:
350	n/a	# this is the root object
351	n/a	self.root = value
352	n/a	else:
353	n/a	if not isinstance(self.stack[-1], type([])):
354	n/a	raise ValueError("unexpected element at line %d" %
355	n/a	self.parser.CurrentLineNumber)
356	n/a	self.stack[-1].append(value)
357	n/a
358	n/a	def get_data(self):
359	n/a	data = ''.join(self.data)
360	n/a	self.data = []
361	n/a	return data
362	n/a
363	n/a	# element handlers
364	n/a
365	n/a	def begin_dict(self, attrs):
366	n/a	d = self._dict_type()
367	n/a	self.add_object(d)
368	n/a	self.stack.append(d)
369	n/a
370	n/a	def end_dict(self):
371	n/a	if self.current_key:
372	n/a	raise ValueError("missing value for key '%s' at line %d" %
373	n/a	(self.current_key,self.parser.CurrentLineNumber))
374	n/a	self.stack.pop()
375	n/a
376	n/a	def end_key(self):
377	n/a	if self.current_key or not isinstance(self.stack[-1], type({})):
378	n/a	raise ValueError("unexpected key at line %d" %
379	n/a	self.parser.CurrentLineNumber)
380	n/a	self.current_key = self.get_data()
381	n/a
382	n/a	def begin_array(self, attrs):
383	n/a	a = []
384	n/a	self.add_object(a)
385	n/a	self.stack.append(a)
386	n/a
387	n/a	def end_array(self):
388	n/a	self.stack.pop()
389	n/a
390	n/a	def end_true(self):
391	n/a	self.add_object(True)
392	n/a
393	n/a	def end_false(self):
394	n/a	self.add_object(False)
395	n/a
396	n/a	def end_integer(self):
397	n/a	self.add_object(int(self.get_data()))
398	n/a
399	n/a	def end_real(self):
400	n/a	self.add_object(float(self.get_data()))
401	n/a
402	n/a	def end_string(self):
403	n/a	self.add_object(self.get_data())
404	n/a
405	n/a	def end_data(self):
406	n/a	if self._use_builtin_types:
407	n/a	self.add_object(_decode_base64(self.get_data()))
408	n/a
409	n/a	else:
410	n/a	self.add_object(Data.fromBase64(self.get_data()))
411	n/a
412	n/a	def end_date(self):
413	n/a	self.add_object(_date_from_string(self.get_data()))
414	n/a
415	n/a
416	n/a	class _DumbXMLWriter:
417	n/a	def __init__(self, file, indent_level=0, indent="\t"):
418	n/a	self.file = file
419	n/a	self.stack = []
420	n/a	self._indent_level = indent_level
421	n/a	self.indent = indent
422	n/a
423	n/a	def begin_element(self, element):
424	n/a	self.stack.append(element)
425	n/a	self.writeln("<%s>" % element)
426	n/a	self._indent_level += 1
427	n/a
428	n/a	def end_element(self, element):
429	n/a	assert self._indent_level > 0
430	n/a	assert self.stack.pop() == element
431	n/a	self._indent_level -= 1
432	n/a	self.writeln("</%s>" % element)
433	n/a
434	n/a	def simple_element(self, element, value=None):
435	n/a	if value is not None:
436	n/a	value = _escape(value)
437	n/a	self.writeln("<%s>%s</%s>" % (element, value, element))
438	n/a
439	n/a	else:
440	n/a	self.writeln("<%s/>" % element)
441	n/a
442	n/a	def writeln(self, line):
443	n/a	if line:
444	n/a	# plist has fixed encoding of utf-8
445	n/a
446	n/a	# XXX: is this test needed?
447	n/a	if isinstance(line, str):
448	n/a	line = line.encode('utf-8')
449	n/a	self.file.write(self._indent_level * self.indent)
450	n/a	self.file.write(line)
451	n/a	self.file.write(b'\n')
452	n/a
453	n/a
454	n/a	class _PlistWriter(_DumbXMLWriter):
455	n/a	def __init__(
456	n/a	self, file, indent_level=0, indent=b"\t", writeHeader=1,
457	n/a	sort_keys=True, skipkeys=False):
458	n/a
459	n/a	if writeHeader:
460	n/a	file.write(PLISTHEADER)
461	n/a	_DumbXMLWriter.__init__(self, file, indent_level, indent)
462	n/a	self._sort_keys = sort_keys
463	n/a	self._skipkeys = skipkeys
464	n/a
465	n/a	def write(self, value):
466	n/a	self.writeln("<plist version=\"1.0\">")
467	n/a	self.write_value(value)
468	n/a	self.writeln("</plist>")
469	n/a
470	n/a	def write_value(self, value):
471	n/a	if isinstance(value, str):
472	n/a	self.simple_element("string", value)
473	n/a
474	n/a	elif value is True:
475	n/a	self.simple_element("true")
476	n/a
477	n/a	elif value is False:
478	n/a	self.simple_element("false")
479	n/a
480	n/a	elif isinstance(value, int):
481	n/a	if -1 << 63 <= value < 1 << 64:
482	n/a	self.simple_element("integer", "%d" % value)
483	n/a	else:
484	n/a	raise OverflowError(value)
485	n/a
486	n/a	elif isinstance(value, float):
487	n/a	self.simple_element("real", repr(value))
488	n/a
489	n/a	elif isinstance(value, dict):
490	n/a	self.write_dict(value)
491	n/a
492	n/a	elif isinstance(value, Data):
493	n/a	self.write_data(value)
494	n/a
495	n/a	elif isinstance(value, (bytes, bytearray)):
496	n/a	self.write_bytes(value)
497	n/a
498	n/a	elif isinstance(value, datetime.datetime):
499	n/a	self.simple_element("date", _date_to_string(value))
500	n/a
501	n/a	elif isinstance(value, (tuple, list)):
502	n/a	self.write_array(value)
503	n/a
504	n/a	else:
505	n/a	raise TypeError("unsupported type: %s" % type(value))
506	n/a
507	n/a	def write_data(self, data):
508	n/a	self.write_bytes(data.data)
509	n/a
510	n/a	def write_bytes(self, data):
511	n/a	self.begin_element("data")
512	n/a	self._indent_level -= 1
513	n/a	maxlinelength = max(
514	n/a	16,
515	n/a	76 - len(self.indent.replace(b"\t", b" " * 8) * self._indent_level))
516	n/a
517	n/a	for line in _encode_base64(data, maxlinelength).split(b"\n"):
518	n/a	if line:
519	n/a	self.writeln(line)
520	n/a	self._indent_level += 1
521	n/a	self.end_element("data")
522	n/a
523	n/a	def write_dict(self, d):
524	n/a	if d:
525	n/a	self.begin_element("dict")
526	n/a	if self._sort_keys:
527	n/a	items = sorted(d.items())
528	n/a	else:
529	n/a	items = d.items()
530	n/a
531	n/a	for key, value in items:
532	n/a	if not isinstance(key, str):
533	n/a	if self._skipkeys:
534	n/a	continue
535	n/a	raise TypeError("keys must be strings")
536	n/a	self.simple_element("key", key)
537	n/a	self.write_value(value)
538	n/a	self.end_element("dict")
539	n/a
540	n/a	else:
541	n/a	self.simple_element("dict")
542	n/a
543	n/a	def write_array(self, array):
544	n/a	if array:
545	n/a	self.begin_element("array")
546	n/a	for value in array:
547	n/a	self.write_value(value)
548	n/a	self.end_element("array")
549	n/a
550	n/a	else:
551	n/a	self.simple_element("array")
552	n/a
553	n/a
554	n/a	def _is_fmt_xml(header):
555	n/a	prefixes = (b'<?xml', b'<plist')
556	n/a
557	n/a	for pfx in prefixes:
558	n/a	if header.startswith(pfx):
559	n/a	return True
560	n/a
561	n/a	# Also check for alternative XML encodings, this is slightly
562	n/a	# overkill because the Apple tools (and plistlib) will not
563	n/a	# generate files with these encodings.
564	n/a	for bom, encoding in (
565	n/a	(codecs.BOM_UTF8, "utf-8"),
566	n/a	(codecs.BOM_UTF16_BE, "utf-16-be"),
567	n/a	(codecs.BOM_UTF16_LE, "utf-16-le"),
568	n/a	# expat does not support utf-32
569	n/a	#(codecs.BOM_UTF32_BE, "utf-32-be"),
570	n/a	#(codecs.BOM_UTF32_LE, "utf-32-le"),
571	n/a	):
572	n/a	if not header.startswith(bom):
573	n/a	continue
574	n/a
575	n/a	for start in prefixes:
576	n/a	prefix = bom + start.decode('ascii').encode(encoding)
577	n/a	if header[:len(prefix)] == prefix:
578	n/a	return True
579	n/a
580	n/a	return False
581	n/a
582	n/a	#
583	n/a	# Binary Plist
584	n/a	#
585	n/a
586	n/a
587	n/a	class InvalidFileException (ValueError):
588	n/a	def __init__(self, message="Invalid file"):
589	n/a	ValueError.__init__(self, message)
590	n/a
591	n/a	_BINARY_FORMAT = {1: 'B', 2: 'H', 4: 'L', 8: 'Q'}
592	n/a
593	n/a	class _BinaryPlistParser:
594	n/a	"""
595	n/a	Read or write a binary plist file, following the description of the binary
596	n/a	format. Raise InvalidFileException in case of error, otherwise return the
597	n/a	root object.
598	n/a
599	n/a	see also: http://opensource.apple.com/source/CF/CF-744.18/CFBinaryPList.c
600	n/a	"""
601	n/a	def __init__(self, use_builtin_types, dict_type):
602	n/a	self._use_builtin_types = use_builtin_types
603	n/a	self._dict_type = dict_type
604	n/a
605	n/a	def parse(self, fp):
606	n/a	try:
607	n/a	# The basic file format:
608	n/a	# HEADER
609	n/a	# object...
610	n/a	# refid->offset...
611	n/a	# TRAILER
612	n/a	self._fp = fp
613	n/a	self._fp.seek(-32, os.SEEK_END)
614	n/a	trailer = self._fp.read(32)
615	n/a	if len(trailer) != 32:
616	n/a	raise InvalidFileException()
617	n/a	(
618	n/a	offset_size, self._ref_size, num_objects, top_object,
619	n/a	offset_table_offset
620	n/a	) = struct.unpack('>6xBBQQQ', trailer)
621	n/a	self._fp.seek(offset_table_offset)
622	n/a	self._object_offsets = self._read_ints(num_objects, offset_size)
623	n/a	return self._read_object(self._object_offsets[top_object])
624	n/a
625	n/a	except (OSError, IndexError, struct.error):
626	n/a	raise InvalidFileException()
627	n/a
628	n/a	def _get_size(self, tokenL):
629	n/a	""" return the size of the next object."""
630	n/a	if tokenL == 0xF:
631	n/a	m = self._fp.read(1)[0] & 0x3
632	n/a	s = 1 << m
633	n/a	f = '>' + _BINARY_FORMAT[s]
634	n/a	return struct.unpack(f, self._fp.read(s))[0]
635	n/a
636	n/a	return tokenL
637	n/a
638	n/a	def _read_ints(self, n, size):
639	n/a	data = self._fp.read(size * n)
640	n/a	if size in _BINARY_FORMAT:
641	n/a	return struct.unpack('>' + _BINARY_FORMAT[size] * n, data)
642	n/a	else:
643	n/a	return tuple(int.from_bytes(data[i: i + size], 'big')
644	n/a	for i in range(0, size * n, size))
645	n/a
646	n/a	def _read_refs(self, n):
647	n/a	return self._read_ints(n, self._ref_size)
648	n/a
649	n/a	def _read_object(self, offset):
650	n/a	"""
651	n/a	read the object at offset.
652	n/a
653	n/a	May recursively read sub-objects (content of an array/dict/set)
654	n/a	"""
655	n/a	self._fp.seek(offset)
656	n/a	token = self._fp.read(1)[0]
657	n/a	tokenH, tokenL = token & 0xF0, token & 0x0F
658	n/a
659	n/a	if token == 0x00:
660	n/a	return None
661	n/a
662	n/a	elif token == 0x08:
663	n/a	return False
664	n/a
665	n/a	elif token == 0x09:
666	n/a	return True
667	n/a
668	n/a	# The referenced source code also mentions URL (0x0c, 0x0d) and
669	n/a	# UUID (0x0e), but neither can be generated using the Cocoa libraries.
670	n/a
671	n/a	elif token == 0x0f:
672	n/a	return b''
673	n/a
674	n/a	elif tokenH == 0x10: # int
675	n/a	return int.from_bytes(self._fp.read(1 << tokenL),
676	n/a	'big', signed=tokenL >= 3)
677	n/a
678	n/a	elif token == 0x22: # real
679	n/a	return struct.unpack('>f', self._fp.read(4))[0]
680	n/a
681	n/a	elif token == 0x23: # real
682	n/a	return struct.unpack('>d', self._fp.read(8))[0]
683	n/a
684	n/a	elif token == 0x33: # date
685	n/a	f = struct.unpack('>d', self._fp.read(8))[0]
686	n/a	# timestamp 0 of binary plists corresponds to 1/1/2001
687	n/a	# (year of Mac OS X 10.0), instead of 1/1/1970.
688	n/a	return datetime.datetime(2001, 1, 1) + datetime.timedelta(seconds=f)
689	n/a
690	n/a	elif tokenH == 0x40: # data
691	n/a	s = self._get_size(tokenL)
692	n/a	if self._use_builtin_types:
693	n/a	return self._fp.read(s)
694	n/a	else:
695	n/a	return Data(self._fp.read(s))
696	n/a
697	n/a	elif tokenH == 0x50: # ascii string
698	n/a	s = self._get_size(tokenL)
699	n/a	result = self._fp.read(s).decode('ascii')
700	n/a	return result
701	n/a
702	n/a	elif tokenH == 0x60: # unicode string
703	n/a	s = self._get_size(tokenL)
704	n/a	return self._fp.read(s * 2).decode('utf-16be')
705	n/a
706	n/a	# tokenH == 0x80 is documented as 'UID' and appears to be used for
707	n/a	# keyed-archiving, not in plists.
708	n/a
709	n/a	elif tokenH == 0xA0: # array
710	n/a	s = self._get_size(tokenL)
711	n/a	obj_refs = self._read_refs(s)
712	n/a	return [self._read_object(self._object_offsets[x])
713	n/a	for x in obj_refs]
714	n/a
715	n/a	# tokenH == 0xB0 is documented as 'ordset', but is not actually
716	n/a	# implemented in the Apple reference code.
717	n/a
718	n/a	# tokenH == 0xC0 is documented as 'set', but sets cannot be used in
719	n/a	# plists.
720	n/a
721	n/a	elif tokenH == 0xD0: # dict
722	n/a	s = self._get_size(tokenL)
723	n/a	key_refs = self._read_refs(s)
724	n/a	obj_refs = self._read_refs(s)
725	n/a	result = self._dict_type()
726	n/a	for k, o in zip(key_refs, obj_refs):
727	n/a	result[self._read_object(self._object_offsets[k])
728	n/a	] = self._read_object(self._object_offsets[o])
729	n/a	return result
730	n/a
731	n/a	raise InvalidFileException()
732	n/a
733	n/a	def _count_to_size(count):
734	n/a	if count < 1 << 8:
735	n/a	return 1
736	n/a
737	n/a	elif count < 1 << 16:
738	n/a	return 2
739	n/a
740	n/a	elif count << 1 << 32:
741	n/a	return 4
742	n/a
743	n/a	else:
744	n/a	return 8
745	n/a
746	n/a	class _BinaryPlistWriter (object):
747	n/a	def __init__(self, fp, sort_keys, skipkeys):
748	n/a	self._fp = fp
749	n/a	self._sort_keys = sort_keys
750	n/a	self._skipkeys = skipkeys
751	n/a
752	n/a	def write(self, value):
753	n/a
754	n/a	# Flattened object list:
755	n/a	self._objlist = []
756	n/a
757	n/a	# Mappings from object->objectid
758	n/a	# First dict has (type(object), object) as the key,
759	n/a	# second dict is used when object is not hashable and
760	n/a	# has id(object) as the key.
761	n/a	self._objtable = {}
762	n/a	self._objidtable = {}
763	n/a
764	n/a	# Create list of all objects in the plist
765	n/a	self._flatten(value)
766	n/a
767	n/a	# Size of object references in serialized containers
768	n/a	# depends on the number of objects in the plist.
769	n/a	num_objects = len(self._objlist)
770	n/a	self._object_offsets = [0]*num_objects
771	n/a	self._ref_size = _count_to_size(num_objects)
772	n/a
773	n/a	self._ref_format = _BINARY_FORMAT[self._ref_size]
774	n/a
775	n/a	# Write file header
776	n/a	self._fp.write(b'bplist00')
777	n/a
778	n/a	# Write object list
779	n/a	for obj in self._objlist:
780	n/a	self._write_object(obj)
781	n/a
782	n/a	# Write refnum->object offset table
783	n/a	top_object = self._getrefnum(value)
784	n/a	offset_table_offset = self._fp.tell()
785	n/a	offset_size = _count_to_size(offset_table_offset)
786	n/a	offset_format = '>' + _BINARY_FORMAT[offset_size] * num_objects
787	n/a	self._fp.write(struct.pack(offset_format, *self._object_offsets))
788	n/a
789	n/a	# Write trailer
790	n/a	sort_version = 0
791	n/a	trailer = (
792	n/a	sort_version, offset_size, self._ref_size, num_objects,
793	n/a	top_object, offset_table_offset
794	n/a	)
795	n/a	self._fp.write(struct.pack('>5xBBBQQQ', *trailer))
796	n/a
797	n/a	def _flatten(self, value):
798	n/a	# First check if the object is in the object table, not used for
799	n/a	# containers to ensure that two subcontainers with the same contents
800	n/a	# will be serialized as distinct values.
801	n/a	if isinstance(value, (
802	n/a	str, int, float, datetime.datetime, bytes, bytearray)):
803	n/a	if (type(value), value) in self._objtable:
804	n/a	return
805	n/a
806	n/a	elif isinstance(value, Data):
807	n/a	if (type(value.data), value.data) in self._objtable:
808	n/a	return
809	n/a
810	n/a	# Add to objectreference map
811	n/a	refnum = len(self._objlist)
812	n/a	self._objlist.append(value)
813	n/a	try:
814	n/a	if isinstance(value, Data):
815	n/a	self._objtable[(type(value.data), value.data)] = refnum
816	n/a	else:
817	n/a	self._objtable[(type(value), value)] = refnum
818	n/a	except TypeError:
819	n/a	self._objidtable[id(value)] = refnum
820	n/a
821	n/a	# And finally recurse into containers
822	n/a	if isinstance(value, dict):
823	n/a	keys = []
824	n/a	values = []
825	n/a	items = value.items()
826	n/a	if self._sort_keys:
827	n/a	items = sorted(items)
828	n/a
829	n/a	for k, v in items:
830	n/a	if not isinstance(k, str):
831	n/a	if self._skipkeys:
832	n/a	continue
833	n/a	raise TypeError("keys must be strings")
834	n/a	keys.append(k)
835	n/a	values.append(v)
836	n/a
837	n/a	for o in itertools.chain(keys, values):
838	n/a	self._flatten(o)
839	n/a
840	n/a	elif isinstance(value, (list, tuple)):
841	n/a	for o in value:
842	n/a	self._flatten(o)
843	n/a
844	n/a	def _getrefnum(self, value):
845	n/a	try:
846	n/a	if isinstance(value, Data):
847	n/a	return self._objtable[(type(value.data), value.data)]
848	n/a	else:
849	n/a	return self._objtable[(type(value), value)]
850	n/a	except TypeError:
851	n/a	return self._objidtable[id(value)]
852	n/a
853	n/a	def _write_size(self, token, size):
854	n/a	if size < 15:
855	n/a	self._fp.write(struct.pack('>B', token \| size))
856	n/a
857	n/a	elif size < 1 << 8:
858	n/a	self._fp.write(struct.pack('>BBB', token \| 0xF, 0x10, size))
859	n/a
860	n/a	elif size < 1 << 16:
861	n/a	self._fp.write(struct.pack('>BBH', token \| 0xF, 0x11, size))
862	n/a
863	n/a	elif size < 1 << 32:
864	n/a	self._fp.write(struct.pack('>BBL', token \| 0xF, 0x12, size))
865	n/a
866	n/a	else:
867	n/a	self._fp.write(struct.pack('>BBQ', token \| 0xF, 0x13, size))
868	n/a
869	n/a	def _write_object(self, value):
870	n/a	ref = self._getrefnum(value)
871	n/a	self._object_offsets[ref] = self._fp.tell()
872	n/a	if value is None:
873	n/a	self._fp.write(b'\x00')
874	n/a
875	n/a	elif value is False:
876	n/a	self._fp.write(b'\x08')
877	n/a
878	n/a	elif value is True:
879	n/a	self._fp.write(b'\x09')
880	n/a
881	n/a	elif isinstance(value, int):
882	n/a	if value < 0:
883	n/a	try:
884	n/a	self._fp.write(struct.pack('>Bq', 0x13, value))
885	n/a	except struct.error:
886	n/a	raise OverflowError(value) from None
887	n/a	elif value < 1 << 8:
888	n/a	self._fp.write(struct.pack('>BB', 0x10, value))
889	n/a	elif value < 1 << 16:
890	n/a	self._fp.write(struct.pack('>BH', 0x11, value))
891	n/a	elif value < 1 << 32:
892	n/a	self._fp.write(struct.pack('>BL', 0x12, value))
893	n/a	elif value < 1 << 63:
894	n/a	self._fp.write(struct.pack('>BQ', 0x13, value))
895	n/a	elif value < 1 << 64:
896	n/a	self._fp.write(b'\x14' + value.to_bytes(16, 'big', signed=True))
897	n/a	else:
898	n/a	raise OverflowError(value)
899	n/a
900	n/a	elif isinstance(value, float):
901	n/a	self._fp.write(struct.pack('>Bd', 0x23, value))
902	n/a
903	n/a	elif isinstance(value, datetime.datetime):
904	n/a	f = (value - datetime.datetime(2001, 1, 1)).total_seconds()
905	n/a	self._fp.write(struct.pack('>Bd', 0x33, f))
906	n/a
907	n/a	elif isinstance(value, Data):
908	n/a	self._write_size(0x40, len(value.data))
909	n/a	self._fp.write(value.data)
910	n/a
911	n/a	elif isinstance(value, (bytes, bytearray)):
912	n/a	self._write_size(0x40, len(value))
913	n/a	self._fp.write(value)
914	n/a
915	n/a	elif isinstance(value, str):
916	n/a	try:
917	n/a	t = value.encode('ascii')
918	n/a	self._write_size(0x50, len(value))
919	n/a	except UnicodeEncodeError:
920	n/a	t = value.encode('utf-16be')
921	n/a	self._write_size(0x60, len(t) // 2)
922	n/a
923	n/a	self._fp.write(t)
924	n/a
925	n/a	elif isinstance(value, (list, tuple)):
926	n/a	refs = [self._getrefnum(o) for o in value]
927	n/a	s = len(refs)
928	n/a	self._write_size(0xA0, s)
929	n/a	self._fp.write(struct.pack('>' + self._ref_format * s, *refs))
930	n/a
931	n/a	elif isinstance(value, dict):
932	n/a	keyRefs, valRefs = [], []
933	n/a
934	n/a	if self._sort_keys:
935	n/a	rootItems = sorted(value.items())
936	n/a	else:
937	n/a	rootItems = value.items()
938	n/a
939	n/a	for k, v in rootItems:
940	n/a	if not isinstance(k, str):
941	n/a	if self._skipkeys:
942	n/a	continue
943	n/a	raise TypeError("keys must be strings")
944	n/a	keyRefs.append(self._getrefnum(k))
945	n/a	valRefs.append(self._getrefnum(v))
946	n/a
947	n/a	s = len(keyRefs)
948	n/a	self._write_size(0xD0, s)
949	n/a	self._fp.write(struct.pack('>' + self._ref_format * s, *keyRefs))
950	n/a	self._fp.write(struct.pack('>' + self._ref_format * s, *valRefs))
951	n/a
952	n/a	else:
953	n/a	raise TypeError(value)
954	n/a
955	n/a
956	n/a	def _is_fmt_binary(header):
957	n/a	return header[:8] == b'bplist00'
958	n/a
959	n/a
960	n/a	#
961	n/a	# Generic bits
962	n/a	#
963	n/a
964	n/a	_FORMATS={
965	n/a	FMT_XML: dict(
966	n/a	detect=_is_fmt_xml,
967	n/a	parser=_PlistParser,
968	n/a	writer=_PlistWriter,
969	n/a	),
970	n/a	FMT_BINARY: dict(
971	n/a	detect=_is_fmt_binary,
972	n/a	parser=_BinaryPlistParser,
973	n/a	writer=_BinaryPlistWriter,
974	n/a	)
975	n/a	}
976	n/a
977	n/a
978	n/a	def load(fp, *, fmt=None, use_builtin_types=True, dict_type=dict):
979	n/a	"""Read a .plist file. 'fp' should be (readable) file object.
980	n/a	Return the unpacked root object (which usually is a dictionary).
981	n/a	"""
982	n/a	if fmt is None:
983	n/a	header = fp.read(32)
984	n/a	fp.seek(0)
985	n/a	for info in _FORMATS.values():
986	n/a	if info['detect'](header):
987	n/a	P = info['parser']
988	n/a	break
989	n/a
990	n/a	else:
991	n/a	raise InvalidFileException()
992	n/a
993	n/a	else:
994	n/a	P = _FORMATS[fmt]['parser']
995	n/a
996	n/a	p = P(use_builtin_types=use_builtin_types, dict_type=dict_type)
997	n/a	return p.parse(fp)
998	n/a
999	n/a
1000	n/a	def loads(value, *, fmt=None, use_builtin_types=True, dict_type=dict):
1001	n/a	"""Read a .plist file from a bytes object.
1002	n/a	Return the unpacked root object (which usually is a dictionary).
1003	n/a	"""
1004	n/a	fp = BytesIO(value)
1005	n/a	return load(
1006	n/a	fp, fmt=fmt, use_builtin_types=use_builtin_types, dict_type=dict_type)
1007	n/a
1008	n/a
1009	n/a	def dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False):
1010	n/a	"""Write 'value' to a .plist file. 'fp' should be a (writable)
1011	n/a	file object.
1012	n/a	"""
1013	n/a	if fmt not in _FORMATS:
1014	n/a	raise ValueError("Unsupported format: %r"%(fmt,))
1015	n/a
1016	n/a	writer = _FORMATS[fmt]["writer"](fp, sort_keys=sort_keys, skipkeys=skipkeys)
1017	n/a	writer.write(value)
1018	n/a
1019	n/a
1020	n/a	def dumps(value, *, fmt=FMT_XML, skipkeys=False, sort_keys=True):
1021	n/a	"""Return a bytes object with the contents for a .plist file.
1022	n/a	"""
1023	n/a	fp = BytesIO()
1024	n/a	dump(value, fp, fmt=fmt, skipkeys=skipkeys, sort_keys=sort_keys)
1025	n/a	return fp.getvalue()