1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
|
<span id="plistlib-generate-and-parse-apple-plist-files"></span><h1>plistlib — Generate and parse Apple .plist files</h1> <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/plistlib.py">Lib/plistlib.py</a></p> <p>This module provides an interface for reading and writing the “property list” files used by Apple, primarily on macOS and iOS. This module supports both binary and XML plist files.</p> <p>The property list (<code>.plist</code>) file format is a simple serialization supporting basic object types, like dictionaries, lists, numbers and strings. Usually the top level object is a dictionary.</p> <p>To write out and to parse a plist file, use the <a class="reference internal" href="#plistlib.dump" title="plistlib.dump"><code>dump()</code></a> and <a class="reference internal" href="#plistlib.load" title="plistlib.load"><code>load()</code></a> functions.</p> <p>To work with plist data in bytes objects, use <a class="reference internal" href="#plistlib.dumps" title="plistlib.dumps"><code>dumps()</code></a> and <a class="reference internal" href="#plistlib.loads" title="plistlib.loads"><code>loads()</code></a>.</p> <p>Values can be strings, integers, floats, booleans, tuples, lists, dictionaries (but only with string keys), <a class="reference internal" href="stdtypes#bytes" title="bytes"><code>bytes</code></a>, <a class="reference internal" href="stdtypes#bytearray" title="bytearray"><code>bytearray</code></a> or <a class="reference internal" href="datetime#datetime.datetime" title="datetime.datetime"><code>datetime.datetime</code></a> objects.</p> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.4: </span>New API, old API deprecated. Support for binary format plists added.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.8: </span>Support added for reading and writing <a class="reference internal" href="#plistlib.UID" title="plistlib.UID"><code>UID</code></a> tokens in binary plists as used by NSKeyedArchiver and NSKeyedUnarchiver.</p> </div> <div class="versionchanged"> <p><span class="versionmodified changed">Changed in version 3.9: </span>Old API removed.</p> </div> <div class="admonition seealso"> <p class="admonition-title">See also</p> <dl class="simple"> <dt><a class="reference external" href="https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/">PList manual page</a></dt>
<dd>
<p>Apple’s documentation of the file format.</p> </dd> </dl> </div> <p>This module defines the following functions:</p> <dl class="py function"> <dt class="sig sig-object py" id="plistlib.load">
<code>plistlib.load(fp, *, fmt=None, dict_type=dict)</code> </dt> <dd>
<p>Read a plist file. <em>fp</em> should be a readable and binary file object. Return the unpacked root object (which usually is a dictionary).</p> <p>The <em>fmt</em> is the format of the file and the following values are valid:</p> <ul class="simple"> <li>
<a class="reference internal" href="constants#None" title="None"><code>None</code></a>: Autodetect the file format</li> <li>
<a class="reference internal" href="#plistlib.FMT_XML" title="plistlib.FMT_XML"><code>FMT_XML</code></a>: XML file format</li> <li>
<a class="reference internal" href="#plistlib.FMT_BINARY" title="plistlib.FMT_BINARY"><code>FMT_BINARY</code></a>: Binary plist format</li> </ul> <p>The <em>dict_type</em> is the type used for dictionaries that are read from the plist file.</p> <p>XML data for the <a class="reference internal" href="#plistlib.FMT_XML" title="plistlib.FMT_XML"><code>FMT_XML</code></a> format is parsed using the Expat parser from <a class="reference internal" href="pyexpat#module-xml.parsers.expat" title="xml.parsers.expat: An interface to the Expat non-validating XML parser."><code>xml.parsers.expat</code></a> – see its documentation for possible exceptions on ill-formed XML. Unknown elements will simply be ignored by the plist parser.</p> <p>The parser for the binary format raises <code>InvalidFileException</code> when the file cannot be parsed.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="plistlib.loads">
<code>plistlib.loads(data, *, fmt=None, dict_type=dict)</code> </dt> <dd>
<p>Load a plist from a bytes object. See <a class="reference internal" href="#plistlib.load" title="plistlib.load"><code>load()</code></a> for an explanation of the keyword arguments.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="plistlib.dump">
<code>plistlib.dump(value, fp, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)</code> </dt> <dd>
<p>Write <em>value</em> to a plist file. <em>Fp</em> should be a writable, binary file object.</p> <p>The <em>fmt</em> argument specifies the format of the plist file and can be one of the following values:</p> <ul class="simple"> <li>
<a class="reference internal" href="#plistlib.FMT_XML" title="plistlib.FMT_XML"><code>FMT_XML</code></a>: XML formatted plist file</li> <li>
<a class="reference internal" href="#plistlib.FMT_BINARY" title="plistlib.FMT_BINARY"><code>FMT_BINARY</code></a>: Binary formatted plist file</li> </ul> <p>When <em>sort_keys</em> is true (the default) the keys for dictionaries will be written to the plist in sorted order, otherwise they will be written in the iteration order of the dictionary.</p> <p>When <em>skipkeys</em> is false (the default) the function raises <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> when a key of a dictionary is not a string, otherwise such keys are skipped.</p> <p>A <a class="reference internal" href="exceptions#TypeError" title="TypeError"><code>TypeError</code></a> will be raised if the object is of an unsupported type or a container that contains objects of unsupported types.</p> <p>An <a class="reference internal" href="exceptions#OverflowError" title="OverflowError"><code>OverflowError</code></a> will be raised for integer values that cannot be represented in (binary) plist files.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="py function"> <dt class="sig sig-object py" id="plistlib.dumps">
<code>plistlib.dumps(value, *, fmt=FMT_XML, sort_keys=True, skipkeys=False)</code> </dt> <dd>
<p>Return <em>value</em> as a plist-formatted bytes object. See the documentation for <a class="reference internal" href="#plistlib.dump" title="plistlib.dump"><code>dump()</code></a> for an explanation of the keyword arguments of this function.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <p>The following classes are available:</p> <dl class="py class"> <dt class="sig sig-object py" id="plistlib.UID">
<code>class plistlib.UID(data)</code> </dt> <dd>
<p>Wraps an <a class="reference internal" href="functions#int" title="int"><code>int</code></a>. This is used when reading or writing NSKeyedArchiver encoded data, which contains UID (see PList manual).</p> <p>It has one attribute, <code>data</code>, which can be used to retrieve the int value of the UID. <code>data</code> must be in the range <code>0 <= data < 2**64</code>.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.8.</span></p> </div> </dd>
</dl> <p>The following constants are available:</p> <dl class="py data"> <dt class="sig sig-object py" id="plistlib.FMT_XML">
<code>plistlib.FMT_XML</code> </dt> <dd>
<p>The XML format for plist files.</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <dl class="py data"> <dt class="sig sig-object py" id="plistlib.FMT_BINARY">
<code>plistlib.FMT_BINARY</code> </dt> <dd>
<p>The binary format for plist files</p> <div class="versionadded"> <p><span class="versionmodified added">New in version 3.4.</span></p> </div> </dd>
</dl> <section id="examples"> <h2>Examples</h2> <p>Generating a plist:</p> <pre data-language="python">import datetime
import plistlib
pl = dict(
aString = "Doodah",
aList = ["A", "B", 12, 32.1, [1, 2, 3]],
aFloat = 0.1,
anInt = 728,
aDict = dict(
anotherString = "<hello & hi there!>",
aThirdString = "M\xe4ssig, Ma\xdf",
aTrueValue = True,
aFalseValue = False,
),
someData = b"<binary gunk>",
someMoreData = b"<lots of binary gunk>" * 10,
aDate = datetime.datetime.now()
)
print(plistlib.dumps(pl).decode())
</pre> <p>Parsing a plist:</p> <pre data-language="python">import plistlib
plist = b"""<plist version="1.0">
<dict>
<key>foo</key>
<string>bar</string>
</dict>
</plist>"""
pl = plistlib.loads(plist)
print(pl["foo"])
</pre> </section> <div class="_attribution">
<p class="_attribution-p">
© 2001–2023 Python Software Foundation<br>Licensed under the PSF License.<br>
<a href="https://docs.python.org/3.12/library/plistlib.html" class="_attribution-link">https://docs.python.org/3.12/library/plistlib.html</a>
</p>
</div>
|
