<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>plistlib – Manipulate OS X property list files — Python Module of the Week</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.132',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="top" title="Python Module of the Week" href="../index.html" />
<link rel="up" title="Miscelaneous" href="../miscelaneous.html" />
<link rel="next" title="History" href="../history.html" />
<link rel="prev" title="EasyDialogs – Carbon dialogs for Mac OS X" href="../EasyDialogs/index.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../history.html" title="History"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="../EasyDialogs/index.html" title="EasyDialogs – Carbon dialogs for Mac OS X"
accesskey="P">previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../miscelaneous.html" accesskey="U">Miscelaneous</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">plistlib – Manipulate OS X property list files</a><ul>
<li><a class="reference internal" href="#reading-plist-files">Reading plist Files</a></li>
<li><a class="reference internal" href="#writing-plist-files">Writing plist Files</a></li>
<li><a class="reference internal" href="#binary-property-data">Binary Property Data</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../EasyDialogs/index.html"
title="previous chapter">EasyDialogs – Carbon dialogs for Mac OS X</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="../history.html"
title="next chapter">History</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/plistlib/index.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-plistlib">
<span id="plistlib-manipulate-os-x-property-list-files"></span><h1>plistlib – Manipulate OS X property list files<a class="headerlink" href="#module-plistlib" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Purpose:</th><td class="field-body">Read and write OS X property list files</td>
</tr>
<tr class="field"><th class="field-name">Python Version:</th><td class="field-body">2.6</td>
</tr>
</tbody>
</table>
<p><a class="reference internal" href="#module-plistlib" title="plistlib: Manipulate OS X property list files"><tt class="xref py py-mod docutils literal"><span class="pre">plistlib</span></tt></a> provides an interface for working with property list
files used under OS X. plist files are typically XML, sometimes
compressed. They are used by the operating system and applications to
store preferences or other configuration settings. The contents are
usually structured as a dictionary containing key value pairs of basic
built-in types (unicode strings, integers, dates, etc.). Values can
also be nested data structures such as other dictionaries or lists.
Binary data, or strings with control characters, can be encoded using
the <tt class="docutils literal"><span class="pre">data</span></tt> type.</p>
<div class="section" id="reading-plist-files">
<h2>Reading plist Files<a class="headerlink" href="#reading-plist-files" title="Permalink to this headline">¶</a></h2>
<p>OS X applications such as iCal use plist files to store meta-data
about objects they manage. For example, iCal stores the definitions
of all of your calendars as a series of plist files in the Library
directory.</p>
<div class="highlight-xml"><div class="highlight"><pre><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span>
<span class="cp"><!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"></span>
<span class="nt"><plist</span> <span class="na">version=</span><span class="s">"1.0"</span><span class="nt">></span>
<span class="nt"><dict></span>
<span class="nt"><key></span>AlarmFilter<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>AlarmsDisabled<span class="nt"></key></span>
<span class="nt"><false/></span>
<span class="nt"><key></span>AttachmentFilter<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>AutoRefresh<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>Checked<span class="nt"></key></span>
<span class="nt"><integer></span>1<span class="nt"></integer></span>
<span class="nt"><key></span>Color<span class="nt"></key></span>
<span class="nt"><string></span>#808000FF<span class="nt"></string></span>
<span class="nt"><key></span>Enabled<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>Key<span class="nt"></key></span>
<span class="nt"><string></span>4221BCE5-1017-4EE4-B7FF-311A846C600D<span class="nt"></string></span>
<span class="nt"><key></span>NeedsForcedUpdate<span class="nt"></key></span>
<span class="nt"><false/></span>
<span class="nt"><key></span>NeedsRefresh<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>Order<span class="nt"></key></span>
<span class="nt"><integer></span>25<span class="nt"></integer></span>
<span class="nt"><key></span>RefreshDate<span class="nt"></key></span>
<span class="nt"><date></span>2009-11-29T16:31:53Z<span class="nt"></date></span>
<span class="nt"><key></span>RefreshInterval<span class="nt"></key></span>
<span class="nt"><integer></span>3600<span class="nt"></integer></span>
<span class="nt"><key></span>SubscriptionTitle<span class="nt"></key></span>
<span class="nt"><string></span>Athens, GA Weather - By Weather Underground<span class="nt"></string></span>
<span class="nt"><key></span>SubscriptionURL<span class="nt"></key></span>
<span class="nt"><string></span>http://ical.wunderground.com/auto/ical/GA/Athens.ics?units=both<span class="nt"></string></span>
<span class="nt"><key></span>TaskFilter<span class="nt"></key></span>
<span class="nt"><true/></span>
<span class="nt"><key></span>Title<span class="nt"></key></span>
<span class="nt"><string></span>Athens, GA Weather - By Weather Underground<span class="nt"></string></span>
<span class="nt"><key></span>Type<span class="nt"></key></span>
<span class="nt"><string></span>Subscription<span class="nt"></string></span>
<span class="nt"></dict></span>
<span class="nt"></plist></span>
</pre></div>
</div>
<p>This sample script finds the calendar defintions, reads
them, and prints the titles of any calendars being displayed by iCal
(having the property <tt class="docutils literal"><span class="pre">Checked</span></tt> set to a true value).</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">plistlib</span>
<span class="kn">import</span> <span class="nn">os</span>
<span class="kn">import</span> <span class="nn">glob</span>
<span class="n">calendar_root</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s">'~/Library/Calendars'</span><span class="p">)</span>
<span class="n">calendar_directories</span> <span class="o">=</span> <span class="p">(</span>
<span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">calendar_root</span><span class="p">,</span> <span class="s">'*.caldav'</span><span class="p">,</span> <span class="s">'*.calendar'</span><span class="p">))</span> <span class="o">+</span>
<span class="n">glob</span><span class="o">.</span><span class="n">glob</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">calendar_root</span><span class="p">,</span> <span class="s">'*.calendar'</span><span class="p">))</span>
<span class="p">)</span>
<span class="k">for</span> <span class="n">dirname</span> <span class="ow">in</span> <span class="n">calendar_directories</span><span class="p">:</span>
<span class="n">info_filename</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dirname</span><span class="p">,</span> <span class="s">'Info.plist'</span><span class="p">)</span>
<span class="k">if</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isfile</span><span class="p">(</span><span class="n">info_filename</span><span class="p">):</span>
<span class="n">info</span> <span class="o">=</span> <span class="n">plistlib</span><span class="o">.</span><span class="n">readPlist</span><span class="p">(</span><span class="n">info_filename</span><span class="p">)</span>
<span class="k">if</span> <span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">'Checked'</span><span class="p">):</span>
<span class="k">print</span> <span class="n">info</span><span class="p">[</span><span class="s">'Title'</span><span class="p">]</span>
</pre></div>
</div>
<p>The type of the <tt class="docutils literal"><span class="pre">Checked</span></tt> property is defined by the plist file, so
our script does not need to convert the string to an integer.</p>
<div class="highlight-python"><pre>$ python plistlib_checked_calendars.py
Doug Hellmann
Tasks
Vacation Schedule
EarthSeasons
US Holidays
Athens, GA Weather - By Weather Underground
Birthdays
Georgia Bulldogs Calendar (NCAA Football)
Home
Meetup: Django
Meetup: Python</pre>
</div>
</div>
<div class="section" id="writing-plist-files">
<h2>Writing plist Files<a class="headerlink" href="#writing-plist-files" title="Permalink to this headline">¶</a></h2>
<p>If you want to use plist files to save your own settings, use
<tt class="docutils literal"><span class="pre">writePlist()</span></tt> to serialize the data and write it to the filesystem.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">plistlib</span>
<span class="kn">import</span> <span class="nn">datetime</span>
<span class="kn">import</span> <span class="nn">tempfile</span>
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'an_int'</span><span class="p">:</span><span class="mi">2</span><span class="p">,</span>
<span class="s">'a_bool'</span><span class="p">:</span><span class="bp">False</span><span class="p">,</span>
<span class="s">'the_float'</span><span class="p">:</span><span class="mf">5.9</span><span class="p">,</span>
<span class="s">'simple_string'</span><span class="p">:</span><span class="s">'This string has no special characters.'</span><span class="p">,</span>
<span class="s">'xml_string'</span><span class="p">:</span><span class="s">'<element attr="value">This string includes XML markup &nbsp;</element>'</span><span class="p">,</span>
<span class="s">'nested_list'</span><span class="p">:[</span><span class="s">'a'</span><span class="p">,</span> <span class="s">'b'</span><span class="p">,</span> <span class="s">'c'</span><span class="p">],</span>
<span class="s">'nested_dict'</span><span class="p">:{</span> <span class="s">'key'</span><span class="p">:</span><span class="s">'value'</span> <span class="p">},</span>
<span class="s">'timestamp'</span><span class="p">:</span><span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">(),</span>
<span class="p">}</span>
<span class="n">output_file</span> <span class="o">=</span> <span class="n">tempfile</span><span class="o">.</span><span class="n">NamedTemporaryFile</span><span class="p">()</span>
<span class="k">try</span><span class="p">:</span>
<span class="n">plistlib</span><span class="o">.</span><span class="n">writePlist</span><span class="p">(</span><span class="n">d</span><span class="p">,</span> <span class="n">output_file</span><span class="p">)</span>
<span class="n">output_file</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="k">print</span> <span class="n">output_file</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
<span class="k">finally</span><span class="p">:</span>
<span class="n">output_file</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The first argument is the data structure to write out, and the second
is an open file handle or the name of a file.</p>
<div class="highlight-python"><pre>$ python plistlib_write_plist.py
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>a_bool</key>
<false/>
<key>an_int</key>
<integer>2</integer>
<key>nested_dict</key>
<dict>
<key>key</key>
<string>value</string>
</dict>
<key>nested_list</key>
<array>
<string>a</string>
<string>b</string>
<string>c</string>
</array>
<key>simple_string</key>
<string>This string has no special characters.</string>
<key>the_float</key>
<real>5.9</real>
<key>timestamp</key>
<date>2010-10-24T08:54:22Z</date>
<key>xml_string</key>
<string>&lt;element attr="value"&gt;This string includes XML markup &amp;nbsp;&lt;/element&gt;</string>
</dict>
</plist></pre>
</div>
</div>
<div class="section" id="binary-property-data">
<h2>Binary Property Data<a class="headerlink" href="#binary-property-data" title="Permalink to this headline">¶</a></h2>
<p>Serializing binary data or strings that may include control characters
using a plist is not immune to the typical challenges for an XML
format. To work around the issues, plist files can store binary data
in <a class="reference internal" href="../base64/index.html#module-base64" title="base64: Encode binary data into ASCII characters."><tt class="xref py py-mod docutils literal"><span class="pre">base64</span></tt></a> format if the object is wrapped with a <tt class="docutils literal"><span class="pre">Data</span></tt>
instance.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">plistlib</span>
<span class="n">d</span> <span class="o">=</span> <span class="p">{</span> <span class="s">'binary_data'</span><span class="p">:</span><span class="n">plistlib</span><span class="o">.</span><span class="n">Data</span><span class="p">(</span><span class="s">'This data has an embedded null. </span><span class="se">\0</span><span class="s">'</span><span class="p">),</span>
<span class="p">}</span>
<span class="k">print</span> <span class="n">plistlib</span><span class="o">.</span><span class="n">writePlistToString</span><span class="p">(</span><span class="n">d</span><span class="p">)</span>
</pre></div>
</div>
<p>This example uses the <tt class="docutils literal"><span class="pre">writePlistToString()</span></tt> to create an in-memory
string, instead of writing to a file.</p>
<div class="highlight-python"><pre>$ python plistlib_binary_write.py
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>binary_data</key>
<data>
VGhpcyBkYXRhIGhhcyBhbiBlbWJlZGRlZCBudWxsLiAA
</data>
</dict>
</plist></pre>
</div>
<p>Binary data is automatically converted to a <tt class="docutils literal"><span class="pre">Data</span></tt> instance when
read.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">plistlib</span>
<span class="kn">import</span> <span class="nn">pprint</span>
<span class="n">DATA</span> <span class="o">=</span> <span class="s">"""<?xml version="1.0" encoding="UTF-8"?></span>
<span class="s"><!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"></span>
<span class="s"><plist version="1.0"></span>
<span class="s"><dict></span>
<span class="s"> <key>binary_data</key></span>
<span class="s"> <data></span>
<span class="s"> VGhpcyBkYXRhIGhhcyBhbiBlbWJlZGRlZCBudWxsLiAA</span>
<span class="s"> </data></span>
<span class="s"></dict></span>
<span class="s"></plist></span>
<span class="s">"""</span>
<span class="n">d</span> <span class="o">=</span> <span class="n">plistlib</span><span class="o">.</span><span class="n">readPlistFromString</span><span class="p">(</span><span class="n">DATA</span><span class="p">)</span>
<span class="k">print</span> <span class="nb">repr</span><span class="p">(</span><span class="n">d</span><span class="p">[</span><span class="s">'binary_data'</span><span class="p">]</span><span class="o">.</span><span class="n">data</span><span class="p">)</span>
</pre></div>
</div>
<p>The <tt class="docutils literal"><span class="pre">data</span></tt> attribute of the object contains the decoded data.</p>
<div class="highlight-python"><pre>$ python plistlib_binary_read.py
'This data has an embedded null. \x00'</pre>
</div>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<dl class="last docutils">
<dt><a class="reference external" href="http://docs.python.org/library/plistlib.html">plistlib</a></dt>
<dd>The standard library documentation for this module.</dd>
<dt><a class="reference external" href="http://developer.apple.com/documentation/Darwin/Reference/ManPages/man5/plist.5.html">plist manual page</a></dt>
<dd>Documentation of the plist file format.</dd>
<dt><a class="reference external" href="http://www.wunderground.com/">Weather Underground</a></dt>
<dd>Free weather information, including ICS and RSS feeds.</dd>
<dt><a class="reference external" href="http://www.macosxhints.com/article.php?story=20050430105126392">Convert plist between XML and Binary formats</a></dt>
<dd>Some plist files are stored in a binary format instead of XML
because the binary format is faster to parse using Apple’s
libraries. Python’s plistlib module does not handle the
binary format, so you may need to convert binary files to XML
using <tt class="docutils literal"><span class="pre">plutil</span></tt> before reading them.</dd>
<dt><a class="reference external" href="http://docs.google.com/present/view?id=0AW0cyKASCypUZGczODJ6YjdfMjRobW16dG5mNQ&hl=en">Using Python for System Administration</a></dt>
<dd>Presentation from Nigel Kersten and Chris Adams, including
details of using PyObjC to load plists using the native Cocoa
API, which transparently handles both the XML and binary
formats. See slice 27, especially.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="../history.html" title="History"
>next</a> |</li>
<li class="right" >
<a href="../EasyDialogs/index.html" title="EasyDialogs – Carbon dialogs for Mac OS X"
>previous</a> |</li>
<li><a href="../contents.html">PyMOTW</a> »</li>
<li><a href="../miscelaneous.html" >Miscelaneous</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright Doug Hellmann.
Last updated on Oct 24, 2010.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br/><a href="http://creativecommons.org/licenses/by-nc-sa/3.0/us/" rel="license"><img alt="Creative Commons License" style="border-width:0" src="http://i.creativecommons.org/l/by-nc-sa/3.0/us/88x31.png"/></a>
</div>
</body>
</html>