summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorfuzzyman <devnull@localhost>2010-01-09 20:35:14 +0000
committerfuzzyman <devnull@localhost>2010-01-09 20:35:14 +0000
commitbe6d95eebe622b5dd5fd1b8025d4b013e3175928 (patch)
tree7fab57824e47cdc656bc2e45b42d76ded2b261a5 /docs
parent52e42f1993ba545e62f1604932d7ec5bbeb8b654 (diff)
downloadconfigobj-git-be6d95eebe622b5dd5fd1b8025d4b013e3175928.tar.gz
Adding more files for building docs.
Diffstat (limited to 'docs')
-rw-r--r--docs/configobj.html2614
-rw-r--r--docs/configobj.txt11
-rw-r--r--docs/default.css293
-rw-r--r--docs/docutils.conf3
-rw-r--r--docs/template.tmp8
-rw-r--r--docs/validate.html639
-rw-r--r--docs/voidspace_docutils.css141
7 files changed, 3700 insertions, 9 deletions
diff --git a/docs/configobj.html b/docs/configobj.html
new file mode 100644
index 0000000..efafd0f
--- /dev/null
+++ b/docs/configobj.html
@@ -0,0 +1,2614 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!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" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
+<title>Reading and Writing Config Files</title>
+<meta name="authors" content="Michael Foord Nicola Larosa" />
+<meta name="date" content="2010/01/09" />
+<meta content="ConfigObj - a Python module for easy reading and writing of config files." name="description" />
+<meta content="python, script, module, config, configuration, data, persistence, developer, configparser" name="keywords" />
+<link rel="stylesheet" href="voidspace_docutils.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="reading-and-writing-config-files">
+<h1 class="title">Reading and Writing Config Files</h1>
+<h2 class="subtitle" id="configobj-4-introduction-and-reference">ConfigObj 4 Introduction and Reference</h2>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Authors:</th>
+<td>Michael Foord
+<br />Nicola Larosa</td></tr>
+<tr><th class="docinfo-name">Version:</th>
+<td>ConfigObj 4.7.0</td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>2010/01/09</td></tr>
+<tr class="field"><th class="docinfo-name">Homepage:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj Homepage</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">PyPI Entry:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/configobj/">ConfigObj on PyPI</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Development:</th><td class="field-body"><a class="reference external" href="http://code.google.com/p/configobj/">Google Code Homepage</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Support:</th><td class="field-body"><a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a></td>
+</tr>
+</tbody>
+</table>
+<div class="contents topic" id="configobj-manual">
+<p class="topic-title first">ConfigObj Manual</p>
+<ul class="auto-toc simple">
+<li><a class="reference internal" href="#introduction" id="id27">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
+<li><a class="reference internal" href="#downloading" id="id28">2&nbsp;&nbsp;&nbsp;Downloading</a><ul class="auto-toc">
+<li><a class="reference internal" href="#installing" id="id29">2.1&nbsp;&nbsp;&nbsp;Installing</a></li>
+<li><a class="reference internal" href="#documentation" id="id30">2.2&nbsp;&nbsp;&nbsp;Documentation</a></li>
+<li><a class="reference internal" href="#development-version" id="id31">2.3&nbsp;&nbsp;&nbsp;Development Version</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#configobj-in-the-real-world" id="id32">3&nbsp;&nbsp;&nbsp;ConfigObj in the Real World</a></li>
+<li><a class="reference internal" href="#getting-started" id="id33">4&nbsp;&nbsp;&nbsp;Getting Started</a><ul class="auto-toc">
+<li><a class="reference internal" href="#reading-a-config-file" id="id34">4.1&nbsp;&nbsp;&nbsp;Reading a Config File</a></li>
+<li><a class="reference internal" href="#writing-a-config-file" id="id35">4.2&nbsp;&nbsp;&nbsp;Writing a Config File</a></li>
+<li><a class="reference internal" href="#config-files" id="id36">4.3&nbsp;&nbsp;&nbsp;Config Files</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#configobj-specifications" id="id37">5&nbsp;&nbsp;&nbsp;ConfigObj specifications</a><ul class="auto-toc">
+<li><a class="reference internal" href="#methods" id="id38">5.1&nbsp;&nbsp;&nbsp;Methods</a><ul class="auto-toc">
+<li><a class="reference internal" href="#write" id="id39">5.1.1&nbsp;&nbsp;&nbsp;write</a></li>
+<li><a class="reference internal" href="#validate" id="id40">5.1.2&nbsp;&nbsp;&nbsp;validate</a><ul class="auto-toc">
+<li><a class="reference internal" href="#return-value" id="id41">5.1.2.1&nbsp;&nbsp;&nbsp;Return Value</a></li>
+<li><a class="reference internal" href="#mentioning-default-values" id="id42">5.1.2.2&nbsp;&nbsp;&nbsp;Mentioning Default Values</a></li>
+<li><a class="reference internal" href="#mentioning-repeated-sections-and-values" id="id43">5.1.2.3&nbsp;&nbsp;&nbsp;Mentioning Repeated Sections and Values</a></li>
+<li><a class="reference internal" href="#mentioning-simpleval" id="id44">5.1.2.4&nbsp;&nbsp;&nbsp;Mentioning SimpleVal</a></li>
+<li><a class="reference internal" href="#mentioning-copy-mode" id="id45">5.1.2.5&nbsp;&nbsp;&nbsp;Mentioning copy Mode</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#reload" id="id46">5.1.3&nbsp;&nbsp;&nbsp;reload</a></li>
+<li><a class="reference internal" href="#reset" id="id47">5.1.4&nbsp;&nbsp;&nbsp;reset</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#attributes" id="id48">5.2&nbsp;&nbsp;&nbsp;Attributes</a><ul class="auto-toc">
+<li><a class="reference internal" href="#interpolation" id="id49">5.2.1&nbsp;&nbsp;&nbsp;interpolation</a></li>
+<li><a class="reference internal" href="#stringify" id="id50">5.2.2&nbsp;&nbsp;&nbsp;stringify</a></li>
+<li><a class="reference internal" href="#bom" id="id51">5.2.3&nbsp;&nbsp;&nbsp;BOM</a></li>
+<li><a class="reference internal" href="#initial-comment" id="id52">5.2.4&nbsp;&nbsp;&nbsp;initial_comment</a></li>
+<li><a class="reference internal" href="#final-comment" id="id53">5.2.5&nbsp;&nbsp;&nbsp;final_comment</a></li>
+<li><a class="reference internal" href="#list-values" id="id54">5.2.6&nbsp;&nbsp;&nbsp;list_values</a></li>
+<li><a class="reference internal" href="#encoding" id="id55">5.2.7&nbsp;&nbsp;&nbsp;encoding</a></li>
+<li><a class="reference internal" href="#default-encoding" id="id56">5.2.8&nbsp;&nbsp;&nbsp;default_encoding</a></li>
+<li><a class="reference internal" href="#unrepr" id="id57">5.2.9&nbsp;&nbsp;&nbsp;unrepr</a></li>
+<li><a class="reference internal" href="#write-empty-values" id="id58">5.2.10&nbsp;&nbsp;&nbsp;write_empty_values</a></li>
+<li><a class="reference internal" href="#newlines" id="id59">5.2.11&nbsp;&nbsp;&nbsp;newlines</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-config-file-format" id="id60">6&nbsp;&nbsp;&nbsp;The Config File Format</a></li>
+<li><a class="reference internal" href="#sections" id="id61">7&nbsp;&nbsp;&nbsp;Sections</a><ul class="auto-toc">
+<li><a class="reference internal" href="#section-attributes" id="id62">7.1&nbsp;&nbsp;&nbsp;Section Attributes</a></li>
+<li><a class="reference internal" href="#section-methods" id="id63">7.2&nbsp;&nbsp;&nbsp;Section Methods</a></li>
+<li><a class="reference internal" href="#walking-a-section" id="id64">7.3&nbsp;&nbsp;&nbsp;Walking a Section</a></li>
+<li><a class="reference internal" href="#examples" id="id65">7.4&nbsp;&nbsp;&nbsp;Examples</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#exceptions" id="id66">8&nbsp;&nbsp;&nbsp;Exceptions</a></li>
+<li><a class="reference internal" href="#validation" id="id67">9&nbsp;&nbsp;&nbsp;Validation</a><ul class="auto-toc">
+<li><a class="reference internal" href="#configspec" id="id68">9.1&nbsp;&nbsp;&nbsp;configspec</a></li>
+<li><a class="reference internal" href="#type-conversion" id="id69">9.2&nbsp;&nbsp;&nbsp;Type Conversion</a></li>
+<li><a class="reference internal" href="#default-values" id="id70">9.3&nbsp;&nbsp;&nbsp;Default Values</a><ul class="auto-toc">
+<li><a class="reference internal" href="#id13" id="id71">9.3.1&nbsp;&nbsp;&nbsp;List Values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#repeated-sections" id="id72">9.4&nbsp;&nbsp;&nbsp;Repeated Sections</a></li>
+<li><a class="reference internal" href="#repeated-values" id="id73">9.5&nbsp;&nbsp;&nbsp;Repeated Values</a></li>
+<li><a class="reference internal" href="#copy-mode" id="id74">9.6&nbsp;&nbsp;&nbsp;Copy Mode</a></li>
+<li><a class="reference internal" href="#validation-and-interpolation" id="id75">9.7&nbsp;&nbsp;&nbsp;Validation and Interpolation</a></li>
+<li><a class="reference internal" href="#extra-values" id="id76">9.8&nbsp;&nbsp;&nbsp;Extra Values</a></li>
+<li><a class="reference internal" href="#simpleval" id="id77">9.9&nbsp;&nbsp;&nbsp;SimpleVal</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#empty-values" id="id78">10&nbsp;&nbsp;&nbsp;Empty values</a></li>
+<li><a class="reference internal" href="#unrepr-mode" id="id79">11&nbsp;&nbsp;&nbsp;unrepr mode</a></li>
+<li><a class="reference internal" href="#string-interpolation" id="id80">12&nbsp;&nbsp;&nbsp;String Interpolation</a></li>
+<li><a class="reference internal" href="#comments" id="id81">13&nbsp;&nbsp;&nbsp;Comments</a></li>
+<li><a class="reference internal" href="#flatten-errors" id="id82">14&nbsp;&nbsp;&nbsp;flatten_errors</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example-usage" id="id83">14.1&nbsp;&nbsp;&nbsp;Example Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#get-extra-values" id="id84">15&nbsp;&nbsp;&nbsp;get_extra_values</a><ul class="auto-toc">
+<li><a class="reference internal" href="#id14" id="id85">15.1&nbsp;&nbsp;&nbsp;Example Usage</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#credits" id="id86">16&nbsp;&nbsp;&nbsp;CREDITS</a></li>
+<li><a class="reference internal" href="#license" id="id87">17&nbsp;&nbsp;&nbsp;LICENSE</a></li>
+<li><a class="reference internal" href="#todo" id="id88">18&nbsp;&nbsp;&nbsp;TODO</a></li>
+<li><a class="reference internal" href="#issues" id="id89">19&nbsp;&nbsp;&nbsp;ISSUES</a></li>
+<li><a class="reference internal" href="#changelog" id="id90">20&nbsp;&nbsp;&nbsp;CHANGELOG</a><ul class="auto-toc">
+<li><a class="reference internal" href="#version-4-7-0" id="id91">20.1&nbsp;&nbsp;&nbsp;20010/01/09 - Version 4.7.0</a></li>
+<li><a class="reference internal" href="#version-4-6-0" id="id92">20.2&nbsp;&nbsp;&nbsp;2009/04/13 - Version 4.6.0</a></li>
+<li><a class="reference internal" href="#version-4-5-3" id="id93">20.3&nbsp;&nbsp;&nbsp;2008/06/27 - Version 4.5.3</a></li>
+<li><a class="reference internal" href="#version-4-5-2" id="id94">20.4&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.2</a></li>
+<li><a class="reference internal" href="#version-4-5-1" id="id95">20.5&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.1</a></li>
+<li><a class="reference internal" href="#version-4-5-0" id="id96">20.6&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.0</a></li>
+<li><a class="reference internal" href="#version-4-4-0" id="id97">20.7&nbsp;&nbsp;&nbsp;2007/02/04 - Version 4.4.0</a></li>
+<li><a class="reference internal" href="#version-4-3-3-alpha4" id="id98">20.8&nbsp;&nbsp;&nbsp;2006/12/17 - Version 4.3.3-alpha4</a></li>
+<li><a class="reference internal" href="#version-4-3-3-alpha3" id="id99">20.9&nbsp;&nbsp;&nbsp;2006/12/17 - Version 4.3.3-alpha3</a></li>
+<li><a class="reference internal" href="#version-4-3-3-alpha2" id="id100">20.10&nbsp;&nbsp;&nbsp;2006/12/09 - Version 4.3.3-alpha2</a></li>
+<li><a class="reference internal" href="#version-4-3-3-alpha1" id="id101">20.11&nbsp;&nbsp;&nbsp;2006/12/09 - Version 4.3.3-alpha1</a></li>
+<li><a class="reference internal" href="#version-4-3-2" id="id102">20.12&nbsp;&nbsp;&nbsp;2006/06/04 - Version 4.3.2</a></li>
+<li><a class="reference internal" href="#version-4-3-1" id="id103">20.13&nbsp;&nbsp;&nbsp;2006/04/29 - Version 4.3.1</a></li>
+<li><a class="reference internal" href="#version-4-3-0" id="id104">20.14&nbsp;&nbsp;&nbsp;2006/03/24 - Version 4.3.0</a></li>
+<li><a class="reference internal" href="#version-4-2-0" id="id105">20.15&nbsp;&nbsp;&nbsp;2006/02/16 - Version 4.2.0</a></li>
+<li><a class="reference internal" href="#version-4-1-0" id="id106">20.16&nbsp;&nbsp;&nbsp;2005/12/14 - Version 4.1.0</a></li>
+<li><a class="reference internal" href="#version-4-0-2" id="id107">20.17&nbsp;&nbsp;&nbsp;2005/12/02 - Version 4.0.2</a></li>
+<li><a class="reference internal" href="#version-4-0-1" id="id108">20.18&nbsp;&nbsp;&nbsp;2005/11/05 - Version 4.0.1</a></li>
+<li><a class="reference internal" href="#version-4-0-0" id="id109">20.19&nbsp;&nbsp;&nbsp;2005/10/17 - Version 4.0.0</a></li>
+<li><a class="reference internal" href="#version-4-0-0-beta-5" id="id110">20.20&nbsp;&nbsp;&nbsp;2005/09/09 - Version 4.0.0 beta 5</a></li>
+<li><a class="reference internal" href="#version-4-0-0-beta-4" id="id111">20.21&nbsp;&nbsp;&nbsp;2005/09/07 - Version 4.0.0 beta 4</a></li>
+<li><a class="reference internal" href="#version-4-0-0-beta-3" id="id112">20.22&nbsp;&nbsp;&nbsp;2005/08/28 - Version 4.0.0 beta 3</a></li>
+<li><a class="reference internal" href="#version-4-0-0-beta-2" id="id113">20.23&nbsp;&nbsp;&nbsp;2005/08/25 - Version 4.0.0 beta 2</a></li>
+<li><a class="reference internal" href="#version-4-0-0-beta-1" id="id114">20.24&nbsp;&nbsp;&nbsp;2005/08/21 - Version 4.0.0 beta 1</a></li>
+<li><a class="reference internal" href="#version-3-0-0" id="id115">20.25&nbsp;&nbsp;&nbsp;2004/05/24 - Version 3.0.0</a></li>
+<li><a class="reference internal" href="#version-2-0-0-beta" id="id116">20.26&nbsp;&nbsp;&nbsp;2004/03/14 - Version 2.0.0 beta</a></li>
+<li><a class="reference internal" href="#version-1-0-5" id="id117">20.27&nbsp;&nbsp;&nbsp;2004/01/29 - Version 1.0.5</a></li>
+<li><a class="reference internal" href="#origins" id="id118">20.28&nbsp;&nbsp;&nbsp;Origins</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#footnotes" id="id119">21&nbsp;&nbsp;&nbsp;Footnotes</a></li>
+</ul>
+</div>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>The best introduction to working with ConfigObj, including the powerful configuration validation system,
+is the article:</p>
+<ul class="last simple">
+<li><a class="reference external" href="http://www.voidspace.org.uk/python/articles/configobj.shtml">An Introduction to ConfigObj</a></li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h1><a class="toc-backref" href="#id27">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
+<p><strong>ConfigObj</strong> is a simple but powerful config file reader and writer: an <em>ini
+file round tripper</em>. Its main feature is that it is very easy to use, with a
+straightforward programmer's interface and a simple syntax for config files.
+It has lots of other features though :</p>
+<ul>
+<li><p class="first">Nested sections (subsections), to any level</p>
+</li>
+<li><p class="first">List values</p>
+</li>
+<li><p class="first">Multiple line values</p>
+</li>
+<li><p class="first">String interpolation (substitution)</p>
+</li>
+<li><p class="first">Integrated with a powerful validation system</p>
+<blockquote>
+<ul class="simple">
+<li>including automatic type checking/conversion</li>
+<li>repeated sections</li>
+<li>and allowing default values</li>
+</ul>
+</blockquote>
+</li>
+<li><p class="first">When writing out config files, ConfigObj preserves all comments and the order of members and sections</p>
+</li>
+<li><p class="first">Many useful methods and options for working with configuration files (like the 'reload' method)</p>
+</li>
+<li><p class="first">Full Unicode support</p>
+</li>
+</ul>
+<p>For support and bug reports please use the ConfigObj <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a> or the issue tracker on the
+<a class="reference external" href="http://code.google.com/p/configobj/">Google Code Homepage</a>.</p>
+</div>
+<div class="section" id="downloading">
+<h1><a class="toc-backref" href="#id28">2&nbsp;&nbsp;&nbsp;Downloading</a></h1>
+<p>The current version is <strong>4.7.0</strong>, dated 9th January 2010. ConfigObj 4 is
+stable and mature. We still expect to pick up a few bugs along the way though <a class="footnote-reference" href="#id15" id="id1">[1]</a>.</p>
+<p>You can get ConfigObj in the following ways :</p>
+<ul>
+<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/downloads/configobj.py">configobj.py</a> from Voidspace</p>
+<blockquote>
+<p>ConfigObj has no external dependencies. This file is sufficient to access
+all the functionality except <a class="reference internal" href="#validation">Validation</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/downloads/configobj-4.7.0.zip">configobj.zip</a> from Voidspace</p>
+<blockquote>
+<p>This also contains <a class="reference external" href="http://www.voidspace.org.uk/downloads/validate.py">validate.py</a> and <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">this document</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/downloads/validate.py">validate.py</a> from Voidspace</p>
+</li>
+</ul>
+<div class="section" id="installing">
+<h2><a class="toc-backref" href="#id29">2.1&nbsp;&nbsp;&nbsp;Installing</a></h2>
+<p>ConfigObj has a source distribution <a class="reference external" href="http://pypi.python.org/pypi/configobj/">on PyPI</a>. If you unzip
+the archive you can install it with:</p>
+<pre class="literal-block">
+setup.py install
+</pre>
+<p>Alternatively, you can install with easy install or pip:</p>
+<pre class="literal-block">
+easy_install configobj
+</pre>
+</div>
+<div class="section" id="documentation">
+<h2><a class="toc-backref" href="#id30">2.2&nbsp;&nbsp;&nbsp;Documentation</a></h2>
+<p><em>configobj.zip</em> also contains <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">this document</a>.</p>
+<ul class="simple">
+<li>You can view <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">this document</a> online at the <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj Homepage</a>.</li>
+</ul>
+</div>
+<div class="section" id="development-version">
+<h2><a class="toc-backref" href="#id31">2.3&nbsp;&nbsp;&nbsp;Development Version</a></h2>
+<p>It is sometimes possible to get the latest <em>development version</em> of ConfigObj
+from the Subversion Repository maintained on the <a class="reference external" href="http://code.google.com/p/configobj/">Google Code Homepage</a>.</p>
+</div>
+</div>
+<div class="section" id="configobj-in-the-real-world">
+<h1><a class="toc-backref" href="#id32">3&nbsp;&nbsp;&nbsp;ConfigObj in the Real World</a></h1>
+<p><strong>ConfigObj</strong> is widely used. Projects using it include:</p>
+<ul>
+<li><p class="first"><a class="reference external" href="http://bazaar-ng.org">Bazaar</a>.</p>
+<blockquote>
+<p>Bazaar is a Python distributed {acro;VCS;Version Control System}.
+ConfigObj is used to read <tt class="docutils literal">bazaar.conf</tt> and <tt class="docutils literal">branches.conf</tt>.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://chandler.osafoundation.org/">Chandler</a></p>
+<blockquote>
+<p>A Python and <a class="reference external" href="http://www.wxpython.org">wxPython</a>
+Personal Information Manager, being developed by the
+<a class="reference external" href="http://www.osafoundation.org/">OSAFoundation</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://matplotlib.sourceforge.net/">matplotlib</a></p>
+<blockquote>
+<p>A 2D plotting library.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://ipython.scipy.org/moin/">IPython</a></p>
+<blockquote>
+<p>IPython is an enhanced interactive Python shell. IPython uses ConfigObj in a module called 'TConfig' that combines it with enthought <a class="reference external" href="http://code.enthought.com/traits/">Traits</a>: <a class="reference external" href="http://ipython.scipy.org/ipython/ipython/browser/ipython/branches/saw/sandbox/tconfig">tconfig</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><a class="reference external" href="http://elisa.fluendo.com/">Elisa - the Fluendo Mediacenter</a></p>
+<blockquote>
+<p>Elisa is an open source cross-platform media center solution designed to be simple for people not particularly familiar with computers.</p>
+</blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="getting-started">
+<h1><a class="toc-backref" href="#id33">4&nbsp;&nbsp;&nbsp;Getting Started</a></h1>
+<p>The outstanding feature of using ConfigObj is simplicity. Most functions can be
+performed with single line commands.</p>
+<div class="section" id="reading-a-config-file">
+<h2><a class="toc-backref" href="#id34">4.1&nbsp;&nbsp;&nbsp;Reading a Config File</a></h2>
+<p>The normal way to read a config file, is to give ConfigObj the filename :</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
+</pre></div>
+<p>You can also pass the config file in as a list of lines, or a <tt class="docutils literal">StringIO</tt>
+instance, so it doesn't matter where your config data comes from.</p>
+<p>You can then access members of your config file as a dictionary. Subsections
+will also be dictionaries.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="n">value1</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s">&#39;keyword1&#39;</span><span class="p">]</span>
+<span class="n">value2</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s">&#39;keyword2&#39;</span><span class="p">]</span>
+<span class="c">#</span>
+<span class="n">section1</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">]</span>
+<span class="n">value3</span> <span class="o">=</span> <span class="n">section1</span><span class="p">[</span><span class="s">&#39;keyword3&#39;</span><span class="p">]</span>
+<span class="n">value4</span> <span class="o">=</span> <span class="n">section1</span><span class="p">[</span><span class="s">&#39;keyword4&#39;</span><span class="p">]</span>
+<span class="c">#</span>
+<span class="c"># you could also write</span>
+<span class="n">value3</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">][</span><span class="s">&#39;keyword3&#39;</span><span class="p">]</span>
+<span class="n">value4</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">][</span><span class="s">&#39;keyword4&#39;</span><span class="p">]</span>
+</pre></div>
+</div>
+<div class="section" id="writing-a-config-file">
+<h2><a class="toc-backref" href="#id35">4.2&nbsp;&nbsp;&nbsp;Writing a Config File</a></h2>
+<p>Creating a new config file is just as easy as reading one. You can specify a
+filename when you create the ConfigObj, or do it later <a class="footnote-reference" href="#id16" id="id2">[2]</a>.</p>
+<p>If you <em>don't</em> set a filename, then the <tt class="docutils literal">write</tt> method will return a list of
+lines instead of writing to file. See the <a class="reference internal" href="#write">write</a> method for more details.</p>
+<p>Here we show creating an empty ConfigObj, setting a filename and some values,
+and then writing to file :</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">()</span>
+<span class="n">config</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="n">filename</span>
+<span class="c">#</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;keyword1&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">value1</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;keyword2&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">value2</span>
+<span class="c">#</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">][</span><span class="s">&#39;keyword3&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">value3</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section1&#39;</span><span class="p">][</span><span class="s">&#39;keyword4&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">value4</span>
+<span class="c">#</span>
+<span class="n">section2</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="s">&#39;keyword5&#39;</span><span class="p">:</span> <span class="n">value5</span><span class="p">,</span>
+ <span class="s">&#39;keyword6&#39;</span><span class="p">:</span> <span class="n">value6</span><span class="p">,</span>
+ <span class="s">&#39;sub-section&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword7&#39;</span><span class="p">:</span> <span class="n">value7</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section2&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">section2</span>
+<span class="c">#</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section3&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section3&#39;</span><span class="p">][</span><span class="s">&#39;keyword 8&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">value8</span><span class="p">,</span> <span class="n">value9</span><span class="p">,</span> <span class="n">value10</span><span class="p">]</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;section3&#39;</span><span class="p">][</span><span class="s">&#39;keyword 9&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="p">[</span><span class="n">value11</span><span class="p">,</span> <span class="n">value12</span><span class="p">,</span> <span class="n">value13</span><span class="p">]</span>
+<span class="c">#</span>
+<span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">()</span>
+</pre></div>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Keywords and section names can only be strings <a class="footnote-reference" href="#id17" id="id3">[3]</a>. Attempting to set
+anything else will raise a <tt class="docutils literal">ValueError</tt>.</p>
+</div>
+</div>
+<div class="section" id="config-files">
+<h2><a class="toc-backref" href="#id36">4.3&nbsp;&nbsp;&nbsp;Config Files</a></h2>
+<p>The config files that ConfigObj will read and write are based on the 'INI'
+format. This means it will read and write files created for <tt class="docutils literal">ConfigParser</tt>
+<a class="footnote-reference" href="#id18" id="id4">[4]</a>.</p>
+<p>Keywords and values are separated by an <tt class="docutils literal">'='</tt>, and section markers are
+between square brackets. Keywords, values, and section names can be surrounded
+by single or double quotes. Indentation is not significant, but can be
+preserved.</p>
+<p>Subsections are indicated by repeating the square brackets in the section
+marker. You nest levels by using more brackets.</p>
+<p>You can have list values by separating items with a comma, and values spanning
+multiple lines by using triple quotes (single or double).</p>
+<p>For full details on all these see <a class="reference internal" href="#the-config-file-format">the config file format</a>. Here's an example
+to illustrate:</p>
+<pre class="literal-block">
+# This is the 'initial_comment'
+# Which may be several lines
+keyword1 = value1
+'keyword 2' = 'value 2'
+
+[ &quot;section 1&quot; ]
+# This comment goes with keyword 3
+keyword 3 = value 3
+'keyword 4' = value4, value 5, 'value 6'
+
+ [[ sub-section ]] # an inline comment
+ # sub-section is inside &quot;section 1&quot;
+ 'keyword 5' = 'value 7'
+ 'keyword 6' = '''A multiline value,
+that spans more than one line :-)
+The line breaks are included in the value.'''
+
+ [[[ sub-sub-section ]]]
+ # sub-sub-section is *in* 'sub-section'
+ # which is in 'section 1'
+ 'keyword 7' = 'value 8'
+
+[section 2] # an inline comment
+keyword8 = &quot;value 9&quot;
+keyword9 = value10 # an inline comment
+# The 'final_comment'
+# Which also may be several lines
+</pre>
+</div>
+</div>
+<div class="section" id="configobj-specifications">
+<h1><a class="toc-backref" href="#id37">5&nbsp;&nbsp;&nbsp;ConfigObj specifications</a></h1>
+<div class="highlight"><pre><span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">infile</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
+ <span class="n">interpolation</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">list_values</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
+ <span class="n">create_empty</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">file_error</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">stringify</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
+ <span class="n">indent_type</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">default_encoding</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">unrepr</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
+ <span class="n">write_empty_values</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">_inspec</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
+</pre></div>
+<p>Many of the keyword arguments are available as attributes after the config file has been
+parsed.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>New in ConfigObj 4.7.0: It is no longer possible to instantiate ConfigObj with
+an <tt class="docutils literal">options</tt> dictionary as in earlier versions. To modify code that used to
+do this simply unpack the dictionary in the constructor call:</p>
+<div class="last"><div class="highlight"><pre><span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="o">**</span><span class="n">options</span><span class="p">)</span>
+</pre></div>
+</div></div>
+<p>ConfigObj takes the following arguments (with the default values shown) :</p>
+<ul>
+<li><p class="first">infile: <tt class="docutils literal">None</tt></p>
+<blockquote>
+<p>You don't need to specify an infile. If you omit it, an empty ConfigObj will be
+created. <tt class="docutils literal">infile</tt> <em>can</em> be :</p>
+<ul class="simple">
+<li>Nothing. In which case the <tt class="docutils literal">filename</tt> attribute of your ConfigObj will be
+<tt class="docutils literal">None</tt>. You can set a filename at any time.</li>
+<li>A filename. What happens if the file doesn't already exist is determined by
+the options <tt class="docutils literal">file_error</tt> and <tt class="docutils literal">create_empty</tt>. The filename will be
+preserved as the <tt class="docutils literal">filename</tt> attribute. This can be changed at any time.</li>
+<li>A list of lines. Any trailing newlines will be removed from the lines. The
+<tt class="docutils literal">filename</tt> attribute of your ConfigObj will be <tt class="docutils literal">None</tt>.</li>
+<li>A <tt class="docutils literal">StringIO</tt> instance or file object, or any object with a <tt class="docutils literal">read</tt> method.
+The <tt class="docutils literal">filename</tt> attribute of your ConfigObj will be <tt class="docutils literal">None</tt> <a class="footnote-reference" href="#id19" id="id5">[5]</a>.</li>
+<li>A dictionary. You can initialise a ConfigObj from a dictionary <a class="footnote-reference" href="#id20" id="id6">[6]</a>. The
+<tt class="docutils literal">filename</tt> attribute of your ConfigObj will be <tt class="docutils literal">None</tt>. All keys must be
+strings. In this case, the order of values and sections is arbitrary.</li>
+</ul>
+</blockquote>
+</li>
+<li><p class="first">'raise_errors': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>When parsing, it is possible that the config file will be badly formed. The
+default is to parse the whole file and raise a single error at the end. You
+can set <tt class="docutils literal">raise_errors = True</tt> to have errors raised immediately. See the
+<a class="reference internal" href="#exceptions">exceptions</a> section for more details.</p>
+<p>Altering this value after initial parsing has no effect.</p>
+</blockquote>
+</li>
+<li><p class="first">'list_values': <tt class="docutils literal">True</tt></p>
+<blockquote>
+<p>If <tt class="docutils literal">True</tt> (the default) then list values are possible. If <tt class="docutils literal">False</tt>, the
+values are not parsed for lists.</p>
+<p>If <tt class="docutils literal">list_values = False</tt> then single line values are not quoted or
+unquoted when reading and writing.</p>
+<p>Changing this value affects whether single line values will be quoted or
+not when writing.</p>
+</blockquote>
+</li>
+<li><p class="first">'create_empty': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>If this value is <tt class="docutils literal">True</tt> and the file specified by <tt class="docutils literal">infile</tt> doesn't
+exist, ConfigObj will create an empty file. This can be a useful test that
+the filename makes sense: an impossible filename will cause an error.</p>
+<p>Altering this value after initial parsing has no effect.</p>
+</blockquote>
+</li>
+<li><p class="first">'file_error': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>If this value is <tt class="docutils literal">True</tt> and the file specified by <tt class="docutils literal">infile</tt> doesn't
+exist, ConfigObj will raise an <tt class="docutils literal">IOError</tt>.</p>
+<p>Altering this value after initial parsing has no effect.</p>
+</blockquote>
+</li>
+<li><p class="first">'interpolation': <tt class="docutils literal">True</tt></p>
+<blockquote>
+<p>Whether string interpolation is switched on or not. It is on (<tt class="docutils literal">True</tt>) by
+default.</p>
+<p>You can set this attribute to change whether string interpolation is done
+when values are fetched. See the <a class="reference internal" href="#string-interpolation">String Interpolation</a> section for more details.</p>
+<p>New in ConfigObj 4.7.0: Interpolation will also be done in list values.</p>
+</blockquote>
+</li>
+<li><p class="first">'configspec': <tt class="docutils literal">None</tt></p>
+<blockquote>
+<p>If you want to use the validation system, you supply a configspec. This is
+effectively a type of config file that specifies a check for each member.
+This check can be used to do type conversion as well as check that the
+value is within your required parameters.</p>
+<p>You provide a configspec in the same way as you do the initial file: a
+filename, or list of lines, etc. See the <a class="reference internal" href="#validation">validation</a> section for full
+details on how to use the system.</p>
+<p>When parsed, every section has a <tt class="docutils literal">configspec</tt> with a dictionary of
+configspec checks for <em>that section</em>.</p>
+</blockquote>
+</li>
+<li><p class="first">'stringify': <tt class="docutils literal">True</tt></p>
+<blockquote>
+<p>If you use the validation scheme, it can do type checking <em>and</em> conversion
+for you. This means you may want to set members to integers, or other
+non-string values.</p>
+<p>If 'stringify' is set to <tt class="docutils literal">True</tt> (default) then non-string values will
+be converted to strings when you write the config file. The <a class="reference internal" href="#validation">validation</a>
+process converts values from strings to the required type.</p>
+<p>If 'stringify' is set to <tt class="docutils literal">False</tt>, attempting to set a member to a
+non-string value <a class="footnote-reference" href="#id21" id="id7">[7]</a> will raise a <tt class="docutils literal">TypeError</tt> (no type conversion is
+done by validation).</p>
+</blockquote>
+</li>
+<li><p class="first">'indent_type': <tt class="docutils literal">'&nbsp;&nbsp;&nbsp; '</tt></p>
+<blockquote>
+<p>Indentation is not significant; it can however be present in the input and
+output config. Any combination of tabs and spaces may be used: the string
+will be repeated for each level of indentation. Typical values are: <tt class="docutils literal">''</tt>
+(no indentation), <tt class="docutils literal">'&nbsp;&nbsp;&nbsp; '</tt> (indentation with four spaces, the default),
+<tt class="docutils literal">'\t'</tt> (indentation with one tab).</p>
+<p>If this option is not specified, and the ConfigObj is initialised with a
+dictionary, the indentation used in the output is the default one, that is,
+four spaces.</p>
+<p>If this option is not specified, and the ConfigObj is initialised with a
+list of lines or a file, the indentation used in the first indented line is
+selected and used in all output lines. If no input line is indented, no
+output line will be either.</p>
+<p>If this option <em>is</em> specified, the option value is used in the output
+config, overriding the type of indentation in the input config (if any).</p>
+</blockquote>
+</li>
+<li><p class="first">'encoding': <tt class="docutils literal">None</tt></p>
+<blockquote>
+<p>By default <strong>ConfigObj</strong> does not decode the file/strings you pass it into
+Unicode <a class="footnote-reference" href="#id22" id="id8">[8]</a>. If you want your config file as Unicode (keys and members)
+you need to provide an encoding to decode the file with. This encoding will
+also be used to encode the config file when writing.</p>
+<p>You can change the encoding attribute at any time.</p>
+<p>Any characters in your strings that can't be encoded with the specified
+encoding will raise a <tt class="docutils literal">UnicodeEncodeError</tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p><tt class="docutils literal">UTF16</tt> encoded files will automatically be detected and decoded,
+even if <tt class="docutils literal">encoding</tt> is <tt class="docutils literal">None</tt>.</p>
+<p class="last">This is because it is a 16-bit encoding, and ConfigObj will mangle it
+(split characters on byte boundaries) if it parses it without decoding.</p>
+</div>
+</blockquote>
+</li>
+<li><p class="first">'default_encoding': <tt class="docutils literal">None</tt></p>
+<blockquote>
+<p>When using the <tt class="docutils literal">write</tt> method, <strong>ConfigObj</strong> uses the <tt class="docutils literal">encoding</tt>
+attribute to encode the Unicode strings. If any members (or keys) have
+been set as byte strings instead of Unicode, these must first be decoded
+to Unicode before outputting in the specified encoding.</p>
+<p><tt class="docutils literal">default_encoding</tt>, if specified, is the encoding used to decode byte
+strings in the <strong>ConfigObj</strong> before writing. If this is <tt class="docutils literal">None</tt>, then
+the Python default encoding (<tt class="docutils literal">sys.defaultencoding</tt> - usually ASCII) is
+used.</p>
+<p>For most Western European users, a value of <tt class="docutils literal"><span class="pre">latin-1</span></tt> is sensible.</p>
+<p><tt class="docutils literal">default_encoding</tt> is <em>only</em> used if an <tt class="docutils literal">encoding</tt> is specified.</p>
+<p>Any characters in byte-strings that can't be decoded using the
+<tt class="docutils literal">default_encoding</tt> will raise a <tt class="docutils literal">UnicodeDecodeError</tt>.</p>
+</blockquote>
+</li>
+<li><p class="first">'unrepr': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>The <tt class="docutils literal">unrepr</tt> option reads and writes files in a different mode. This
+allows you to store and retrieve the basic Python data-types using config
+files.</p>
+<p>This uses Python syntax for lists and quoting. See <a class="reference internal" href="#unrepr-mode">unrepr mode</a> for the
+full details.</p>
+</blockquote>
+</li>
+<li><p class="first">'write_empty_values': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>If <tt class="docutils literal">write_empty_values</tt> is <tt class="docutils literal">True</tt>, empty strings are written as
+empty values. See <a class="reference internal" href="#empty-values">Empty Values</a> for more details.</p>
+</blockquote>
+</li>
+<li><p class="first">'_inspec': <tt class="docutils literal">False</tt></p>
+<blockquote>
+<p>Used internally by ConfigObj when parsing configspec files. If you are
+creating a ConfigObj instance from a configspec file you must pass True
+for this argument as well as <tt class="docutils literal">list_values=False</tt>.</p>
+</blockquote>
+</li>
+</ul>
+<div class="section" id="methods">
+<h2><a class="toc-backref" href="#id38">5.1&nbsp;&nbsp;&nbsp;Methods</a></h2>
+<p>The ConfigObj is a subclass of an object called <tt class="docutils literal">Section</tt>, which is itself a
+subclass of <tt class="docutils literal">dict</tt>, the builtin dictionary type. This means it also has
+<strong>all</strong> the normal dictionary methods.</p>
+<p>In addition, the following <a class="reference internal" href="#section-methods">Section Methods</a> may be useful :</p>
+<ul class="simple">
+<li>'restore_default'</li>
+<li>'restore_defaults'</li>
+<li>'walk'</li>
+<li>'merge'</li>
+<li>'dict'</li>
+<li>'as_bool'</li>
+<li>'as_float'</li>
+<li>'as_int'</li>
+<li>'as_list'</li>
+</ul>
+<p>Read about <a class="reference internal" href="#sections">Sections</a> for details of all the methods.</p>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p>The <em>merge</em> method of sections is a recursive update.</p>
+<p>You can use this to merge sections, or even whole ConfigObjs, into each
+other.</p>
+<p class="last">You would typically use this to create a default ConfigObj and then merge
+in user settings. This way users only need to specify values that are
+different from the default. You can use configspecs and validation to
+achieve the same thing of course.</p>
+</div>
+<p>The public methods available on ConfigObj are :</p>
+<ul class="simple">
+<li>'write'</li>
+<li>'validate'</li>
+<li>'reset'</li>
+<li>'reload'</li>
+</ul>
+<div class="section" id="write">
+<h3><a class="toc-backref" href="#id39">5.1.1&nbsp;&nbsp;&nbsp;write</a></h3>
+<div class="highlight"><pre><span class="n">write</span><span class="p">(</span><span class="n">file_object</span><span class="o">=</span><span class="bp">None</span><span class="p">)</span>
+</pre></div>
+<p>This method writes the current ConfigObj and takes a single, optional argument
+<a class="footnote-reference" href="#id23" id="id9">[9]</a>.</p>
+<p>If you pass in a file like object to the <tt class="docutils literal">write</tt> method, the config file will
+be written to this. (The only method of this object that is used is its
+<tt class="docutils literal">write</tt> method, so a <tt class="docutils literal">StringIO</tt> instance, or any other file like object
+will work.)</p>
+<p>Otherwise, the behaviour of this method depends on the <tt class="docutils literal">filename</tt> attribute
+of the ConfigObj.</p>
+<dl class="docutils">
+<dt><tt class="docutils literal">filename</tt></dt>
+<dd>ConfigObj will write the configuration to the file specified.</dd>
+<dt><tt class="docutils literal">None</tt></dt>
+<dd><tt class="docutils literal">write</tt> returns a list of lines. (Not <tt class="docutils literal">'\n'</tt> terminated)</dd>
+</dl>
+<p>First the 'initial_comment' is written, then the config file, followed by the
+'final_comment'. Comment lines and inline comments are written with each
+key/value.</p>
+</div>
+<div class="section" id="validate">
+<h3><a class="toc-backref" href="#id40">5.1.2&nbsp;&nbsp;&nbsp;validate</a></h3>
+<div class="highlight"><pre><span class="n">validate</span><span class="p">(</span><span class="n">validator</span><span class="p">,</span> <span class="n">preserve_errors</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">copy</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
+</pre></div>
+<div class="highlight"><pre><span class="c"># filename is the config file</span>
+<span class="c"># filename2 is the configspec</span>
+<span class="c"># (which could also be hardcoded into your program)</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">filename2</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="n">val</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+<span class="n">test</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">test</span> <span class="o">==</span> <span class="bp">True</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;Succeeded.&#39;</span>
+</pre></div>
+<p>The validate method uses the <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">validate</a> module to do the
+validation.</p>
+<p>This method validates the ConfigObj against the configspec. By doing type
+conversion as well it can abstract away the config file altogether and present
+the config <em>data</em> to your application (in the types it expects it to be).</p>
+<p>If the <tt class="docutils literal">configspec</tt> attribute of the ConfigObj is <tt class="docutils literal">None</tt>, it raises a
+<tt class="docutils literal">ValueError</tt>.</p>
+<p>If the <a class="reference internal" href="#stringify">stringify</a> attribute is set, this process will convert values to the
+type defined in the configspec.</p>
+<p>The validate method uses checks specified in the configspec and defined in the
+<tt class="docutils literal">Validator</tt> object. It is very easy to extend.</p>
+<p>The configspec looks like the config file, but instead of the value, you
+specify the check (and any default value). See the <a class="reference internal" href="#validation">validation</a> section for
+details.</p>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p>The system of configspecs can seem confusing at first, but is actually
+quite simple and powerful. The best guide to them is this article on
+ConfigObj:</p>
+<ul class="last simple">
+<li><a class="reference external" href="http://www.voidspace.org.uk/python/articles/configobj.shtml">An Introduction to ConfigObj</a></li>
+</ul>
+</div>
+<p>The <tt class="docutils literal">copy</tt> parameter fills in missing values from the configspec (default
+values), <em>without</em> marking the values as defaults. It also causes comments to
+be copied from the configspec into the config file. This allows you to use a
+configspec to create default config files. (Normally default values aren't
+written out by the <tt class="docutils literal">write</tt> method.)</p>
+<p>As of ConfigObj 4.3.0 you can also pass in a ConfigObj instance as your
+configspec. This is especially useful if you need to specify the encoding of
+your configspec file. When you read your configspec file, you <em>must</em> specify
+<tt class="docutils literal">list_values=False</tt>. If you need to support hashes inside the configspec
+values then you must also pass in <tt class="docutils literal">_inspec=True</tt>. This is because configspec
+files actually use a different syntax to config files and inline comment support
+must be switched off to correctly read configspec files with hashes in the values.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">configspec</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">configspecfilename</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s">&#39;UTF8&#39;</span><span class="p">,</span>
+ <span class="n">list_values</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">_inspec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">configspec</span><span class="p">)</span>
+</pre></div>
+<div class="section" id="return-value">
+<h4><a class="toc-backref" href="#id41">5.1.2.1&nbsp;&nbsp;&nbsp;Return Value</a></h4>
+<p>By default, the validate method either returns <tt class="docutils literal">True</tt> (everything passed)
+or a dictionary of <tt class="docutils literal">True</tt> / <tt class="docutils literal">False</tt> representing pass/fail. The dictionary
+follows the structure of the ConfigObj.</p>
+<p>If a whole section passes then it is replaced with the value <tt class="docutils literal">True</tt>. If a
+whole section fails, then it is replaced with the value <tt class="docutils literal">False</tt>.</p>
+<p>If a value is missing, and there is no default in the check, then the check
+automatically fails.</p>
+<p>The <tt class="docutils literal">validate</tt> method takes an optional keyword argument <tt class="docutils literal">preserve_errors</tt>.
+If you set this to <tt class="docutils literal">True</tt>, instead of getting <tt class="docutils literal">False</tt> for failed checks you
+get the actual error object from the <strong>validate</strong> module. This usually contains
+useful information about why the check failed.</p>
+<p>See the <a class="reference internal" href="#flatten-errors">flatten_errors</a> function for how to turn your results dictionary into
+a useful list of error messages.</p>
+<p>Even if <tt class="docutils literal">preserve_errors</tt> is <tt class="docutils literal">True</tt>, missing keys or sections will still be
+represented by a <tt class="docutils literal">False</tt> in the results dictionary.</p>
+</div>
+<div class="section" id="mentioning-default-values">
+<h4><a class="toc-backref" href="#id42">5.1.2.2&nbsp;&nbsp;&nbsp;Mentioning Default Values</a></h4>
+<p>In the check in your configspec, you can specify a default to be used - by
+using the <tt class="docutils literal">default</tt> keyword. E.g.</p>
+<pre class="literal-block">
+key1 = integer(0, 30, default=15)
+key2 = integer(default=15)
+key3 = boolean(default=True)
+key4 = option('Hello', 'Goodbye', 'Not Today', default='Not Today')
+</pre>
+<p>If the configspec check supplies a default and the value is missing in the
+config, then the default will be set in your ConfigObj. (It is still passed to
+the <tt class="docutils literal">Validator</tt> so that type conversion can be done: this means the default
+value must still pass the check.)</p>
+<p>ConfigObj keeps a record of which values come from defaults, using the
+<tt class="docutils literal">defaults</tt> attribute of <a class="reference internal" href="#sections">sections</a>. Any key in this list isn't written out by
+the <tt class="docutils literal">write</tt> method. If a key is set from outside (even to the same value)
+then it is removed from the <tt class="docutils literal">defaults</tt> list.</p>
+<!-- note:
+
+Even if all the keys in a section are in the defaults list, the section
+marker is still written out. -->
+<p>There is additionally a special case default value of <tt class="docutils literal">None</tt>. If you set the
+default value to <tt class="docutils literal">None</tt> and the value is missing, the value will always be
+set to <tt class="docutils literal">None</tt>. As the other checks don't return <tt class="docutils literal">None</tt> (unless you
+implement your own that do), you can tell that this value came from a default
+value (and was missing from the config file). It allows an easy way of
+implementing optional values. Simply check (and ignore) members that are set
+to <tt class="docutils literal">None</tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If <a class="reference internal" href="#stringify">stringify</a> is <tt class="docutils literal">False</tt> then <tt class="docutils literal">default=None</tt> returns <tt class="docutils literal">''</tt> instead of
+<tt class="docutils literal">None</tt>. This is because setting a value to a non-string raises an error
+if stringify is unset.</p>
+</div>
+<p>The default value can be a list. See <a class="reference internal" href="#id13">List Values</a> for the way to do this.</p>
+<p>Writing invalid default values is a <em>guaranteed</em> way of confusing your users.
+Default values <strong>must</strong> pass the check.</p>
+</div>
+<div class="section" id="mentioning-repeated-sections-and-values">
+<h4><a class="toc-backref" href="#id43">5.1.2.3&nbsp;&nbsp;&nbsp;Mentioning Repeated Sections and Values</a></h4>
+<p>In the configspec it is possible to cause <em>every</em> sub-section in a section to
+be validated using the same configspec. You do this with a section in the
+configspec called <tt class="docutils literal">__many__</tt>. Every sub-section in that section has the
+<tt class="docutils literal">__many__</tt> configspec applied to it (without you having to explicitly name
+them in advance).</p>
+<p>Your <tt class="docutils literal">__many__</tt> section can have nested subsections, which can also include
+<tt class="docutils literal">__many__</tt> type sections.</p>
+<p>You can also specify that all values should be validated using the same configspec,
+by having a member with the name <tt class="docutils literal">__many__</tt>. If you want to use repeated values
+along with repeated sections then you can call one of them <tt class="docutils literal">___many___</tt> (triple
+underscores).</p>
+<p>Sections with repeated sections or values can also have specifically named sub-sections
+or values. The <tt class="docutils literal">__many__</tt> configspec will only be used to validate entries that don't
+have an explicit configspec.</p>
+<p>See <a class="reference internal" href="#repeated-sections">Repeated Sections</a> for examples.</p>
+</div>
+<div class="section" id="mentioning-simpleval">
+<h4><a class="toc-backref" href="#id44">5.1.2.4&nbsp;&nbsp;&nbsp;Mentioning SimpleVal</a></h4>
+<p>If you just want to check if all members are present, then you can use the
+<tt class="docutils literal">SimpleVal</tt> object that comes with ConfigObj. It only fails members if they
+are missing.</p>
+<p>Write a configspec that has all the members you want to check for, but set
+every section to <tt class="docutils literal">''</tt>.</p>
+<div class="highlight"><pre><span class="n">val</span> <span class="o">=</span> <span class="n">SimpleVal</span><span class="p">()</span>
+<span class="n">test</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">test</span> <span class="ow">is</span> <span class="bp">True</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;Succeeded.&#39;</span>
+</pre></div>
+</div>
+<div class="section" id="mentioning-copy-mode">
+<h4><a class="toc-backref" href="#id45">5.1.2.5&nbsp;&nbsp;&nbsp;Mentioning copy Mode</a></h4>
+<p>As discussed in <a class="reference internal" href="#mentioning-default-values">Mentioning Default Values</a>, you can use a configspec to
+supply default values. These are marked in the ConfigObj instance as defaults,
+and <em>not</em> written out by the <tt class="docutils literal">write</tt> mode. This means that your users only
+need to supply values that are different from the defaults.</p>
+<p>This can be inconvenient if you <em>do</em> want to write out the default values,
+for example to write out a default config file.</p>
+<p>If you set <tt class="docutils literal">copy=True</tt> when you call validate, then no values are marked as
+defaults. In addition, all comments from the configspec are copied into
+your ConfigObj instance. You can then call <tt class="docutils literal">write</tt> to create your config
+file.</p>
+<p>There is a limitation with this. In order to allow <a class="reference internal" href="#string-interpolation">String Interpolation</a> to work
+within configspecs, <tt class="docutils literal">DEFAULT</tt> sections are not processed by
+validation; even in copy mode.</p>
+</div>
+</div>
+<div class="section" id="reload">
+<h3><a class="toc-backref" href="#id46">5.1.3&nbsp;&nbsp;&nbsp;reload</a></h3>
+<p>If a ConfigObj instance was loaded from the filesystem, then this method will reload it. It
+will also reuse any configspec you supplied at instantiation (including reloading it from
+the filesystem if you passed it in as a filename).</p>
+<p>If the ConfigObj does not have a filename attribute pointing to a file, then a <tt class="docutils literal">ReloadError</tt>
+will be raised.</p>
+</div>
+<div class="section" id="reset">
+<h3><a class="toc-backref" href="#id47">5.1.4&nbsp;&nbsp;&nbsp;reset</a></h3>
+<p>This method takes no arguments and doesn't return anything. It restores a ConfigObj
+instance to a freshly created state.</p>
+</div>
+</div>
+<div class="section" id="attributes">
+<h2><a class="toc-backref" href="#id48">5.2&nbsp;&nbsp;&nbsp;Attributes</a></h2>
+<p>A ConfigObj has the following attributes :</p>
+<ul class="simple">
+<li>indent_type</li>
+<li>interpolate</li>
+<li>stringify</li>
+<li>BOM</li>
+<li>initial_comment</li>
+<li>final_comment</li>
+<li>list_values</li>
+<li>encoding</li>
+<li>default_encoding</li>
+<li>unrepr</li>
+<li>write_empty_values</li>
+<li>newlines</li>
+</ul>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This doesn't include <em>comments</em>, <em>inline_comments</em>, <em>defaults</em>, or
+<em>configspec</em>. These are actually attributes of <a class="reference internal" href="#sections">Sections</a>.</p>
+</div>
+<p>It also has the following attributes as a result of parsing. They correspond to
+options when the ConfigObj was created, but changing them has no effect.</p>
+<ul class="simple">
+<li>raise_errors</li>
+<li>create_empty</li>
+<li>file_error</li>
+</ul>
+<div class="section" id="interpolation">
+<h3><a class="toc-backref" href="#id49">5.2.1&nbsp;&nbsp;&nbsp;interpolation</a></h3>
+<p>ConfigObj can perform string interpolation in a <em>similar</em> way to
+<tt class="docutils literal">ConfigParser</tt>. See the <a class="reference internal" href="#string-interpolation">String Interpolation</a> section for full details.</p>
+<p>If <tt class="docutils literal">interpolation</tt> is set to <tt class="docutils literal">False</tt>, then interpolation is <em>not</em> done when
+you fetch values.</p>
+</div>
+<div class="section" id="stringify">
+<h3><a class="toc-backref" href="#id50">5.2.2&nbsp;&nbsp;&nbsp;stringify</a></h3>
+<p>If this attribute is set (<tt class="docutils literal">True</tt>) then the <a class="reference internal" href="#validate">validate</a> method changes the
+values in the ConfigObj. These are turned back into strings when <a class="reference internal" href="#write">write</a> is
+called.</p>
+<p>If stringify is unset (<tt class="docutils literal">False</tt>) then attempting to set a value to a non
+string (or a list of strings) will raise a <tt class="docutils literal">TypeError</tt>.</p>
+</div>
+<div class="section" id="bom">
+<h3><a class="toc-backref" href="#id51">5.2.3&nbsp;&nbsp;&nbsp;BOM</a></h3>
+<p>If the initial config file <em>started</em> with the UTF8 Unicode signature (known
+slightly incorrectly as the BOM - Byte Order Mark), or the UTF16 BOM, then
+this attribute is set to <tt class="docutils literal">True</tt>. Otherwise it is <tt class="docutils literal">False</tt>.</p>
+<p>If it is set to <tt class="docutils literal">True</tt> when <tt class="docutils literal">write</tt> is called then, if <tt class="docutils literal">encoding</tt> is set
+to <tt class="docutils literal">None</tt> <em>or</em> to <tt class="docutils literal">utf_8</tt> (and variants) a UTF BOM will be written.</p>
+<p>For UTF16 encodings, a BOM is <em>always</em> written.</p>
+</div>
+<div class="section" id="initial-comment">
+<h3><a class="toc-backref" href="#id52">5.2.4&nbsp;&nbsp;&nbsp;initial_comment</a></h3>
+<p>This is a list of lines. If the ConfigObj is created from an existing file, it
+will contain any lines of comments before the start of the members.</p>
+<p>If you create a new ConfigObj, this will be an empty list.</p>
+<p>The write method puts these lines before it starts writing out the members.</p>
+</div>
+<div class="section" id="final-comment">
+<h3><a class="toc-backref" href="#id53">5.2.5&nbsp;&nbsp;&nbsp;final_comment</a></h3>
+<p>This is a list of lines. If the ConfigObj is created from an existing file, it
+will contain any lines of comments after the last member.</p>
+<p>If you create a new ConfigObj, this will be an empty list.</p>
+<p>The <tt class="docutils literal">write</tt> method puts these lines after it finishes writing out the
+members.</p>
+</div>
+<div class="section" id="list-values">
+<h3><a class="toc-backref" href="#id54">5.2.6&nbsp;&nbsp;&nbsp;list_values</a></h3>
+<p>This attribute is <tt class="docutils literal">True</tt> or <tt class="docutils literal">False</tt>. If set to <tt class="docutils literal">False</tt> then values are
+not parsed for list values. In addition single line values are not unquoted.</p>
+<p>This allows you to do your own parsing of values. It exists primarily to
+support the reading of the <a class="reference internal" href="#configspec">configspec</a> - but has other use cases.</p>
+<p>For example you could use the <tt class="docutils literal">LineParser</tt> from the
+<a class="reference external" href="http://www.voidspace.org.uk/python/listquote.html#lineparser">listquote module</a>
+to read values for nested lists.</p>
+<p>Single line values aren't quoted when writing - but multiline values are
+handled as normal.</p>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Because values aren't quoted, leading or trailing whitespace can be lost. This behaviour was changed in version 4.0.1. Prior to this, single line values might have been quoted; even with <tt class="docutils literal">list_values=False</tt>. This means that files written by earlier versions of ConfigObj <em>could</em> now be incompatible and need the quotes removing by hand.</p>
+</div>
+</div>
+<div class="section" id="encoding">
+<h3><a class="toc-backref" href="#id55">5.2.7&nbsp;&nbsp;&nbsp;encoding</a></h3>
+<p>This is the encoding used to encode the output, when you call <tt class="docutils literal">write</tt>. It
+must be a valid encoding <a class="reference external" href="http://docs.python.org/lib/standard-encodings.html">recognised by Python</a>.</p>
+<p>If this value is <tt class="docutils literal">None</tt> then no encoding is done when <tt class="docutils literal">write</tt> is called.</p>
+</div>
+<div class="section" id="default-encoding">
+<h3><a class="toc-backref" href="#id56">5.2.8&nbsp;&nbsp;&nbsp;default_encoding</a></h3>
+<p>If encoding is set, any byte-strings in your ConfigObj instance (keys or
+members) will first be decoded to Unicode using the encoding specified by the
+<tt class="docutils literal">default_encoding</tt> attribute. This ensures that the output is in the encoding
+specified.</p>
+<p>If this value is <tt class="docutils literal">None</tt> then <tt class="docutils literal">sys.defaultencoding</tt> is used instead.</p>
+</div>
+<div class="section" id="unrepr">
+<h3><a class="toc-backref" href="#id57">5.2.9&nbsp;&nbsp;&nbsp;unrepr</a></h3>
+<p>Another boolean value. If this is set, then <tt class="docutils literal">repr(value)</tt> is used to write
+values. This writes values in a slightly different way to the normal ConfigObj
+file syntax.</p>
+<p>This preserves basic Python data-types when read back in. See <a class="reference internal" href="#unrepr-mode">unrepr mode</a>
+for more details.</p>
+</div>
+<div class="section" id="write-empty-values">
+<h3><a class="toc-backref" href="#id58">5.2.10&nbsp;&nbsp;&nbsp;write_empty_values</a></h3>
+<p>Also boolean. If set, values that are an empty string (<tt class="docutils literal">''</tt>) are written as
+empty values. See <a class="reference internal" href="#empty-values">Empty Values</a> for more details.</p>
+</div>
+<div class="section" id="newlines">
+<h3><a class="toc-backref" href="#id59">5.2.11&nbsp;&nbsp;&nbsp;newlines</a></h3>
+<p>When a config file is read, ConfigObj records the type of newline separators in the
+file and uses this separator when writing. It defaults to <tt class="docutils literal">None</tt>, and ConfigObj
+uses the system default (<tt class="docutils literal">os.sep</tt>) if write is called without newlines having
+been set.</p>
+</div>
+</div>
+</div>
+<div class="section" id="the-config-file-format">
+<h1><a class="toc-backref" href="#id60">6&nbsp;&nbsp;&nbsp;The Config File Format</a></h1>
+<p>You saw an example config file in the <a class="reference internal" href="#config-files">Config Files</a> section. Here is a fuller
+specification of the config files used and created by ConfigObj.</p>
+<p>The basic pattern for keywords is:</p>
+<pre class="literal-block">
+# comment line
+# comment line
+keyword = value # inline comment
+</pre>
+<p>Both keyword and value can optionally be surrounded in quotes. The equals sign
+is the only valid divider.</p>
+<p>Values can have comments on the lines above them, and an inline comment after
+them. This, of course, is optional. See the <a class="reference internal" href="#comments">comments</a> section for details.</p>
+<p>If a keyword or value starts or ends with whitespace, or contains a quote mark
+or comma, then it should be surrounded by quotes. Quotes are not necessary if
+whitespace is surrounded by non-whitespace.</p>
+<p>Values can also be lists. Lists are comma separated. You indicate a single
+member list by a trailing comma. An empty list is shown by a single comma:</p>
+<pre class="literal-block">
+keyword1 = value1, value2, value3
+keyword2 = value1, # a single member list
+keyword3 = , # an empty list
+</pre>
+<p>Values that contain line breaks (multi-line values) can be surrounded by triple
+quotes. These can also be used if a value contains both types of quotes. List
+members cannot be surrounded by triple quotes:</p>
+<pre class="literal-block">
+keyword1 = ''' A multi line value
+on several
+lines''' # with a comment
+keyword2 = '''I won't be &quot;afraid&quot;.'''
+#
+keyword3 = &quot;&quot;&quot; A multi line value
+on several
+lines&quot;&quot;&quot; # with a comment
+keyword4 = &quot;&quot;&quot;I won't be &quot;afraid&quot;.&quot;&quot;&quot;
+</pre>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">There is no way of safely quoting values that contain both types of triple
+quotes.</p>
+</div>
+<p>A line that starts with a '#', possibly preceded by whitespace, is a comment.</p>
+<p>New sections are indicated by a section marker line. That is the section name
+in square brackets. Whitespace around the section name is ignored. The name can
+be quoted with single or double quotes. The marker can have comments before it
+and an inline comment after it:</p>
+<pre class="literal-block">
+# The First Section
+[ section name 1 ] # first section
+keyword1 = value1
+
+# The Second Section
+[ &quot;section name 2&quot; ] # second section
+keyword2 = value2
+</pre>
+<p>Any subsections (sections that are <em>inside</em> the current section) are
+designated by repeating the square brackets before and after the section name.
+The number of square brackets represents the nesting level of the sub-section.
+Square brackets may be separated by whitespace; such whitespace, however, will
+not be present in the output config written by the <tt class="docutils literal">write</tt> method.</p>
+<p>Indentation is not significant, but can be preserved. See the description of
+the <tt class="docutils literal">indent_type</tt> option, in the <a class="reference internal" href="#configobj-specifications">ConfigObj specifications</a> chapter, for the
+details.</p>
+<p>A <em>NestingError</em> will be raised if the number of the opening and the closing
+brackets in a section marker is not the same, or if a sub-section's nesting
+level is greater than the nesting level of it parent plus one.</p>
+<p>In the outer section, single values can only appear before any sub-section.
+Otherwise they will belong to the sub-section immediately before them:</p>
+<pre class="literal-block">
+# initial comment
+keyword1 = value1
+keyword2 = value2
+
+[section 1]
+keyword1 = value1
+keyword2 = value2
+
+ [[sub-section]]
+ # this is in section 1
+ keyword1 = value1
+ keyword2 = value2
+
+ [[[nested section]]]
+ # this is in sub section
+ keyword1 = value1
+ keyword2 = value2
+
+ [[sub-section2]]
+ # this is in section 1 again
+ keyword1 = value1
+ keyword2 = value2
+
+[[sub-section3]]
+# this is also in section 1, indentation is misleading here
+keyword1 = value1
+keyword2 = value2
+
+# final comment
+</pre>
+<p>When parsed, the above config file produces the following data structure:</p>
+<div class="highlight"><pre><span class="n">ConfigObj</span><span class="p">({</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="s">&#39;section 1&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="s">&#39;sub-section&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="s">&#39;nested section&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="p">},</span>
+ <span class="p">},</span>
+ <span class="s">&#39;sub-section2&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="p">},</span>
+ <span class="s">&#39;sub-section3&#39;</span><span class="p">:</span> <span class="p">{</span>
+ <span class="s">&#39;keyword1&#39;</span><span class="p">:</span> <span class="s">&#39;value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;keyword2&#39;</span><span class="p">:</span> <span class="s">&#39;value2&#39;</span><span class="p">,</span>
+ <span class="p">},</span>
+ <span class="p">},</span>
+<span class="p">})</span>
+</pre></div>
+<p>Sections are ordered: note how the structure of the resulting ConfigObj is in
+the same order as the original file.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>In ConfigObj 4.3.0 <em>empty values</em> became valid syntax. They are read as the
+empty string. There is also an option/attribute (<tt class="docutils literal">write_empty_values</tt>) to
+allow the writing of these.</p>
+<p>This is mainly to support 'legacy' config files, written from other
+applications. This is documented under <a class="reference internal" href="#empty-values">Empty Values</a>.</p>
+<p class="last"><a class="reference internal" href="#unrepr-mode">unrepr mode</a> introduces <em>another</em> syntax variation, used for storing
+basic Python datatypes in config files.</p>
+</div>
+</div>
+<div class="section" id="sections">
+<h1><a class="toc-backref" href="#id61">7&nbsp;&nbsp;&nbsp;Sections</a></h1>
+<p>Every section in a ConfigObj has certain properties. The ConfigObj itself also
+has these properties, because it too is a section (sometimes called the <em>root
+section</em>).</p>
+<p><tt class="docutils literal">Section</tt> is a subclass of the standard new-class dictionary, therefore it
+has <strong>all</strong> the methods of a normal dictionary. This means you can <tt class="docutils literal">update</tt>
+and <tt class="docutils literal">clear</tt> sections.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>You create a new section by assigning a member to be a dictionary.</p>
+<p>The new <tt class="docutils literal">Section</tt> is created <em>from</em> the dictionary, but isn't the same
+thing as the dictionary. (So references to the dictionary you use to create
+the section <em>aren't</em> references to the new section).</p>
+<p>Note the following.</p>
+<div class="highlight"><pre><span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">()</span>
+<span class="n">vals</span> <span class="o">=</span> <span class="p">{</span><span class="s">&#39;key1&#39;</span><span class="p">:</span> <span class="s">&#39;value 1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;key2&#39;</span><span class="p">:</span> <span class="s">&#39;value 2&#39;</span>
+ <span class="p">}</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;vals&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">vals</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;vals&#39;</span><span class="p">]</span> <span class="o">==</span> <span class="n">vals</span>
+<span class="bp">True</span>
+<span class="n">config</span><span class="p">[</span><span class="s">&#39;vals&#39;</span><span class="p">]</span> <span class="ow">is</span> <span class="n">vals</span>
+<span class="bp">False</span>
+</pre></div>
+<p class="last">If you now change <tt class="docutils literal">vals</tt>, the changes won't be reflected in <tt class="docutils literal"><span class="pre">config['vals']</span></tt>.</p>
+</div>
+<p>A section is ordered, following its <tt class="docutils literal">scalars</tt> and <tt class="docutils literal">sections</tt>
+attributes documented below. This means that the following dictionary
+attributes return their results in order.</p>
+<ul>
+<li><p class="first">'__iter__'</p>
+<blockquote>
+<p>More commonly known as <tt class="docutils literal">for member in section:</tt>.</p>
+</blockquote>
+</li>
+<li><p class="first">'__repr__' and '__str__'</p>
+<blockquote>
+<p>Any time you print or display the ConfigObj.</p>
+</blockquote>
+</li>
+<li><p class="first">'items'</p>
+</li>
+<li><p class="first">'iteritems'</p>
+</li>
+<li><p class="first">'iterkeys'</p>
+</li>
+<li><p class="first">'itervalues'</p>
+</li>
+<li><p class="first">'keys'</p>
+</li>
+<li><p class="first">'popitem'</p>
+</li>
+<li><p class="first">'values'</p>
+</li>
+</ul>
+<div class="section" id="section-attributes">
+<h2><a class="toc-backref" href="#id62">7.1&nbsp;&nbsp;&nbsp;Section Attributes</a></h2>
+<ul>
+<li><p class="first">main</p>
+<blockquote>
+<p>A reference to the main ConfigObj.</p>
+</blockquote>
+</li>
+<li><p class="first">parent</p>
+<blockquote>
+<p>A reference to the 'parent' section, the section that this section is a
+member of.</p>
+<p>On the ConfigObj this attribute is a reference to itself. You can use this
+to walk up the sections, stopping when <tt class="docutils literal">section.parent is section</tt>.</p>
+</blockquote>
+</li>
+<li><p class="first">depth</p>
+<blockquote>
+<p>The nesting level of the current section.</p>
+<p>If you create a new ConfigObj and add sections, 1 will be added to the
+depth level between sections.</p>
+</blockquote>
+</li>
+<li><p class="first">defaults</p>
+<blockquote>
+<p>This attribute is a list of scalars that came from default values. Values
+that came from defaults aren't written out by the <tt class="docutils literal">write</tt> method.
+Setting any of these values in the section removes them from the defaults
+list.</p>
+</blockquote>
+</li>
+<li><p class="first">default_values</p>
+<blockquote>
+<p>This attribute is a dictionary mapping keys to the default values for the
+keys. By default it is an empty dictionary and is populated when you
+validate the ConfigObj.</p>
+</blockquote>
+</li>
+<li><p class="first">scalars, sections</p>
+<blockquote>
+<p>These attributes are normal lists, representing the order that members,
+single values and subsections appear in the section. The order will either
+be the order of the original config file, <em>or</em> the order that you added
+members.</p>
+<p>The order of members in this lists is the order that <tt class="docutils literal">write</tt> creates in
+the config file. The <tt class="docutils literal">scalars</tt> list is output before the <tt class="docutils literal">sections</tt>
+list.</p>
+<p>Adding or removing members also alters these lists. You can manipulate the
+lists directly to alter the order of members.</p>
+<div class="warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">If you alter the <tt class="docutils literal">scalars</tt>, <tt class="docutils literal">sections</tt>, or <tt class="docutils literal">defaults</tt> attributes
+so that they no longer reflect the contents of the section, you will
+break your ConfigObj.</p>
+</div>
+<p>See also the <tt class="docutils literal">rename</tt> method.</p>
+</blockquote>
+</li>
+<li><p class="first">comments</p>
+<blockquote>
+<p>This is a dictionary of comments associated with each member. Each entry is
+a list of lines. These lines are written out before the member.</p>
+</blockquote>
+</li>
+<li><p class="first">inline_comments</p>
+<blockquote>
+<p>This is <em>another</em> dictionary of comments associated with each member. Each
+entry is a string that is put inline with the member.</p>
+</blockquote>
+</li>
+<li><p class="first">configspec</p>
+<blockquote>
+<p>The configspec attribute is a dictionary mapping scalars to <em>checks</em>. A
+check defines the expected type and possibly the allowed values for a
+member.</p>
+<p>The configspec has the same format as a config file, but instead of values
+it has a specification for the value (which may include a default value).
+The <a class="reference internal" href="#validate">validate</a> method uses it to check the config file makes sense. If a
+configspec is passed in when the ConfigObj is created, then it is parsed
+and broken up to become the <tt class="docutils literal">configspec</tt> attribute of each section.</p>
+<p>If you didn't pass in a configspec, this attribute will be <tt class="docutils literal">None</tt> on the
+root section (the main ConfigObj).</p>
+<p>You can set the configspec attribute directly on a section.</p>
+<p>See the <a class="reference internal" href="#validation">validation</a> section for full details of how to write configspecs.</p>
+</blockquote>
+</li>
+<li><p class="first">extra_values</p>
+<blockquote>
+<p>By default an empty list. After <a class="reference internal" href="#validation">validation</a> this is populated with any members
+of the section that don't appear in the configspec (i.e. they are additional
+values). Rather than accessing this directly it may be more convenient to get
+all the extra values in a config file using the <a class="reference internal" href="#get-extra-values">get_extra_values</a> function.</p>
+<p>New in ConfigObj 4.7.0.</p>
+</blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="section-methods">
+<h2><a class="toc-backref" href="#id63">7.2&nbsp;&nbsp;&nbsp;Section Methods</a></h2>
+<ul>
+<li><p class="first"><strong>dict</strong></p>
+<blockquote>
+<p>This method takes no arguments. It returns a deep copy of the section as a
+dictionary. All subsections will also be dictionaries, and list values will
+be copies, rather than references to the original <a class="footnote-reference" href="#id24" id="id10">[10]</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>rename</strong></p>
+<blockquote>
+<p><tt class="docutils literal">rename(oldkey, newkey)</tt></p>
+<p>This method renames a key, without affecting its position in the sequence.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>merge</strong></p>
+<blockquote>
+<p><tt class="docutils literal">merge(indict)</tt></p>
+<p>This method is a <em>recursive update</em> method. It allows you to merge two
+config files together.</p>
+<p>You would typically use this to create a default ConfigObj and then merge
+in user settings. This way users only need to specify values that are
+different from the default.</p>
+<p>For example :</p>
+<div class="highlight"><pre><span class="c"># def_cfg contains your default config settings</span>
+<span class="c"># user_cfg contains the user settings</span>
+<span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">def_cfg</span><span class="p">)</span>
+<span class="n">usr</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">user_cfg</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="n">cfg</span><span class="o">.</span><span class="n">merge</span><span class="p">(</span><span class="n">usr</span><span class="p">)</span>
+
+<span class="sd">&quot;&quot;&quot;</span>
+<span class="sd">cfg now contains a combination of the default settings and the user</span>
+<span class="sd">settings.</span>
+
+<span class="sd">The user settings will have overwritten any of the default ones.</span>
+<span class="sd">&quot;&quot;&quot;</span>
+</pre></div>
+</blockquote>
+</li>
+<li><p class="first"><strong>walk</strong></p>
+<blockquote>
+<p>This method can be used to transform values and names. See <a class="reference internal" href="#walking-a-section">walking a
+section</a> for examples and explanation.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>as_bool</strong></p>
+<blockquote>
+<p><tt class="docutils literal">as_bool(key)</tt></p>
+<p>Returns <tt class="docutils literal">True</tt> if the key contains a string that represents <tt class="docutils literal">True</tt>, or
+is the <tt class="docutils literal">True</tt> object.</p>
+<p>Returns <tt class="docutils literal">False</tt> if the key contains a string that represents <tt class="docutils literal">False</tt>,
+or is the <tt class="docutils literal">False</tt> object.</p>
+<p>Raises a <tt class="docutils literal">ValueError</tt> if the key contains anything else.</p>
+<p>Strings that represent <tt class="docutils literal">True</tt> are (not case sensitive):</p>
+<pre class="literal-block">
+true, yes, on, 1
+</pre>
+<p>Strings that represent <tt class="docutils literal">False</tt> are:</p>
+<pre class="literal-block">
+false, no, off, 0
+</pre>
+</blockquote>
+</li>
+<li><p class="first"><strong>as_int</strong></p>
+<blockquote>
+<p><tt class="docutils literal">as_int(key)</tt></p>
+<p>This returns the value contained in the specified key as an integer.</p>
+<p>It raises a <tt class="docutils literal">ValueError</tt> if the conversion can't be done.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>as_float</strong></p>
+<blockquote>
+<p><tt class="docutils literal">as_float(key)</tt></p>
+<p>This returns the value contained in the specified key as a float.</p>
+<p>It raises a <tt class="docutils literal">ValueError</tt> if the conversion can't be done.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>as_list</strong></p>
+<blockquote>
+<p><tt class="docutils literal">as_list(key)</tt></p>
+<p>This returns the value contained in the specified key as a list.</p>
+<p>If it isn't a list it will be wrapped as a list so that you can
+guarantee the returned value will be a list.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>restore_default</strong></p>
+<blockquote>
+<p><tt class="docutils literal">restore_default(key)</tt></p>
+<p>Restore (and return) the default value for the specified key.</p>
+<p>This method will only work for a ConfigObj that was created
+with a configspec and has been validated.</p>
+<p>If there is no default value for this key, <tt class="docutils literal">KeyError</tt> is raised.</p>
+</blockquote>
+</li>
+<li><p class="first"><strong>restore_defaults</strong></p>
+<blockquote>
+<p><tt class="docutils literal">restore_defaults()</tt></p>
+<p>Recursively restore default values to all members
+that have them.</p>
+<p>This method will only work for a ConfigObj that was created
+with a configspec and has been validated.</p>
+<p>It doesn't delete or modify entries without default values.</p>
+</blockquote>
+</li>
+</ul>
+</div>
+<div class="section" id="walking-a-section">
+<h2><a class="toc-backref" href="#id64">7.3&nbsp;&nbsp;&nbsp;Walking a Section</a></h2>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">The walk method allows you to call a function on every member/name.</p>
+</div>
+<div class="highlight"><pre><span class="n">walk</span><span class="p">(</span><span class="n">function</span><span class="p">,</span> <span class="n">raise_errors</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span>
+ <span class="n">call_on_sections</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="o">**</span><span class="n">keywargs</span><span class="p">)</span>
+</pre></div>
+<p><tt class="docutils literal">walk</tt> is a method of the <tt class="docutils literal">Section</tt> object. This means it is also a method
+of ConfigObj.</p>
+<p>It walks through every member and calls a function on the keyword and value. It
+walks recursively through subsections.</p>
+<p>It returns a dictionary of all the computed values.</p>
+<p>If the function raises an exception, the default is to propagate the error, and
+stop. If <tt class="docutils literal">raise_errors=False</tt> then it sets the return value for that keyword
+to <tt class="docutils literal">False</tt> instead, and continues. This is similar to the way <a class="reference internal" href="#validation">validation</a>
+works.</p>
+<p>Your function receives the arguments <tt class="docutils literal">(section, key)</tt>. The current value is
+then <tt class="docutils literal">section[key]</tt> <a class="footnote-reference" href="#id25" id="id11">[11]</a>. Any unrecognised keyword arguments you pass to
+walk, are passed on to the function.</p>
+<p>Normally <tt class="docutils literal">walk</tt> just recurses into subsections. If you are transforming (or
+checking) names as well as values, then you want to be able to change the names
+of sections. In this case set <tt class="docutils literal">call_on_sections</tt> to <tt class="docutils literal">True</tt>. Now, on
+encountering a sub-section, <em>first</em> the function is called for the <em>whole</em>
+sub-section, and <em>then</em> it recurses into it's members. This means your function
+must be able to handle receiving dictionaries as well as strings and lists.</p>
+<p>If you are using the return value from <tt class="docutils literal">walk</tt> <em>and</em> <tt class="docutils literal">call_on_sections</tt>,
+note that walk discards the return value when it calls your function.</p>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">You can use <tt class="docutils literal">walk</tt> to transform the names of members of a section
+but you mustn't add or delete members.</p>
+</div>
+</div>
+<div class="section" id="examples">
+<h2><a class="toc-backref" href="#id65">7.4&nbsp;&nbsp;&nbsp;Examples</a></h2>
+<p>You can use this for transforming all values in your ConfigObj. For example
+you might like the nested lists from ConfigObj 3. This was provided by the
+<a class="reference external" href="http://www.voidspace.org.uk/python/modules.shtml#listquote">listquote</a> module. You could switch off the parsing for list values
+(<tt class="docutils literal">list_values=False</tt>) and use listquote to parse every value.</p>
+<p>Another thing you might want to do is use the Python escape codes in your
+values. You might be <em>used</em> to using <tt class="docutils literal">\n</tt> for line feed and <tt class="docutils literal">\t</tt> for tab.
+Obviously we'd need to decode strings that come from the config file (using the
+escape codes). Before writing out we'll need to put the escape codes back in
+encode.</p>
+<p>As an example we'll write a function to use with walk, that encodes or decodes
+values using the <tt class="docutils literal"><span class="pre">string-escape</span></tt> codec.</p>
+<p>The function has to take each value and set the new value. As a bonus we'll
+create one function that will do decode <em>or</em> encode depending on a keyword
+argument.</p>
+<p>We don't want to work with section names, we're only transforming values, so
+we can leave <tt class="docutils literal">call_on_sections</tt> as <tt class="docutils literal">False</tt>. This means the two datatypes we
+have to handle are strings and lists, we can ignore everything else. (We'll
+treat tuples as lists as well).</p>
+<p>We're not using the return values, so it doesn't need to return anything, just
+change the values if appropriate.</p>
+<div class="highlight"><pre><span class="k">def</span> <span class="nf">string_escape</span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">encode</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
+ <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd"> A function to encode or decode using the &#39;string-escape&#39; codec.</span>
+<span class="sd"> To be passed to the walk method of a ConfigObj.</span>
+<span class="sd"> By default it decodes.</span>
+<span class="sd"> To encode, pass in the keyword argument ``encode=True``.</span>
+<span class="sd"> &quot;&quot;&quot;</span>
+ <span class="n">val</span> <span class="o">=</span> <span class="n">section</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
+ <span class="c"># is it a type we can work with</span>
+ <span class="c"># NOTE: for platforms where Python &gt; 2.2</span>
+ <span class="c"># you can use basestring instead of (str, unicode)</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">val</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">,</span> <span class="nb">list</span><span class="p">,</span> <span class="nb">tuple</span><span class="p">)):</span>
+ <span class="c"># no !</span>
+ <span class="k">return</span>
+ <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">val</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">)):</span>
+ <span class="c"># it&#39;s a string !</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="n">encode</span><span class="p">:</span>
+ <span class="n">section</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;string-escape&#39;</span><span class="p">)</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">section</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;string-escape&#39;</span><span class="p">)</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="c"># it must be a list or tuple!</span>
+ <span class="c"># we&#39;ll be lazy and create a new list</span>
+ <span class="n">newval</span> <span class="o">=</span> <span class="p">[]</span>
+ <span class="c"># we&#39;ll check every member of the list</span>
+ <span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">val</span><span class="p">:</span>
+ <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">)):</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="n">encode</span><span class="p">:</span>
+ <span class="n">newval</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">entry</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">&#39;string-escape&#39;</span><span class="p">))</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">newval</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">entry</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">&#39;string-escape&#39;</span><span class="p">))</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">newval</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">entry</span><span class="p">)</span>
+ <span class="c"># done !</span>
+ <span class="n">section</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">newval</span>
+
+<span class="c"># assume we have a ConfigObj called ``config``</span>
+<span class="c">#</span>
+<span class="c"># To decode</span>
+<span class="n">config</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">string_escape</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="c"># To encode.</span>
+<span class="c"># Because ``walk`` doesn&#39;t recognise the ``encode`` argument</span>
+<span class="c"># it passes it to our function.</span>
+<span class="n">config</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">string_escape</span><span class="p">,</span> <span class="n">encode</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+</pre></div>
+<p>Here's a simple example of using <tt class="docutils literal">walk</tt> to transform names and values. One
+usecase of this would be to create a <em>standard</em> config file with placeholders
+for section and keynames. You can then use walk to create new config files
+and change values and member names :</p>
+<div class="highlight"><pre><span class="c"># We use &#39;XXXX&#39; as a placeholder</span>
+<span class="n">config</span> <span class="o">=</span> <span class="s">&#39;&#39;&#39;</span>
+<span class="s">XXXXkey1 = XXXXvalue1</span>
+<span class="s">XXXXkey2 = XXXXvalue2</span>
+<span class="s">XXXXkey3 = XXXXvalue3</span>
+<span class="s">[XXXXsection1]</span>
+<span class="s">XXXXkey1 = XXXXvalue1</span>
+<span class="s">XXXXkey2 = XXXXvalue2</span>
+<span class="s">XXXXkey3 = XXXXvalue3</span>
+<span class="s">[XXXXsection2]</span>
+<span class="s">XXXXkey1 = XXXXvalue1</span>
+<span class="s">XXXXkey2 = XXXXvalue2</span>
+<span class="s">XXXXkey3 = XXXXvalue3</span>
+<span class="s"> [[XXXXsection1]]</span>
+<span class="s"> XXXXkey1 = XXXXvalue1</span>
+<span class="s"> XXXXkey2 = XXXXvalue2</span>
+<span class="s"> XXXXkey3 = XXXXvalue3</span>
+<span class="s">&#39;&#39;&#39;</span><span class="o">.</span><span class="n">splitlines</span><span class="p">()</span>
+<span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="k">def</span> <span class="nf">transform</span><span class="p">(</span><span class="n">section</span><span class="p">,</span> <span class="n">key</span><span class="p">):</span>
+ <span class="n">val</span> <span class="o">=</span> <span class="n">section</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
+ <span class="n">newkey</span> <span class="o">=</span> <span class="n">key</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&#39;XXXX&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1&#39;</span><span class="p">)</span>
+ <span class="n">section</span><span class="o">.</span><span class="n">rename</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">newkey</span><span class="p">)</span>
+ <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">val</span><span class="p">,</span> <span class="p">(</span><span class="nb">tuple</span><span class="p">,</span> <span class="nb">list</span><span class="p">,</span> <span class="nb">dict</span><span class="p">)):</span>
+ <span class="k">pass</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">val</span> <span class="o">=</span> <span class="n">val</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s">&#39;XXXX&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1&#39;</span><span class="p">)</span>
+ <span class="n">section</span><span class="p">[</span><span class="n">newkey</span><span class="p">]</span> <span class="o">=</span> <span class="n">val</span>
+<span class="c">#</span>
+<span class="n">cfg</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">transform</span><span class="p">,</span> <span class="n">call_on_sections</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="k">print</span> <span class="n">cfg</span>
+<span class="n">ConfigObj</span><span class="p">({</span><span class="s">&#39;CLIENT1key1&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value1&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1key2&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value2&#39;</span><span class="p">,</span>
+<span class="s">&#39;CLIENT1key3&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value3&#39;</span><span class="p">,</span>
+<span class="s">&#39;CLIENT1section1&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s">&#39;CLIENT1key1&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;CLIENT1key2&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value2&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1key3&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value3&#39;</span><span class="p">},</span>
+<span class="s">&#39;CLIENT1section2&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s">&#39;CLIENT1key1&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;CLIENT1key2&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value2&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1key3&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value3&#39;</span><span class="p">,</span>
+ <span class="s">&#39;CLIENT1section1&#39;</span><span class="p">:</span> <span class="p">{</span><span class="s">&#39;CLIENT1key1&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value1&#39;</span><span class="p">,</span>
+ <span class="s">&#39;CLIENT1key2&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value2&#39;</span><span class="p">,</span> <span class="s">&#39;CLIENT1key3&#39;</span><span class="p">:</span> <span class="s">&#39;CLIENT1value3&#39;</span><span class="p">}}})</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="exceptions">
+<h1><a class="toc-backref" href="#id66">8&nbsp;&nbsp;&nbsp;Exceptions</a></h1>
+<p>There are several places where ConfigObj may raise exceptions (other than
+because of bugs).</p>
+<ol class="arabic">
+<li><dl class="first docutils">
+<dt>If a configspec filename you pass in doesn't exist, or a config file</dt>
+<dd><p class="first last">filename doesn't exist <em>and</em> <tt class="docutils literal">file_error=True</tt>, an <tt class="docutils literal">IOError</tt> will be
+raised.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>If you try to set a non-string key, or a non string value when</dt>
+<dd><p class="first last"><tt class="docutils literal">stringify=False</tt>, a <tt class="docutils literal">TypeError</tt> will be raised.</p>
+</dd>
+</dl>
+</li>
+<li><p class="first">A badly built config file will cause parsing errors.</p>
+</li>
+<li><p class="first">A parsing error can also occur when reading a configspec.</p>
+</li>
+<li><dl class="first docutils">
+<dt>In string interpolation you can specify a value that doesn't exist, or</dt>
+<dd><p class="first last">create circular references (recursion).</p>
+</dd>
+</dl>
+</li>
+</ol>
+<p>Number 5 (which is actually two different types of exceptions) is documented
+in <a class="reference internal" href="#string-interpolation">String Interpolation</a>.</p>
+<p><em>This</em> section is about errors raised during parsing.</p>
+<p>The base error class is <tt class="docutils literal">ConfigObjError</tt>. This is a subclass of
+<tt class="docutils literal">SyntaxError</tt>, so you can trap for <tt class="docutils literal">SyntaxError</tt> without needing to
+directly import any of the ConfigObj exceptions.</p>
+<p>The following other exceptions are defined (all deriving from
+<tt class="docutils literal">ConfigObjError</tt>) :</p>
+<ul>
+<li><p class="first"><tt class="docutils literal">NestingError</tt></p>
+<blockquote>
+<p>This error indicates either a mismatch in the brackets in a section marker,
+or an excessive level of nesting.</p>
+</blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal">ParseError</tt></p>
+<blockquote>
+<p>This error indicates that a line is badly written. It is neither a valid
+<tt class="docutils literal">key = value</tt> line, nor a valid section marker line, nor a comment line.</p>
+</blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal">DuplicateError</tt></p>
+<blockquote>
+<p>The keyword or section specified already exists.</p>
+</blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal">ConfigspecError</tt></p>
+<blockquote>
+<p>An error occurred whilst parsing a configspec.</p>
+</blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal">UnreprError</tt></p>
+<blockquote>
+<p>An error occurred when parsing a value in <a class="reference internal" href="#unrepr-mode">unrepr mode</a>.</p>
+</blockquote>
+</li>
+<li><p class="first"><tt class="docutils literal">ReloadError</tt></p>
+<blockquote>
+<p><tt class="docutils literal">reload</tt> was called on a ConfigObj instance that doesn't have a valid
+filename attribute.</p>
+</blockquote>
+</li>
+</ul>
+<p>When parsing a configspec, ConfigObj will stop on the first error it
+encounters. It will raise a <tt class="docutils literal">ConfigspecError</tt>. This will have an <tt class="docutils literal">error</tt>
+attribute, which is the actual error that was raised.</p>
+<p>Behaviour when parsing a config file depends on the option <tt class="docutils literal">raise_errors</tt>.
+If ConfigObj encounters an error while parsing a config file:</p>
+<blockquote>
+<p>If <tt class="docutils literal">raise_errors=True</tt> then ConfigObj will raise the appropriate error
+and parsing will stop.</p>
+<p>If <tt class="docutils literal">raise_errors=False</tt> (the default) then parsing will continue to the
+end and <em>all</em> errors will be collected.</p>
+</blockquote>
+<p>If <tt class="docutils literal">raise_errors</tt> is False and multiple errors are found a <tt class="docutils literal">ConfigObjError</tt>
+is raised. The error raised has a <tt class="docutils literal">config</tt> attribute, which is the parts of
+the ConfigObj that parsed successfully. It also has an attribute <tt class="docutils literal">errors</tt>,
+which is a list of <em>all</em> the errors raised. Each entry in the list is an
+instance of the appropriate error type. Each one has the following attributes
+(useful for delivering a sensible error message to your user) :</p>
+<ul class="simple">
+<li><tt class="docutils literal">line</tt>: the original line that caused the error.</li>
+<li><tt class="docutils literal">line_number</tt>: its number in the config file.</li>
+<li><tt class="docutils literal">message</tt>: the error message that accompanied the error.</li>
+</ul>
+<p>If only one error is found, then that error is re-raised. The error still has
+the <tt class="docutils literal">config</tt> and <tt class="docutils literal">errors</tt> attributes. This means that your error handling
+code can be the same whether one error is raised in parsing , or several.</p>
+<p>It also means that in the most common case (a single error) a useful error
+message will be raised.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">One wrongly written line could break the basic structure of your config
+file. This could cause every line after it to flag an error, so having a
+list of all the lines that caused errors may not be as useful as it sounds.</p>
+</div>
+</div>
+<div class="section" id="validation">
+<h1><a class="toc-backref" href="#id67">9&nbsp;&nbsp;&nbsp;Validation</a></h1>
+<div class="hint">
+<p class="first admonition-title">Hint</p>
+<p>The system of configspecs can seem confusing at first, but is actually
+quite simple and powerful. The best reference is my article on ConfigObj:</p>
+<ul class="last simple">
+<li><a class="reference external" href="http://www.voidspace.org.uk/python/articles/configobj.shtml">An Introduction to ConfigObj</a></li>
+</ul>
+</div>
+<p>Validation is done through a combination of the <a class="reference internal" href="#configspec">configspec</a> and a <tt class="docutils literal">Validator</tt>
+object. For this you need <em>validate.py</em> <a class="footnote-reference" href="#id26" id="id12">[12]</a>. See <a class="reference internal" href="#downloading">downloading</a> if you don't
+have a copy.</p>
+<p>Validation can perform two different operations :</p>
+<ol class="arabic">
+<li><dl class="first docutils">
+<dt>Check that a value meets a specification. For example, check that a value</dt>
+<dd><p class="first last">is an integer between one and six, or is a choice from a specific set of
+options.</p>
+</dd>
+</dl>
+</li>
+<li><dl class="first docutils">
+<dt>It can convert the value into the type required. For example, if one of</dt>
+<dd><p class="first last">your values is a port number, validation will turn it into an integer for
+you.</p>
+</dd>
+</dl>
+</li>
+</ol>
+<p>So validation can act as a transparent layer between the datatypes of your
+application configuration (boolean, integers, floats, etc) and the text format
+of your config file.</p>
+<div class="section" id="configspec">
+<h2><a class="toc-backref" href="#id68">9.1&nbsp;&nbsp;&nbsp;configspec</a></h2>
+<p>The <tt class="docutils literal">validate</tt> method checks members against an entry in the configspec. Your
+configspec therefore resembles your config file, with a check for every member.</p>
+<p>In order to perform validation you need a <tt class="docutils literal">Validator</tt> object. This has
+several useful built-in check functions. You can also create your own custom
+functions and register them with your Validator object.</p>
+<p>Each check is the name of one of these functions, including any parameters and
+keyword arguments. The configspecs look like function calls, and they map to
+function calls.</p>
+<p>The basic datatypes that an un-extended Validator can test for are :</p>
+<ul class="simple">
+<li>boolean values (True and False)</li>
+<li>integers (including minimum and maximum values)</li>
+<li>floats (including min and max)</li>
+<li>strings (including min and max length)</li>
+<li>IP addresses (v4 only)</li>
+</ul>
+<p>It can also handle lists of these types and restrict a value to being one from
+a set of options.</p>
+<p>An example configspec is going to look something like:</p>
+<pre class="literal-block">
+port = integer(0, 100)
+user = string(max=25)
+mode = option('quiet', 'loud', 'silent')
+</pre>
+<p>You can specify default values, and also have the same configspec applied to
+several sections. This is called <a class="reference internal" href="#repeated-sections">repeated sections</a>.</p>
+<p>For full details on writing configspecs, please refer to the <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">validate.py
+documentation</a>.</p>
+<div class="important">
+<p class="first admonition-title">Important</p>
+<p>Your configspec is read by ConfigObj in the same way as a config file.</p>
+<p>That means you can do interpolation <em>within</em> your configspec.</p>
+<p>In order to allow this, checks in the 'DEFAULT' section (of the root level
+of your configspec) are <em>not</em> used.</p>
+<p>If you want to use a configspec <em>without</em> interpolation being done in it
+you can create your configspec manually and switch off interpolation:</p>
+<div class="last"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+
+<span class="n">configspec</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">spec_filename</span><span class="p">,</span> <span class="n">interpolation</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">list_values</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
+ <span class="n">_inspec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="n">conf</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">config_filename</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">configspec</span><span class="p">)</span>
+</pre></div>
+</div></div>
+<p>If you need to specify the encoding of your configspec, then you can pass in a
+ConfigObj instance as your configspec. When you read your configspec file, you
+<em>must</em> specify <tt class="docutils literal">list_values=False</tt>. If you need to support hashes in
+configspec values then you must also pass in <tt class="docutils literal">_inspec=True</tt>.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">configspec</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">configspecfilename</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s">&#39;UTF8&#39;</span><span class="p">,</span>
+ <span class="n">list_values</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">_inspec</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">configspec</span><span class="p">)</span>
+</pre></div>
+</div>
+<div class="section" id="type-conversion">
+<h2><a class="toc-backref" href="#id69">9.2&nbsp;&nbsp;&nbsp;Type Conversion</a></h2>
+<p>By default, validation does type conversion. This means that if you specify
+<tt class="docutils literal">integer</tt> as the check, then calling <a class="reference internal" href="#validate">validate</a> will actually change the value
+to an integer (so long as the check succeeds).</p>
+<p>It also means that when you call the <a class="reference internal" href="#write">write</a> method, the value will be converted
+back into a string using the <tt class="docutils literal">str</tt> function.</p>
+<p>To switch this off, and leave values as strings after validation, you need to
+set the <a class="reference internal" href="#stringify">stringify</a> attribute to <tt class="docutils literal">False</tt>. If this is the case, attempting to
+set a value to a non-string will raise an error.</p>
+</div>
+<div class="section" id="default-values">
+<h2><a class="toc-backref" href="#id70">9.3&nbsp;&nbsp;&nbsp;Default Values</a></h2>
+<p>You can set a default value in your check. If the value is missing from the
+config file then this value will be used instead. This means that your user
+only has to supply values that differ from the defaults.</p>
+<p>If you <em>don't</em> supply a default then for a value to be missing is an error,
+and this will show in the <a class="reference internal" href="#return-value">return value</a> from validate.</p>
+<p>Additionally you can set the default to be <tt class="docutils literal">None</tt>. This means the value will
+be set to <tt class="docutils literal">None</tt> (the object) <em>whichever check is used</em>. (It will be set to
+<tt class="docutils literal">''</tt> rather than <tt class="docutils literal">None</tt> if <a class="reference internal" href="#stringify">stringify</a> is <tt class="docutils literal">False</tt>). You can use this
+to easily implement optional values in your config files.</p>
+<pre class="literal-block">
+port = integer(0, 100, default=80)
+user = string(max=25, default=0)
+mode = option('quiet', 'loud', 'silent', default='loud')
+nick = string(default=None)
+</pre>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p>Because the default goes through type conversion, it also has to pass the
+check.</p>
+<p class="last">Note that <tt class="docutils literal">default=None</tt> is case sensitive.</p>
+</div>
+<div class="section" id="id13">
+<h3><a class="toc-backref" href="#id71">9.3.1&nbsp;&nbsp;&nbsp;List Values</a></h3>
+<p>It's possible that you will want to specify a list as a default value. To avoid
+confusing syntax with commas and quotes you use a list constructor to specify
+that keyword arguments are lists. This includes the <tt class="docutils literal">default</tt> value. This
+makes checks look something like:</p>
+<pre class="literal-block">
+checkname(default=list('val1', 'val2', 'val3'))
+</pre>
+<p>This works with all keyword arguments, but is most useful for default values.</p>
+</div>
+</div>
+<div class="section" id="repeated-sections">
+<h2><a class="toc-backref" href="#id72">9.4&nbsp;&nbsp;&nbsp;Repeated Sections</a></h2>
+<p>Repeated sections are a way of specifying a configspec for a section that
+should be applied to all unspecified subsections in the same section.</p>
+<p>The easiest way of explaining this is to give an example. Suppose you have a
+config file that describes a dog. That dog has various attributes, but it can
+also have many fleas. You don't know in advance how many fleas there will be,
+or what they will be called, but you want each flea validated against the same
+configspec.</p>
+<p>We can define a section called <em>fleas</em>. We want every flea in that section
+(every sub-section) to have the same configspec applied to it. We do this by
+defining a single section called <tt class="docutils literal">__many__</tt>.</p>
+<pre class="literal-block">
+[dog]
+name = string(default=Rover)
+age = float(0, 99, default=0)
+
+ [[fleas]]
+
+ [[[__many__]]]
+ bloodsucker = boolean(default=True)
+ children = integer(default=10000)
+ size = option(small, tiny, micro, default=tiny)
+</pre>
+<p>Every flea on our dog will now be validated using the <tt class="docutils literal">__many__</tt> configspec.</p>
+<p><tt class="docutils literal">__many__</tt> sections can have sub-sections, including their own <tt class="docutils literal">__many__</tt>
+sub-sections. Defaults work in the normal way in repeated sections.</p>
+</div>
+<div class="section" id="repeated-values">
+<h2><a class="toc-backref" href="#id73">9.5&nbsp;&nbsp;&nbsp;Repeated Values</a></h2>
+<p>As well as using <tt class="docutils literal">__many__</tt> to validate unspecified sections you can use it to validate values. For
+example, to specify that all values in a section should be integers:</p>
+<pre class="literal-block">
+[section]
+ __many__ = integer
+</pre>
+<p>If you want to use repeated values alongside repeated sections you can call one <tt class="docutils literal">__many__</tt> and the
+other <tt class="docutils literal">___many___</tt> (with three underscores).</p>
+</div>
+<div class="section" id="copy-mode">
+<h2><a class="toc-backref" href="#id74">9.6&nbsp;&nbsp;&nbsp;Copy Mode</a></h2>
+<p>Because you can specify default values in your configspec, you can use
+ConfigObj to write out default config files for your application.</p>
+<p>However, normally values supplied from a default in a configspec are <em>not</em>
+written out by the <tt class="docutils literal">write</tt> method.</p>
+<p>To do this, you need to specify <tt class="docutils literal">copy=True</tt> when you call validate. As well
+as not marking values as default, all the comments in the configspec file
+will be copied into your ConfigObj instance.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="n">vdt</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">configspec</span><span class="o">=</span><span class="s">&#39;default.ini&#39;</span><span class="p">)</span>
+<span class="n">config</span><span class="o">.</span><span class="n">filename</span> <span class="o">=</span> <span class="s">&#39;new_default.ini&#39;</span>
+<span class="n">config</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">vdt</span><span class="p">,</span> <span class="n">copy</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">()</span>
+</pre></div>
+<p>If you need to support hashes in the configspec values then you must create
+it with <tt class="docutils literal">_inspec=True</tt>. This has the side effect of switching off the parsing
+of inline comments, meaning that they won't be copied into the new config file.
+(ConfigObj syntax is slightly different from configspec syntax and the parser
+can't support both inline comments and hashes in configspec values.)</p>
+</div>
+<div class="section" id="validation-and-interpolation">
+<h2><a class="toc-backref" href="#id75">9.7&nbsp;&nbsp;&nbsp;Validation and Interpolation</a></h2>
+<p>String interpolation and validation don't play well together. When validation
+changes type it sets the value. If the value uses interpolation, then the
+interpolation reference would normally be overwritten. Calling <tt class="docutils literal">write</tt> would
+then use the absolute value and the interpolation reference would be lost.</p>
+<p>As a compromise - if the value is unchanged by validation then it is not reset.
+This means strings that pass through validation unmodified will not be
+overwritten. If validation changes type - the value has to be overwritten, and
+any interpolation references are lost.</p>
+</div>
+<div class="section" id="extra-values">
+<h2><a class="toc-backref" href="#id76">9.8&nbsp;&nbsp;&nbsp;Extra Values</a></h2>
+<p>After validation the <tt class="docutils literal">extra_values</tt> member of every section that is listed in
+the configspec will be populated with the names of members that are in the
+config file but not in the configspec.</p>
+<p>If you are reporting configuration errors to your user this information can be
+useful, for example some missing entries may be due to misspelt entries that
+appear as extra values.</p>
+<p>See the <a class="reference internal" href="#get-extra-values">get_extra_values</a> function</p>
+<p>New in ConfigObj 4.7.0.</p>
+</div>
+<div class="section" id="simpleval">
+<h2><a class="toc-backref" href="#id77">9.9&nbsp;&nbsp;&nbsp;SimpleVal</a></h2>
+<p>You may not need a full validation process, but still want to check if all the
+expected values are present.</p>
+<p>Provided as part of the ConfigObj module is the <tt class="docutils literal">SimpleVal</tt> object. This has
+a dummy <tt class="docutils literal">test</tt> method that always passes.</p>
+<p>The only reason a test will fail is if the value is missing. The return value
+from <tt class="docutils literal">validate</tt> will either be <tt class="docutils literal">True</tt>, meaning all present, or a dictionary
+with <tt class="docutils literal">False</tt> for all missing values/sections.</p>
+<p>To use it, you still need to pass in a valid configspec when you create the
+ConfigObj, but just set all the values to <tt class="docutils literal">''</tt>. Then create an instance of
+<tt class="docutils literal">SimpleVal</tt> and pass it to the <tt class="docutils literal">validate</tt> method.</p>
+<p>As a trivial example if you had the following config file:</p>
+<pre class="literal-block">
+# config file for an application
+port = 80
+protocol = http
+domain = voidspace
+top_level_domain = org.uk
+</pre>
+<p>You would write the following configspec:</p>
+<pre class="literal-block">
+port = ''
+protocol = ''
+domain = ''
+top_level_domain = ''
+</pre>
+<div class="highlight"><pre><span class="n">config</span> <span class="o">=</span> <span class="n">Configobj</span><span class="p">(</span><span class="n">filename</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">configspec</span><span class="p">)</span>
+<span class="n">val</span> <span class="o">=</span> <span class="n">SimpleVal</span><span class="p">()</span>
+<span class="n">test</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">val</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">test</span> <span class="o">==</span> <span class="bp">True</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;All values present.&#39;</span>
+<span class="k">elif</span> <span class="n">test</span> <span class="o">==</span> <span class="bp">False</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;No values present!&#39;</span>
+<span class="k">else</span><span class="p">:</span>
+ <span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">test</span><span class="p">:</span>
+ <span class="k">if</span> <span class="n">test</span><span class="p">[</span><span class="n">entry</span><span class="p">]</span> <span class="o">==</span> <span class="bp">False</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;&quot;</span><span class="si">%s</span><span class="s">&quot; missing.&#39;</span> <span class="o">%</span> <span class="n">entry</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="empty-values">
+<h1><a class="toc-backref" href="#id78">10&nbsp;&nbsp;&nbsp;Empty values</a></h1>
+<p>Many config files from other applications allow empty values. As of version
+4.3.0, ConfigObj will read these as an empty string.</p>
+<p>A new option/attribute has been added (<tt class="docutils literal">write_empty_values</tt>) to allow
+ConfigObj to write empty strings as empty values.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">configobj</span> <span class="kn">import</span> <span class="n">ConfigObj</span>
+<span class="n">cfg</span> <span class="o">=</span> <span class="s">&#39;&#39;&#39;</span>
+<span class="s"> key =</span>
+<span class="s"> key2 = # a comment</span>
+<span class="s">&#39;&#39;&#39;</span><span class="o">.</span><span class="n">splitlines</span><span class="p">()</span>
+<span class="n">config</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">cfg</span><span class="p">)</span>
+<span class="k">print</span> <span class="n">config</span>
+<span class="n">ConfigObj</span><span class="p">({</span><span class="s">&#39;key&#39;</span><span class="p">:</span> <span class="s">&#39;&#39;</span><span class="p">,</span> <span class="s">&#39;key2&#39;</span><span class="p">:</span> <span class="s">&#39;&#39;</span><span class="p">})</span>
+
+<span class="n">config</span><span class="o">.</span><span class="n">write_empty_values</span> <span class="o">=</span> <span class="bp">True</span>
+<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">():</span>
+ <span class="k">print</span> <span class="n">line</span>
+
+<span class="n">key</span> <span class="o">=</span>
+<span class="n">key2</span> <span class="o">=</span> <span class="c"># a comment</span>
+</pre></div>
+</div>
+<div class="section" id="unrepr-mode">
+<h1><a class="toc-backref" href="#id79">11&nbsp;&nbsp;&nbsp;unrepr mode</a></h1>
+<p>The <tt class="docutils literal">unrepr</tt> option allows you to store and retrieve the basic Python
+data-types using config files. It has to use a slightly different syntax to
+normal ConfigObj files. Unsurprisingly it uses Python syntax.</p>
+<p>This means that lists are different (they are surrounded by square brackets),
+and strings <em>must</em> be quoted.</p>
+<p>The types that <tt class="docutils literal">unrepr</tt> can work with are :</p>
+<blockquote>
+<div class="line-block">
+<div class="line">strings, lists tuples</div>
+<div class="line">None, True, False</div>
+<div class="line">dictionaries, integers, floats</div>
+<div class="line">longs and complex numbers</div>
+</div>
+</blockquote>
+<p>You can't store classes, types or instances.</p>
+<p><tt class="docutils literal">unrepr</tt> uses <tt class="docutils literal">repr(object)</tt> to write out values, so it currently <em>doesn't</em>
+check that you are writing valid objects. If you attempt to read an unsupported
+value, ConfigObj will raise a <tt class="docutils literal">configobj.UnknownType</tt> exception.</p>
+<p>Values that are triple quoted cased. The triple quotes are removed <em>before</em>
+converting. This means that you can use triple quotes to write dictionaries
+over several lines in your config files. They won't be written like this
+though.</p>
+<p>If you are writing config files by hand, for use with <tt class="docutils literal">unrepr</tt>, you should
+be aware of the following differences from normal ConfigObj syntax :</p>
+<blockquote>
+<div class="line-block">
+<div class="line">List : <tt class="docutils literal">['A List', 'With', 'Strings']</tt></div>
+<div class="line">Strings : <tt class="docutils literal">&quot;Must be quoted.&quot;</tt></div>
+<div class="line">Backslash : <tt class="docutils literal">&quot;The backslash must be escaped \\&quot;</tt></div>
+</div>
+</blockquote>
+<p>These all follow normal Python syntax.</p>
+<p>In unrepr mode <em>inline comments</em> are not saved. This is because lines are
+parsed using the <a class="reference external" href="http://docs.python.org/lib/compiler.html">compiler package</a>
+which discards comments.</p>
+</div>
+<div class="section" id="string-interpolation">
+<h1><a class="toc-backref" href="#id80">12&nbsp;&nbsp;&nbsp;String Interpolation</a></h1>
+<p>ConfigObj allows string interpolation <em>similar</em> to the way <tt class="docutils literal">ConfigParser</tt>
+or <tt class="docutils literal">string.Template</tt> work. The value of the <tt class="docutils literal">interpolation</tt> attribute
+determines which style of interpolation you want to use. Valid values are
+&quot;ConfigParser&quot; or &quot;Template&quot; (case-insensitive, so &quot;configparser&quot; and
+&quot;template&quot; will also work). For backwards compatibility reasons, the value
+<tt class="docutils literal">True</tt> is also a valid value for the <tt class="docutils literal">interpolation</tt> attribute, and
+will select <tt class="docutils literal">ConfigParser</tt>-style interpolation. At some undetermined point
+in the future, that default <em>may</em> change to <tt class="docutils literal">Template</tt>-style interpolation.</p>
+<p>For <tt class="docutils literal">ConfigParser</tt>-style interpolation, you specify a value to be
+substituted by including <tt class="docutils literal">%(name)s</tt> in the value.</p>
+<p>For <tt class="docutils literal">Template</tt>-style interpolation, you specify a value to be substituted
+by including <tt class="docutils literal">${cl}name{cr}</tt> in the value. Alternately, if 'name' is a valid
+Python identifier (i.e., is composed of nothing but alphanumeric characters,
+plus the underscore character), then the braces are optional and the value
+can be written as <tt class="docutils literal">$name</tt>.</p>
+<p>Note that <tt class="docutils literal">ConfigParser</tt>-style interpolation and <tt class="docutils literal">Template</tt>-style
+interpolation are mutually exclusive; you cannot have a configuration file
+that's a mix of one or the other. Pick one and stick to it. <tt class="docutils literal">Template</tt>-style
+interpolation is simpler to read and write by hand, and is recommended if
+you don't have a particular reason to use <tt class="docutils literal">ConfigParser</tt>-style.</p>
+<p>Interpolation checks first the current section to see if <tt class="docutils literal">name</tt> is the key
+to a value. ('name' is case sensitive).</p>
+<p>If it doesn't find it, next it checks the 'DEFAULT' sub-section of the current
+section.</p>
+<p>If it still doesn't find it, it moves on to check the parent section and the
+parent section's 'DEFAULT' subsection, and so on all the way up to the main
+section.</p>
+<p>If the value specified isn't found in any of these locations, then a
+<tt class="docutils literal">MissingInterpolationOption</tt> error is raised (a subclass of
+<tt class="docutils literal">ConfigObjError</tt>).</p>
+<p>If it is found then the returned value is also checked for substitutions. This
+allows you to make up compound values (for example directory paths) that use
+more than one default value. It also means it's possible to create circular
+references. If there are any circular references which would cause an infinite
+interpolation loop, an <tt class="docutils literal">InterpolationLoopError</tt> is raised.</p>
+<p>Both of these errors are subclasses of <tt class="docutils literal">InterpolationError</tt>, which is a
+subclass of <tt class="docutils literal">ConfigObjError</tt>.</p>
+<p>String interpolation and validation don't play well together. This is because
+validation overwrites values - and so may erase the interpolation references.
+See <a class="reference internal" href="#validation-and-interpolation">Validation and Interpolation</a>. (This can only happen if validation
+has to <em>change</em> the value).</p>
+<p>New in ConfigObj 4.7.0: String interpolation is now done in members of list
+values.</p>
+</div>
+<div class="section" id="comments">
+<h1><a class="toc-backref" href="#id81">13&nbsp;&nbsp;&nbsp;Comments</a></h1>
+<p>Any line that starts with a '#', possibly preceded by whitespace, is a comment.</p>
+<p>If a config file starts with comments then these are preserved as the
+<a class="reference internal" href="#initial-comment">initial_comment</a>.</p>
+<p>If a config file ends with comments then these are preserved as the
+<a class="reference internal" href="#final-comment">final_comment</a>.</p>
+<p>Every key or section marker may have lines of comments immediately above it.
+These are saved as the <tt class="docutils literal">comments</tt> attribute of the section. Each member is a
+list of lines.</p>
+<p>You can also have a comment inline with a value. These are saved as the
+<tt class="docutils literal">inline_comments</tt> attribute of the section, with one entry per member of the
+section.</p>
+<p>Subsections (section markers in the config file) can also have comments.</p>
+<p>See <a class="reference internal" href="#section-attributes">Section Attributes</a> for more on these attributes.</p>
+<p>These comments are all written back out by the <tt class="docutils literal">write</tt> method.</p>
+</div>
+<div class="section" id="flatten-errors">
+<h1><a class="toc-backref" href="#id82">14&nbsp;&nbsp;&nbsp;flatten_errors</a></h1>
+<div class="highlight"><pre><span class="n">flatten_errors</span><span class="p">(</span><span class="n">cfg</span><span class="p">,</span> <span class="n">res</span><span class="p">)</span>
+</pre></div>
+<p><a class="reference internal" href="#validation">Validation</a> is a powerful way of checking that the values supplied by the user
+make sense.</p>
+<p>The <a class="reference internal" href="#validate">validate</a> method returns a results dictionary that represents pass or fail
+for each value. This doesn't give you any information about <em>why</em> the check
+failed.</p>
+<p><tt class="docutils literal">flatten_errors</tt> is an example function that turns a results dictionary into
+a flat list, that only contains values that <em>failed</em>.</p>
+<p><tt class="docutils literal">cfg</tt> is the ConfigObj instance being checked, <tt class="docutils literal">res</tt> is the results
+dictionary returned by <tt class="docutils literal">validate</tt>.</p>
+<p>It returns a list of keys that failed. Each member of the list is a tuple:</p>
+<pre class="literal-block">
+([list of sections...], key, result)
+</pre>
+<p>If <tt class="docutils literal">validate</tt> was called with <tt class="docutils literal">preserve_errors=False</tt> (the default)
+then <tt class="docutils literal">result</tt> will always be <tt class="docutils literal">False</tt>.</p>
+<p><em>list of sections</em> is a flattened list of sections that the key was found
+in.</p>
+<p>If the section was missing then key will be <tt class="docutils literal">None</tt>.</p>
+<p>If the value (or section) was missing then <tt class="docutils literal">result</tt> will be <tt class="docutils literal">False</tt>.</p>
+<p>If <tt class="docutils literal">validate</tt> was called with <tt class="docutils literal">preserve_errors=True</tt> and a value
+was present, but failed the check, then <tt class="docutils literal">result</tt> will be the exception
+object returned. You can use this as a string that describes the failure.</p>
+<p>For example :</p>
+<blockquote>
+<em>The value &quot;3&quot; is of the wrong type</em>.</blockquote>
+<div class="section" id="example-usage">
+<h2><a class="toc-backref" href="#id83">14.1&nbsp;&nbsp;&nbsp;Example Usage</a></h2>
+<p>The output from <tt class="docutils literal">flatten_errors</tt> is a list of tuples.</p>
+<p>Here is an example of how you could present this information to the user.</p>
+<div class="highlight"><pre><span class="n">vtor</span> <span class="o">=</span> <span class="n">validate</span><span class="o">.</span><span class="n">Validator</span><span class="p">()</span>
+<span class="c"># ini is your config file - cs is the configspec</span>
+<span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">ini</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">cs</span><span class="p">)</span>
+<span class="n">res</span> <span class="o">=</span> <span class="n">cfg</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">vtor</span><span class="p">,</span> <span class="n">preserve_errors</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+<span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">flatten_errors</span><span class="p">(</span><span class="n">cfg</span><span class="p">,</span> <span class="n">res</span><span class="p">):</span>
+ <span class="c"># each entry is a tuple</span>
+ <span class="n">section_list</span><span class="p">,</span> <span class="n">key</span><span class="p">,</span> <span class="n">error</span> <span class="o">=</span> <span class="n">entry</span>
+ <span class="k">if</span> <span class="n">key</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span>
+ <span class="n">section_list</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">section_list</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="s">&#39;[missing section]&#39;</span><span class="p">)</span>
+ <span class="n">section_string</span> <span class="o">=</span> <span class="s">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">section_list</span><span class="p">)</span>
+ <span class="k">if</span> <span class="n">error</span> <span class="o">==</span> <span class="bp">False</span><span class="p">:</span>
+ <span class="n">error</span> <span class="o">=</span> <span class="s">&#39;Missing value or section.&#39;</span>
+ <span class="k">print</span> <span class="n">section_string</span><span class="p">,</span> <span class="s">&#39; = &#39;</span><span class="p">,</span> <span class="n">error</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="get-extra-values">
+<h1><a class="toc-backref" href="#id84">15&nbsp;&nbsp;&nbsp;get_extra_values</a></h1>
+<div class="highlight"><pre><span class="n">get_extra_values</span><span class="p">(</span><span class="n">conf</span><span class="p">)</span>
+</pre></div>
+<p>New in ConfigObj 4.7.0.</p>
+<p>Find all the values and sections not in the configspec from a validated
+ConfigObj.</p>
+<p><tt class="docutils literal">get_extra_values</tt> returns a list of tuples where each tuple represents
+either an extra section, or an extra value.</p>
+<p>The tuples contain two values, a tuple representing the section the value
+is in and the name of the extra values. For extra values in the top level
+section the first member will be an empty tuple. For values in the 'foo'
+section the first member will be <tt class="docutils literal"><span class="pre">('foo',)</span></tt>. For members in the 'bar'
+subsection of the 'foo' section the first member will be <tt class="docutils literal">('foo', 'bar')</tt>.</p>
+<p>Extra sections will only have one entry. Values and subsections inside
+an extra section aren't listed separately.</p>
+<p>NOTE: If you call <tt class="docutils literal">get_extra_values</tt> on a ConfigObj instance that hasn't
+been validated it will return an empty list.</p>
+<div class="section" id="id14">
+<h2><a class="toc-backref" href="#id85">15.1&nbsp;&nbsp;&nbsp;Example Usage</a></h2>
+<p>The output from <tt class="docutils literal">get_extra_values</tt> is a list of tuples.</p>
+<p>Here is an example of how you could present this information to the user.</p>
+<div class="highlight"><pre><span class="n">vtor</span> <span class="o">=</span> <span class="n">validate</span><span class="o">.</span><span class="n">Validator</span><span class="p">()</span>
+<span class="c"># ini is your config file - cs is the configspec</span>
+<span class="n">cfg</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">ini</span><span class="p">,</span> <span class="n">configspec</span><span class="o">=</span><span class="n">cs</span><span class="p">)</span>
+<span class="n">cfg</span><span class="o">.</span><span class="n">validate</span><span class="p">(</span><span class="n">vtor</span><span class="p">,</span> <span class="n">preserve_errors</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
+
+<span class="k">for</span> <span class="n">sections</span><span class="p">,</span> <span class="n">name</span> <span class="ow">in</span> <span class="n">get_extra_values</span><span class="p">(</span><span class="n">cfg</span><span class="p">):</span>
+
+ <span class="c"># this code gets the extra values themselves</span>
+ <span class="n">the_section</span> <span class="o">=</span> <span class="n">cfg</span>
+ <span class="k">for</span> <span class="n">section</span> <span class="ow">in</span> <span class="n">sections</span><span class="p">:</span>
+ <span class="n">the_section</span> <span class="o">=</span> <span class="n">cfg</span><span class="p">[</span><span class="n">section</span><span class="p">]</span>
+
+ <span class="c"># the_value may be a section or a value</span>
+ <span class="n">the_value</span> <span class="o">=</span> <span class="n">the_section</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>
+
+ <span class="n">section_or_value</span> <span class="o">=</span> <span class="s">&#39;value</span>
+ <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">the_value</span><span class="p">,</span> <span class="nb">dict</span><span class="p">):</span>
+ <span class="c"># Sections are subclasses of dict</span>
+ <span class="n">section_or_value</span> <span class="o">=</span> <span class="s">&#39;section&#39;</span>
+
+ <span class="n">section_string</span> <span class="o">=</span> <span class="s">&#39;, &#39;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">sections</span><span class="p">)</span> <span class="ow">or</span> <span class="s">&quot;top level&quot;</span>
+ <span class="k">print</span> <span class="s">&#39;Extra entry in section: </span><span class="si">%s</span><span class="s">. Entry </span><span class="si">%r</span><span class="s"> is a </span><span class="si">%s</span><span class="s">&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">section_string</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="n">section_or_value</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="credits">
+<h1><a class="toc-backref" href="#id86">16&nbsp;&nbsp;&nbsp;CREDITS</a></h1>
+<p>ConfigObj 4 is written by (and copyright) <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a> and
+<a class="reference external" href="http://www.teknico.net">Nicola Larosa</a>.</p>
+<p>Particularly thanks to Nicola Larosa for help on the config file spec, the
+validation system and the doctests.</p>
+<p><em>validate.py</em> was originally written by Michael Foord and Mark Andrews.</p>
+<p>Thanks to many others for input, patches and bugfixes.</p>
+</div>
+<div class="section" id="license">
+<h1><a class="toc-backref" href="#id87">17&nbsp;&nbsp;&nbsp;LICENSE</a></h1>
+<p>ConfigObj, and related files, are licensed under the BSD license. This is a
+very unrestrictive license, but it comes with the usual disclaimer. This is
+free software: test it, break it, just don't blame us if it eats your data !
+Of course if it does, let us know and we'll fix the problem so it doesn't
+happen to anyone else:</p>
+<pre class="literal-block">
+Copyright (c) 2004 - 2010, Michael Foord &amp; Nicola Larosa
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+
+ * Redistributions of source code must retain the above copyright
+ notice, this list of conditions and the following disclaimer.
+
+ * Redistributions in binary form must reproduce the above
+ copyright notice, this list of conditions and the following
+ disclaimer in the documentation and/or other materials provided
+ with the distribution.
+
+ * Neither the name of Michael Foord nor Nicola Larosa
+ may be used to endorse or promote products derived from this
+ software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+&quot;AS IS&quot; AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+</pre>
+<p>You should also be able to find a copy of this license at : <a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></p>
+</div>
+<div class="section" id="todo">
+<h1><a class="toc-backref" href="#id88">18&nbsp;&nbsp;&nbsp;TODO</a></h1>
+<p>Better support for configuration from multiple files, including tracking
+<em>where</em> the original file came from and writing changes to the correct
+file.</p>
+<p>Make <tt class="docutils literal">newline</tt> a keyword argument (as well as an attribute) ?</p>
+<p><tt class="docutils literal">UTF16</tt> encoded files, when returned as a list of lines, will have the
+BOM at the start of every line. Should this be removed from all but the
+first line ?</p>
+<p>Option to set warning type for unicode decode ? (Defaults to strict).</p>
+<p>A method to optionally remove uniform indentation from multiline values.
+(do as an example of using <tt class="docutils literal">walk</tt> - along with string-escape)</p>
+<p>Should the results dictionary from validate be an ordered dictionary if
+<a class="reference external" href="http://www.voidspace.org.uk/python/odict.html">odict</a> is available ?</p>
+<p>Implement some of the sequence methods (which include slicing) from the
+newer <tt class="docutils literal">odict</tt> ?</p>
+<p>Preserve line numbers of values (and possibly the original text of each value).</p>
+</div>
+<div class="section" id="issues">
+<h1><a class="toc-backref" href="#id89">19&nbsp;&nbsp;&nbsp;ISSUES</a></h1>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Please file any bug reports to <a class="reference external" href="http://www.voidspace.org.uk/python/weblog/index.shtml">Michael Foord</a> or the <strong>ConfigObj</strong>
+<a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a>.</p>
+</div>
+<p>There is currently no way to specify the encoding of a configspec file.</p>
+<p>As a consequence of the changes to configspec handling in version 4.6.0, when
+you create a ConfigObj instance and provide a configspec, the configspec
+attribute is only set on the ConfigObj instance - it isn't set on the sections until you validate. You also can't set the configspec attribute to be a dictionary. This wasn't documented but did work previously.</p>
+<p>In order to fix the problem with hashes in configspecs I had to turn off the parsing of inline comments in configspecs. This will only affect you if you are using <tt class="docutils literal">copy=True</tt> when validating and expecting inline comments to be copied from the configspec into the ConfigObj instance (all other comments will be copied as usual).</p>
+<p>If you <em>create</em> the configspec by passing in a ConfigObj instance (usual way is to pass in a filename or list of lines) then you should pass in <tt class="docutils literal">_inspec=True</tt> to the constructor to allow hashes in values. This is the magic that switches off inline comment parsing.</p>
+<p>When using <tt class="docutils literal">copy</tt> mode for validation, it won't copy <tt class="docutils literal">DEFAULT</tt>
+sections. This is so that you <em>can</em> use interpolation in configspec
+files.</p>
+<p><tt class="docutils literal">validate</tt> doesn't report <em>extra</em> values or sections.</p>
+<p>You can't have a keyword with the same name as a section (in the same
+section). They are both dictionary keys - so they would overlap.</p>
+<p>ConfigObj doesn't quote and unquote values if <tt class="docutils literal">list_values=False</tt>.
+This means that leading or trailing whitespace in values will be lost when
+writing. (Unless you manually quote).</p>
+<p>Interpolation checks first the current section, then the 'DEFAULT' subsection
+of the current section, before moving on to the current section's parent and
+so on up the tree.</p>
+<p>Does it matter that we don't support the ':' divider, which is supported
+by <tt class="docutils literal">ConfigParser</tt> ?</p>
+<p>String interpolation and validation don't play well together. When
+validation changes type it sets the value. This will correctly fetch the
+value using interpolation - but then overwrite the interpolation reference.
+If the value is unchanged by validation (it's a string) - but other types
+will be.</p>
+</div>
+<div class="section" id="changelog">
+<h1><a class="toc-backref" href="#id90">20&nbsp;&nbsp;&nbsp;CHANGELOG</a></h1>
+<p>This is an abbreviated changelog showing the major releases up to version 4.
+From version 4 it lists all releases and changes.</p>
+<div class="section" id="version-4-7-0">
+<h2><a class="toc-backref" href="#id91">20.1&nbsp;&nbsp;&nbsp;20010/01/09 - Version 4.7.0</a></h2>
+<ul class="simple">
+<li>Minimum supported version of Python is now 2.3</li>
+<li>~25% performance improvement thanks to Christian Heimes</li>
+<li>String interpolation now works in list value members</li>
+<li>After validation any additional entries not in the configspec are listed in
+the <tt class="docutils literal">extra_values</tt> section member</li>
+<li>Addition of the <tt class="docutils literal">get_extra_values</tt> function for finding all extra values
+in a validated ConfigObj instance</li>
+<li>Deprecated the use of the <tt class="docutils literal">options</tt> dictionary in the ConfigObj constructor
+and added explicit keyword arguments instead. Use **options if you want
+to initialise a ConfigObj instance from a dictionary</li>
+<li>Constructing a ConfigObj from an existing ConfigObj instance now preserves
+the order of values and sections from the original instance in the new one</li>
+<li>BUGFIX: Checks that failed validation would not populate 'default_values' and
+'restore_default_value' wouldn't work for those entries</li>
+<li>BUGFIX: clear() now clears 'defaults'</li>
+<li>BUGFIX: empty values in list values were accidentally valid syntax. They now
+raise a <tt class="docutils literal">ParseError</tt>. e.g. &quot;value = 1, , 2&quot;</li>
+<li>BUGFIX: Change to the result of a call to <tt class="docutils literal">validate</tt> when <tt class="docutils literal">preserve_errors</tt>
+is True. Previously sections where <em>all</em> values failed validation would
+return False for the section rather than preserving the errors. False will
+now only be returned for a section if it is missing</li>
+<li>Distribution includes version 1.0.1 of validate.py</li>
+<li>Removed __revision__ and __docformat__</li>
+</ul>
+</div>
+<div class="section" id="version-4-6-0">
+<h2><a class="toc-backref" href="#id92">20.2&nbsp;&nbsp;&nbsp;2009/04/13 - Version 4.6.0</a></h2>
+<ul class="simple">
+<li>Pickling of ConfigObj instances now supported (thanks to Christian Heimes)</li>
+<li>Hashes in confgspecs are now allowed (see note below)</li>
+<li>Replaced use of hasattr (which can swallow exceptions) with getattr</li>
+<li>__many__ in configspecs can refer to scalars (ordinary values) as well as sections</li>
+<li>You can use ___many___ (three underscores!) where you want to use __many__ as well</li>
+<li>You can now have normal sections inside configspec sections that use __many__</li>
+<li>You can now create an empty ConfigObj with a configspec, programmatically set values and then validate</li>
+<li>A section that was supplied as a value (or vice-versa) in the actual config file would cause an exception during validation (the config file is still broken of course, but it is now handled gracefully)</li>
+<li>Added <tt class="docutils literal">as_list</tt> method</li>
+<li>Removed the deprecated <tt class="docutils literal">istrue</tt>, <tt class="docutils literal">encode</tt> and <tt class="docutils literal">decode</tt> methods</li>
+<li>Running test_configobj.py now also runs the doctests in the configobj module</li>
+</ul>
+<p>As a consequence of the changes to configspec handling, when you create a ConfigObj instance and provide
+a configspec, the configspec attribute is only set on the ConfigObj instance - it isn't set on the
+sections until you validate. You also can't set the configspec attribute to be a dictionary. This wasn't
+documented but did work previously.</p>
+<p>In order to fix the problem with hashes in configspecs I had to turn off the parsing of inline comments
+in configspecs. This will only affect you if you are using <tt class="docutils literal">copy=True</tt> when validating and expecting
+inline comments to be copied from the configspec into the ConfigObj instance (all other comments will be
+copied as usual).</p>
+<p>If you <em>create</em> the configspec by passing in a ConfigObj instance (usual way is to pass in a filename or
+list of lines) then you should pass in <tt class="docutils literal">_inspec=True</tt> to the constructor to allow hashes in values.
+This is the magic that switches off inline comment parsing.</p>
+</div>
+<div class="section" id="version-4-5-3">
+<h2><a class="toc-backref" href="#id93">20.3&nbsp;&nbsp;&nbsp;2008/06/27 - Version 4.5.3</a></h2>
+<p>BUGFIX: fixed a problem with <tt class="docutils literal">copy=True</tt> when validating with configspecs that use
+<tt class="docutils literal">__many__</tt> sections.</p>
+</div>
+<div class="section" id="version-4-5-2">
+<h2><a class="toc-backref" href="#id94">20.4&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.2</a></h2>
+<p>Distribution updated to include version 0.3.2 of <a class="reference internal" href="#validate">validate</a>. This means that
+<tt class="docutils literal">None</tt> as a default value in configspecs works.</p>
+</div>
+<div class="section" id="version-4-5-1">
+<h2><a class="toc-backref" href="#id95">20.5&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.1</a></h2>
+<p>Distribution updated to include version 0.3.1 of <a class="reference internal" href="#validate">validate</a>. This means that
+Unicode configspecs now work.</p>
+</div>
+<div class="section" id="version-4-5-0">
+<h2><a class="toc-backref" href="#id96">20.6&nbsp;&nbsp;&nbsp;2008/02/05 - Version 4.5.0</a></h2>
+<p>ConfigObj will now guarantee that files will be written terminated with a
+newline.</p>
+<p>ConfigObj will no longer attempt to import the <tt class="docutils literal">validate</tt> module, until/unless
+you call <tt class="docutils literal">ConfigObj.validate</tt> with <tt class="docutils literal">preserve_errors=True</tt>. This makes it
+faster to import.</p>
+<p>New methods <tt class="docutils literal">restore_default</tt> and <tt class="docutils literal">restore_defaults</tt>. <tt class="docutils literal">restore_default</tt>
+resets an entry to its default value (and returns that value). <tt class="docutils literal">restore_defaults</tt>
+resets all entries to their default value. It doesn't modify entries without a
+default value. You must have validated a ConfigObj (which populates the
+<tt class="docutils literal">default_values</tt> dictionary) before calling these methods.</p>
+<p>BUGFIX: Proper quoting of keys, values and list values that contain hashes
+(when writing). When <tt class="docutils literal">list_values=False</tt>, values containing hashes are
+triple quoted.</p>
+<p>Added the <tt class="docutils literal">reload</tt> method. This reloads a ConfigObj from file. If the filename
+attribute is not set then a <tt class="docutils literal">ReloadError</tt> (a new exception inheriting from
+<tt class="docutils literal">IOError</tt>) is raised.</p>
+<p>BUGFIX: Files are read in with 'rb' mode, so that native/non-native line endings work!</p>
+<p>Minor efficiency improvement in <tt class="docutils literal">unrepr</tt> mode.</p>
+<p>Added missing docstrings for some overidden dictionary methods.</p>
+<p>Added the <tt class="docutils literal">reset</tt> method. This restores a ConfigObj to a freshly created state.</p>
+<p>Removed old CHANGELOG file.</p>
+</div>
+<div class="section" id="version-4-4-0">
+<h2><a class="toc-backref" href="#id97">20.7&nbsp;&nbsp;&nbsp;2007/02/04 - Version 4.4.0</a></h2>
+<p>Official release of 4.4.0</p>
+</div>
+<div class="section" id="version-4-3-3-alpha4">
+<h2><a class="toc-backref" href="#id98">20.8&nbsp;&nbsp;&nbsp;2006/12/17 - Version 4.3.3-alpha4</a></h2>
+<p>By Nicola Larosa</p>
+<p>Allowed arbitrary indentation in the <tt class="docutils literal">indent_type</tt> parameter, removed the
+<tt class="docutils literal">NUM_INDENT_SPACES</tt> and <tt class="docutils literal">MAX_INTERPOL_DEPTH</tt> (a leftover) constants,
+added indentation tests (including another docutils workaround, sigh), updated
+the documentation.</p>
+<p>By Michael Foord</p>
+<p>Made the import of <tt class="docutils literal">compiler</tt> conditional so that <tt class="docutils literal">ConfigObj</tt> can be used
+with <a class="reference external" href="http://www.codeplex.com/IronPython">IronPython</a>.</p>
+</div>
+<div class="section" id="version-4-3-3-alpha3">
+<h2><a class="toc-backref" href="#id99">20.9&nbsp;&nbsp;&nbsp;2006/12/17 - Version 4.3.3-alpha3</a></h2>
+<p>By Nicola Larosa</p>
+<p>Added a missing <tt class="docutils literal">self.</tt> in the _handle_comment method and a related test,
+per Sourceforge bug #1523975.</p>
+</div>
+<div class="section" id="version-4-3-3-alpha2">
+<h2><a class="toc-backref" href="#id100">20.10&nbsp;&nbsp;&nbsp;2006/12/09 - Version 4.3.3-alpha2</a></h2>
+<p>By Nicola Larosa</p>
+<p>Changed interpolation search strategy, based on this patch by Robin Munn:
+<a class="reference external" href="http://sourceforge.net/mailarchive/message.php?msg_id=17125993">http://sourceforge.net/mailarchive/message.php?msg_id=17125993</a></p>
+</div>
+<div class="section" id="version-4-3-3-alpha1">
+<h2><a class="toc-backref" href="#id101">20.11&nbsp;&nbsp;&nbsp;2006/12/09 - Version 4.3.3-alpha1</a></h2>
+<p>By Nicola Larosa</p>
+<p>Added Template-style interpolation, with tests, based on this patch by
+Robin Munn: <a class="reference external" href="http://sourceforge.net/mailarchive/message.php?msg_id=17125991">http://sourceforge.net/mailarchive/message.php?msg_id=17125991</a>
+(awful archives, bad Sourceforge, bad).</p>
+</div>
+<div class="section" id="version-4-3-2">
+<h2><a class="toc-backref" href="#id102">20.12&nbsp;&nbsp;&nbsp;2006/06/04 - Version 4.3.2</a></h2>
+<p>Changed error handling, if parsing finds a single error then that error will
+be re-raised. That error will still have an <tt class="docutils literal">errors</tt> and a <tt class="docutils literal">config</tt>
+attribute.</p>
+<p>Fixed bug where '\n' terminated files could be truncated.</p>
+<p>Bugfix in <tt class="docutils literal">unrepr</tt> mode, it couldn't handle '#' in values. (Thanks to
+Philippe Normand for the report.)</p>
+<p>As a consequence of this fix, ConfigObj doesn't now keep inline comments in
+<tt class="docutils literal">unrepr</tt> mode. This is because the parser in the <a class="reference external" href="http://docs.python.org/lib/compiler.html">compiler package</a>
+doesn't keep comments.</p>
+<p>Error messages are now more useful. They tell you the number of parsing errors
+and the line number of the first error. (In the case of multiple errors.)</p>
+<p>Line numbers in exceptions now start at 1, not 0.</p>
+<p>Errors in <tt class="docutils literal">unrepr</tt> mode are now handled the same way as in the normal mode.
+The errors stored will be an <tt class="docutils literal">UnreprError</tt>.</p>
+</div>
+<div class="section" id="version-4-3-1">
+<h2><a class="toc-backref" href="#id103">20.13&nbsp;&nbsp;&nbsp;2006/04/29 - Version 4.3.1</a></h2>
+<p>Added <tt class="docutils literal">validate.py</tt> back into <tt class="docutils literal">configobj.zip</tt>. (Thanks to Stewart
+Midwinter)</p>
+<p>Updated to <a class="reference external" href="http://www.voidspace.org.uk/downloads/validate.py">validate.py</a> 0.2.2.</p>
+<p>Preserve tuples when calling the <tt class="docutils literal">dict</tt> method. (Thanks to Gustavo Niemeyer.)</p>
+<p>Changed <tt class="docutils literal">__repr__</tt> to return a string that contains <tt class="docutils literal">ConfigObj({ ... })</tt>.</p>
+<p>Change so that an options dictionary isn't modified by passing it to ConfigObj.
+(Thanks to Artarious.)</p>
+<p>Added ability to handle negative integers in <tt class="docutils literal">unrepr</tt>. (Thanks to Kevin
+Dangoor.)</p>
+</div>
+<div class="section" id="version-4-3-0">
+<h2><a class="toc-backref" href="#id104">20.14&nbsp;&nbsp;&nbsp;2006/03/24 - Version 4.3.0</a></h2>
+<p>Moved the tests and the CHANGELOG (etc) into a separate file. This has reduced
+the size of <tt class="docutils literal">configobj.py</tt> by about 40%.</p>
+<p>Added the <tt class="docutils literal">unrepr</tt> mode to reading and writing config files. Thanks to Kevin
+Dangoor for this suggestion.</p>
+<p>Empty values are now valid syntax. They are read as an empty string <tt class="docutils literal">''</tt>.
+(<tt class="docutils literal">key =</tt>, or <tt class="docutils literal">key = # comment</tt>.)</p>
+<p><tt class="docutils literal">validate</tt> now honours the order of the configspec.</p>
+<p>Added the <tt class="docutils literal">copy</tt> mode to validate. Thanks to Louis Cordier for this
+suggestion.</p>
+<p>Fixed bug where files written on windows could be given <tt class="docutils literal">'\r\r\n'</tt> line
+terminators.</p>
+<p>Fixed bug where last occurring comment line could be interpreted as the
+final comment if the last line isn't terminated.</p>
+<p>Fixed bug where nested list values would be flattened when <tt class="docutils literal">write</tt> is
+called. Now sub-lists have a string representation written instead.</p>
+<p>Deprecated <tt class="docutils literal">encode</tt> and <tt class="docutils literal">decode</tt> methods instead.</p>
+<p>You can now pass in a ConfigObj instance as a configspec (remember to read
+the configspec file using <tt class="docutils literal">list_values=False</tt>).</p>
+<p>Sorted footnotes in the docs.</p>
+</div>
+<div class="section" id="version-4-2-0">
+<h2><a class="toc-backref" href="#id105">20.15&nbsp;&nbsp;&nbsp;2006/02/16 - Version 4.2.0</a></h2>
+<p>Removed <tt class="docutils literal">BOM_UTF8</tt> from <tt class="docutils literal">__all__</tt>.</p>
+<p>The <tt class="docutils literal">BOM</tt> attribute has become a boolean. (Defaults to <tt class="docutils literal">False</tt>.) It is
+<em>only</em> <tt class="docutils literal">True</tt> for the <tt class="docutils literal">UTF16/UTF8</tt> encodings.</p>
+<p>File like objects no longer need a <tt class="docutils literal">seek</tt> attribute.</p>
+<p>Full unicode support added. New options/attributes <tt class="docutils literal">encoding</tt>,
+<tt class="docutils literal">default_encoding</tt>.</p>
+<p>ConfigObj no longer keeps a reference to file like objects. Instead the
+<tt class="docutils literal">write</tt> method takes a file like object as an optional argument. (Which
+will be used in preference of the <tt class="docutils literal">filename</tt> attribute if that exists as
+well.)</p>
+<p>utf16 files decoded to unicode.</p>
+<p>If <tt class="docutils literal">BOM</tt> is <tt class="docutils literal">True</tt>, but no encoding specified, then the utf8 BOM is
+written out at the start of the file. (It will normally only be <tt class="docutils literal">True</tt> if
+the utf8 BOM was found when the file was read.)</p>
+<p>Thanks to Aaron Bentley for help and testing on the unicode issues.</p>
+<p>File paths are <em>not</em> converted to absolute paths, relative paths will
+remain relative as the <tt class="docutils literal">filename</tt> attribute.</p>
+<p>Fixed bug where <tt class="docutils literal">final_comment</tt> wasn't returned if <tt class="docutils literal">write</tt> is returning
+a list of lines.</p>
+<p>Deprecated <tt class="docutils literal">istrue</tt>, replaced it with <tt class="docutils literal">as_bool</tt>.</p>
+<p>Added <tt class="docutils literal">as_int</tt> and <tt class="docutils literal">as_float</tt>.</p>
+</div>
+<div class="section" id="version-4-1-0">
+<h2><a class="toc-backref" href="#id106">20.16&nbsp;&nbsp;&nbsp;2005/12/14 - Version 4.1.0</a></h2>
+<p>Added <tt class="docutils literal">merge</tt>, a recursive update.</p>
+<p>Added <tt class="docutils literal">preserve_errors</tt> to <tt class="docutils literal">validate</tt> and the <tt class="docutils literal">flatten_errors</tt>
+example function.</p>
+<p>Thanks to Matthew Brett for suggestions and helping me iron out bugs.</p>
+<p>Fixed bug where a config file is <em>all</em> comment, the comment will now be
+<tt class="docutils literal">initial_comment</tt> rather than <tt class="docutils literal">final_comment</tt>.</p>
+<p>Validation no longer done on the 'DEFAULT' section (only in the root level).
+This allows interpolation in configspecs.</p>
+<p>Also use the new list syntax in <a class="reference internal" href="#validate">validate</a> 0.2.1. (For configspecs).</p>
+</div>
+<div class="section" id="version-4-0-2">
+<h2><a class="toc-backref" href="#id107">20.17&nbsp;&nbsp;&nbsp;2005/12/02 - Version 4.0.2</a></h2>
+<p>Fixed bug in <tt class="docutils literal">create_empty</tt>. Thanks to Paul Jimenez for the report.</p>
+</div>
+<div class="section" id="version-4-0-1">
+<h2><a class="toc-backref" href="#id108">20.18&nbsp;&nbsp;&nbsp;2005/11/05 - Version 4.0.1</a></h2>
+<p>Fixed bug in <tt class="docutils literal">Section.walk</tt> when transforming names as well as values.</p>
+<p>Added the <tt class="docutils literal">istrue</tt> method. (Fetches the boolean equivalent of a string
+value).</p>
+<p>Fixed <tt class="docutils literal">list_values=False</tt> - they are now only quoted/unquoted if they
+are multiline values.</p>
+<p>List values are written as <tt class="docutils literal">item, item</tt> rather than <tt class="docutils literal">item,item</tt>.</p>
+</div>
+<div class="section" id="version-4-0-0">
+<h2><a class="toc-backref" href="#id109">20.19&nbsp;&nbsp;&nbsp;2005/10/17 - Version 4.0.0</a></h2>
+<p><strong>ConfigObj 4.0.0 Final</strong></p>
+<p>Fixed bug in <tt class="docutils literal">setdefault</tt>. When creating a new section with setdefault the
+reference returned would be to the dictionary passed in <em>not</em> to the new
+section. Bug fixed and behaviour documented.</p>
+<p>Obscure typo/bug fixed in <tt class="docutils literal">write</tt>. Wouldn't have affected anyone though.</p>
+</div>
+<div class="section" id="version-4-0-0-beta-5">
+<h2><a class="toc-backref" href="#id110">20.20&nbsp;&nbsp;&nbsp;2005/09/09 - Version 4.0.0 beta 5</a></h2>
+<p>Removed <tt class="docutils literal">PositionError</tt>.</p>
+<p>Allowed quotes around keys as documented.</p>
+<p>Fixed bug with commas in comments. (matched as a list value)</p>
+</div>
+<div class="section" id="version-4-0-0-beta-4">
+<h2><a class="toc-backref" href="#id111">20.21&nbsp;&nbsp;&nbsp;2005/09/07 - Version 4.0.0 beta 4</a></h2>
+<p>Fixed bug in <tt class="docutils literal">__delitem__</tt>. Deleting an item no longer deletes the
+<tt class="docutils literal">inline_comments</tt> attribute.</p>
+<p>Fixed bug in initialising ConfigObj from a ConfigObj.</p>
+<p>Changed the mailing list address.</p>
+</div>
+<div class="section" id="version-4-0-0-beta-3">
+<h2><a class="toc-backref" href="#id112">20.22&nbsp;&nbsp;&nbsp;2005/08/28 - Version 4.0.0 beta 3</a></h2>
+<p>Interpolation is switched off before writing out files.</p>
+<p>Fixed bug in handling <tt class="docutils literal">StringIO</tt> instances. (Thanks to report from
+Gustavo Niemeyer.)</p>
+<p>Moved the doctests from the <tt class="docutils literal">__init__</tt> method to a separate function.
+(For the sake of IDE calltips).</p>
+</div>
+<div class="section" id="version-4-0-0-beta-2">
+<h2><a class="toc-backref" href="#id113">20.23&nbsp;&nbsp;&nbsp;2005/08/25 - Version 4.0.0 beta 2</a></h2>
+<p>Amendments to <em>validate.py</em>.</p>
+<p>First public release.</p>
+</div>
+<div class="section" id="version-4-0-0-beta-1">
+<h2><a class="toc-backref" href="#id114">20.24&nbsp;&nbsp;&nbsp;2005/08/21 - Version 4.0.0 beta 1</a></h2>
+<p>Reads nested subsections to any depth.</p>
+<p>Multiline values.</p>
+<p>Simplified options and methods.</p>
+<p>New list syntax.</p>
+<p>Faster, smaller, and better parser.</p>
+<p>Validation greatly improved. Includes:</p>
+<blockquote>
+<ul class="simple">
+<li>type conversion</li>
+<li>default values</li>
+<li>repeated sections</li>
+</ul>
+</blockquote>
+<p>Improved error handling.</p>
+<p>Plus lots of other improvements.</p>
+</div>
+<div class="section" id="version-3-0-0">
+<h2><a class="toc-backref" href="#id115">20.25&nbsp;&nbsp;&nbsp;2004/05/24 - Version 3.0.0</a></h2>
+<p>Several incompatible changes: another major overhaul and change. (Lots of
+improvements though).</p>
+<p>Added support for standard config files with sections. This has an entirely
+new interface: each section is a dictionary of values.</p>
+<p>Changed the update method to be called writein: update clashes with a dict
+method.</p>
+<p>Made various attributes keyword arguments, added several.</p>
+<p>Configspecs and orderlists have changed a great deal.</p>
+<p>Removed support for adding dictionaries: use update instead.</p>
+<p>Now subclasses a new class called caselessDict. This should add various
+dictionary methods that could have caused errors before.</p>
+<p>It also preserves the original casing of keywords when writing them back out.</p>
+<p>Comments are also saved using a <tt class="docutils literal">caselessDict</tt>.</p>
+<p>Using a non-string key will now raise a <tt class="docutils literal">TypeError</tt> rather than converting
+the key.</p>
+<p>Added an exceptions keyword for <em>much</em> better handling of errors.</p>
+<p>Made <tt class="docutils literal">creatempty=False</tt> the default.</p>
+<p>Now checks indict <em>and</em> any keyword args. Keyword args take precedence over
+indict.</p>
+<p><tt class="docutils literal">' ', <span class="pre">':',</span> <span class="pre">'=',</span> ','</tt> and <tt class="docutils literal">'\t'</tt> are now all valid dividers where the
+keyword is unquoted.</p>
+<p>ConfigObj now does no type checking against configspec when you set items.</p>
+<p>delete and add methods removed (they were unnecessary).</p>
+<p>Docs rewritten to include all this gumph and more; actually ConfigObj is
+<em>really</em> easy to use.</p>
+<p>Support for stdout was removed.</p>
+<p>A few new methods added.</p>
+<p>Charmap is now incorporated into ConfigObj.</p>
+</div>
+<div class="section" id="version-2-0-0-beta">
+<h2><a class="toc-backref" href="#id116">20.26&nbsp;&nbsp;&nbsp;2004/03/14 - Version 2.0.0 beta</a></h2>
+<p>Re-written it to subclass dict. My first forays into inheritance and operator
+overloading.</p>
+<p>The config object now behaves like a dictionary.</p>
+<p>I've completely broken the interface, but I don't think anyone was really
+using it anyway.</p>
+<p>This new version is much more 'classy'.</p>
+<p>It will also read straight from/to a filename and completely parse a config
+file without you <em>having</em> to supply a config spec.</p>
+<p>Uses listparse, so can handle nested list items as values.</p>
+<p>No longer has getval and setval methods: use normal dictionary methods, or add
+and delete.</p>
+</div>
+<div class="section" id="version-1-0-5">
+<h2><a class="toc-backref" href="#id117">20.27&nbsp;&nbsp;&nbsp;2004/01/29 - Version 1.0.5</a></h2>
+<p>Version 1.0.5 has a couple of bugfixes as well as a couple of useful additions
+over previous versions.</p>
+<p>Since 1.0.0 the buildconfig function has been moved into this distribution,
+and the methods reset, verify, getval and setval have been added.</p>
+<p>A couple of bugs have been fixed.</p>
+</div>
+<div class="section" id="origins">
+<h2><a class="toc-backref" href="#id118">20.28&nbsp;&nbsp;&nbsp;Origins</a></h2>
+<p>ConfigObj originated in a set of functions for reading config files in the
+<a class="reference external" href="http://www.voidspace.org.uk/atlantibots/">atlantibots</a> project. The original
+functions were written by Rob McNeur.</p>
+</div>
+</div>
+<hr class="docutils" />
+<div class="section" id="footnotes">
+<h1><a class="toc-backref" href="#id119">21&nbsp;&nbsp;&nbsp;Footnotes</a></h1>
+<table class="docutils footnote" frame="void" id="id15" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>And if you discover any bugs, let us know. We'll fix them quickly.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id16" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>If you specify a filename that doesn't exist, ConfigObj will assume you
+are creating a new one. See the <em>create_empty</em> and <em>file_error</em> options.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id17" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>They can be byte strings (<em>ordinary</em> strings) or Unicode.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id18" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id4">[4]</a></td><td>Except we don't support the RFC822 style line continuations, nor ':' as
+a divider.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id19" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id5">[5]</a></td><td>This is a change in ConfigObj 4.2.0. Note that ConfigObj doesn't call
+the seek method of any file like object you pass in. You may want to call
+<tt class="docutils literal">file_object.seek(0)</tt> yourself, first.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id20" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id6">[6]</a></td><td><p class="first">A side effect of this is that it enables you to copy a ConfigObj :</p>
+<div class="highlight"><pre><span class="c"># only copies members</span>
+<span class="c"># not attributes/comments</span>
+<span class="n">config2</span> <span class="o">=</span> <span class="n">ConfigObj</span><span class="p">(</span><span class="n">config1</span><span class="p">)</span>
+</pre></div>
+<p class="last">The order of values and sections will not be preserved, though.</p>
+</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id21" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id7">[7]</a></td><td>Other than lists of strings.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id22" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id8">[8]</a></td><td>The exception is if it detects a <tt class="docutils literal">UTF16</tt> encoded file which it
+must decode before parsing.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id23" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id9">[9]</a></td><td>The method signature shows that this method takes
+two arguments. The second is the section to be written. This is because the
+<tt class="docutils literal">write</tt> method is called recursively.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id24" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id10">[10]</a></td><td>The dict method doesn't actually use the deepcopy mechanism. This means
+if you add nested lists (etc) to your ConfigObj, then the dictionary
+returned by dict may contain some references. For all <em>normal</em> ConfigObjs
+it will return a deepcopy.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id25" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id11">[11]</a></td><td>Passing <tt class="docutils literal">(section, key)</tt> rather than <tt class="docutils literal">(value, key)</tt> allows you to
+change the value by setting <tt class="docutils literal">section[key] = newval</tt>. It also gives you
+access to the <em>rename</em> method of the section.</td></tr>
+</tbody>
+</table>
+<table class="docutils footnote" frame="void" id="id26" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id12">[12]</a></td><td>Minimum required version of <em>validate.py</em> 0.2.0 .</td></tr>
+</tbody>
+</table>
+</div>
+</div>
+</body>
+</html>
diff --git a/docs/configobj.txt b/docs/configobj.txt
index 905f656..60de04c 100644
--- a/docs/configobj.txt
+++ b/docs/configobj.txt
@@ -787,7 +787,7 @@ Attributes
A ConfigObj has the following attributes :
* indent_type
-* interpolate
+* interpolation
* stringify
* BOM
* initial_comment
@@ -887,14 +887,7 @@ handled as normal.
.. caution::
- Because values aren't quoted, leading or trailing whitespace can be
- lost.
-
- This behaviour was changed in version 4.0.1.
-
- Prior to this, single line values might have been quoted; even with
- ``list_values=False``. This means that files written by **ConfigObj**
- *could* now be incompatible - and need the quotes removing by hand.
+ Because values aren't quoted, leading or trailing whitespace can be lost. This behaviour was changed in version 4.0.1. Prior to this, single line values might have been quoted; even with ``list_values=False``. This means that files written by earlier versions of ConfigObj *could* now be incompatible and need the quotes removing by hand.
encoding
diff --git a/docs/default.css b/docs/default.css
new file mode 100644
index 0000000..030cf17
--- /dev/null
+++ b/docs/default.css
@@ -0,0 +1,293 @@
+/*
+:Author: David Goodger (goodger@python.org)
+:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
+:Copyright: This stylesheet has been placed in the public domain.
+
+Default cascading style sheet for the HTML output of Docutils.
+
+See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
+customize this style sheet.
+*/
+
+/* used to remove borders from tables and images */
+.borderless, table.borderless td, table.borderless th {
+ border: 0 }
+
+table.borderless td, table.borderless th {
+ /* Override padding for "table.docutils td" with "! important".
+ The right padding separates the table cells. */
+ padding: 0 0.5em 0 0 ! important }
+
+.first {
+ /* Override more specific margin styles with "! important". */
+ margin-top: 0 ! important }
+
+.last, .with-subtitle {
+ margin-bottom: 0 ! important }
+
+.hidden {
+ display: none }
+
+a.toc-backref {
+ text-decoration: none ;
+ color: black }
+
+blockquote.epigraph {
+ margin: 2em 5em ; }
+
+dl.docutils dd {
+ margin-bottom: 0.5em }
+
+/* Uncomment (and remove this text!) to get bold-faced definition list terms
+dl.docutils dt {
+ font-weight: bold }
+*/
+
+div.abstract {
+ margin: 2em 5em }
+
+div.abstract p.topic-title {
+ font-weight: bold ;
+ text-align: center }
+
+div.admonition, div.attention, div.caution, div.danger, div.error,
+div.hint, div.important, div.note, div.tip, div.warning {
+ margin: 2em ;
+ border: medium outset ;
+ padding: 1em }
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ font-weight: bold ;
+ font-family: sans-serif }
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: red ;
+ font-weight: bold ;
+ font-family: sans-serif }
+
+/* Uncomment (and remove this text!) to get reduced vertical space in
+ compound paragraphs.
+div.compound .compound-first, div.compound .compound-middle {
+ margin-bottom: 0.5em }
+
+div.compound .compound-last, div.compound .compound-middle {
+ margin-top: 0.5em }
+*/
+
+div.dedication {
+ margin: 2em 5em ;
+ text-align: center ;
+ font-style: italic }
+
+div.dedication p.topic-title {
+ font-weight: bold ;
+ font-style: normal }
+
+div.figure {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+div.footer, div.header {
+ clear: both;
+ font-size: smaller }
+
+div.line-block {
+ display: block ;
+ margin-top: 1em ;
+ margin-bottom: 1em }
+
+div.line-block div.line-block {
+ margin-top: 0 ;
+ margin-bottom: 0 ;
+ margin-left: 1.5em }
+
+div.sidebar {
+ margin: 0 0 0.5em 1em ;
+ border: medium outset ;
+ padding: 1em ;
+ background-color: #ffffee ;
+ width: 40% ;
+ float: right ;
+ clear: right }
+
+div.sidebar p.rubric {
+ font-family: sans-serif ;
+ font-size: medium }
+
+div.system-messages {
+ margin: 5em }
+
+div.system-messages h1 {
+ color: red }
+
+div.system-message {
+ border: medium outset ;
+ padding: 1em }
+
+div.system-message p.system-message-title {
+ color: red ;
+ font-weight: bold }
+
+div.topic {
+ margin: 2em }
+
+h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
+h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
+ margin-top: 0.4em }
+
+h1.title {
+ text-align: center }
+
+h2.subtitle {
+ text-align: center }
+
+hr.docutils {
+ width: 75% }
+
+img.align-left, .figure.align-left{
+ clear: left ;
+ float: left ;
+ margin-right: 1em }
+
+img.align-right, .figure.align-right {
+ clear: right ;
+ float: right ;
+ margin-left: 1em }
+
+.align-left {
+ text-align: left }
+
+.align-center {
+ clear: both ;
+ text-align: center }
+
+.align-right {
+ text-align: right }
+
+/* reset inner alignment in figures */
+div.align-right {
+ text-align: left }
+
+/* div.align-center * { */
+/* text-align: left } */
+
+ol.simple, ul.simple {
+ margin-bottom: 1em }
+
+ol.arabic {
+ list-style: decimal }
+
+ol.loweralpha {
+ list-style: lower-alpha }
+
+ol.upperalpha {
+ list-style: upper-alpha }
+
+ol.lowerroman {
+ list-style: lower-roman }
+
+ol.upperroman {
+ list-style: upper-roman }
+
+p.attribution {
+ text-align: right ;
+ margin-left: 50% }
+
+p.caption {
+ font-style: italic }
+
+p.credits {
+ font-style: italic ;
+ font-size: smaller }
+
+p.label {
+ white-space: nowrap }
+
+p.rubric {
+ font-weight: bold ;
+ font-size: larger ;
+ color: maroon ;
+ text-align: center }
+
+p.sidebar-title {
+ font-family: sans-serif ;
+ font-weight: bold ;
+ font-size: larger }
+
+p.sidebar-subtitle {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+p.topic-title {
+ font-weight: bold }
+
+pre.address {
+ margin-bottom: 0 ;
+ margin-top: 0 ;
+ font: inherit }
+
+pre.literal-block, pre.doctest-block {
+ margin-left: 2em ;
+ margin-right: 2em }
+
+span.classifier {
+ font-family: sans-serif ;
+ font-style: oblique }
+
+span.classifier-delimiter {
+ font-family: sans-serif ;
+ font-weight: bold }
+
+span.interpreted {
+ font-family: sans-serif }
+
+span.option {
+ white-space: nowrap }
+
+span.pre {
+ white-space: pre }
+
+span.problematic {
+ color: red }
+
+span.section-subtitle {
+ /* font-size relative to parent (h1..h6 element) */
+ font-size: 80% }
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px }
+
+table.docinfo {
+ margin: 2em 4em }
+
+table.docutils {
+ margin-top: 0.5em ;
+ margin-bottom: 0.5em }
+
+table.footnote {
+ border-left: solid 1px black;
+ margin-left: 1px }
+
+table.docutils td, table.docutils th,
+table.docinfo td, table.docinfo th {
+ padding-left: 0.5em ;
+ padding-right: 0.5em ;
+ vertical-align: top }
+
+table.docutils th.field-name, table.docinfo th.docinfo-name {
+ font-weight: bold ;
+ text-align: left ;
+ white-space: nowrap ;
+ padding-left: 0 }
+
+h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
+h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
+ font-size: 100% }
+
+ul.auto-toc {
+ list-style-type: none }
diff --git a/docs/docutils.conf b/docs/docutils.conf
index 017983a..0a1f9ca 100644
--- a/docs/docutils.conf
+++ b/docs/docutils.conf
@@ -1,2 +1,5 @@
[html4css1 writer]
embed-stylesheet: no
+cloak_email_addresses: yes
+stylesheet: voidspace_docutils.css
+template: template.tmp \ No newline at end of file
diff --git a/docs/template.tmp b/docs/template.tmp
new file mode 100644
index 0000000..2591bce
--- /dev/null
+++ b/docs/template.tmp
@@ -0,0 +1,8 @@
+%(head_prefix)s
+%(head)s
+%(stylesheet)s
+%(body_prefix)s
+%(body_pre_docinfo)s
+%(docinfo)s
+%(body)s
+%(body_suffix)s
diff --git a/docs/validate.html b/docs/validate.html
new file mode 100644
index 0000000..d598c16
--- /dev/null
+++ b/docs/validate.html
@@ -0,0 +1,639 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!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" xml:lang="en" lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
+<title>Validation Schema with validate.py</title>
+<meta name="authors" content="Michael Foord Nicola Larosa Mark Andrews" />
+<meta name="date" content="2010/01/09" />
+<link rel="stylesheet" href="voidspace_docutils.css" type="text/css" />
+</head>
+<body>
+<div class="document" id="validation-schema-with-validate-py">
+<h1 class="title">Validation Schema with validate.py</h1>
+<h2 class="subtitle" id="using-the-validator-class">Using the Validator class</h2>
+<table class="docinfo" frame="void" rules="none">
+<col class="docinfo-name" />
+<col class="docinfo-content" />
+<tbody valign="top">
+<tr><th class="docinfo-name">Authors:</th>
+<td>Michael Foord
+<br />Nicola Larosa
+<br />Mark Andrews</td></tr>
+<tr><th class="docinfo-name">Version:</th>
+<td>Validate 1.0.1</td></tr>
+<tr><th class="docinfo-name">Date:</th>
+<td>2010/01/09</td></tr>
+<tr class="field"><th class="docinfo-name">Homepage:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">Validate Homepage</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Repository:</th><td class="field-body"><a class="reference external" href="http://code.google.com/p/configobj/">Google code homepage</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">PyPI Entry:</th><td class="field-body"><a class="reference external" href="http://pypi.python.org/pypi/validate">Validate on Python Packaging Index</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">License:</th><td class="field-body"><a class="reference external" href="http://www.voidspace.org.uk/python/license.shtml">BSD License</a></td>
+</tr>
+<tr class="field"><th class="docinfo-name">Support:</th><td class="field-body"><a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a></td>
+</tr>
+</tbody>
+</table>
+<div class="contents topic" id="validate-manual">
+<p class="topic-title first">Validate Manual</p>
+<ul class="auto-toc simple">
+<li><a class="reference internal" href="#introduction" id="id1">1&nbsp;&nbsp;&nbsp;Introduction</a></li>
+<li><a class="reference internal" href="#downloading" id="id2">2&nbsp;&nbsp;&nbsp;Downloading</a><ul class="auto-toc">
+<li><a class="reference internal" href="#files" id="id3">2.1&nbsp;&nbsp;&nbsp;Files</a></li>
+<li><a class="reference internal" href="#documentation" id="id4">2.2&nbsp;&nbsp;&nbsp;Documentation</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#the-standard-functions" id="id5">3&nbsp;&nbsp;&nbsp;The standard functions</a></li>
+<li><a class="reference internal" href="#using-validator" id="id6">4&nbsp;&nbsp;&nbsp;Using Validator</a><ul class="auto-toc">
+<li><a class="reference internal" href="#instantiate" id="id7">4.1&nbsp;&nbsp;&nbsp;Instantiate</a></li>
+<li><a class="reference internal" href="#adding-functions" id="id8">4.2&nbsp;&nbsp;&nbsp;Adding functions</a></li>
+<li><a class="reference internal" href="#writing-the-check" id="id9">4.3&nbsp;&nbsp;&nbsp;Writing the check</a></li>
+<li><a class="reference internal" href="#the-check-method" id="id10">4.4&nbsp;&nbsp;&nbsp;The check method</a><ul class="auto-toc">
+<li><a class="reference internal" href="#default-values" id="id11">4.4.1&nbsp;&nbsp;&nbsp;Default Values</a></li>
+<li><a class="reference internal" href="#list-values" id="id12">4.4.2&nbsp;&nbsp;&nbsp;List Values</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#get-default-value" id="id13">4.5&nbsp;&nbsp;&nbsp;get_default_value</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#validator-exceptions" id="id14">5&nbsp;&nbsp;&nbsp;Validator Exceptions</a></li>
+<li><a class="reference internal" href="#writing-check-functions" id="id15">6&nbsp;&nbsp;&nbsp;Writing check functions</a><ul class="auto-toc">
+<li><a class="reference internal" href="#example" id="id16">6.1&nbsp;&nbsp;&nbsp;Example</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#known-issues" id="id17">7&nbsp;&nbsp;&nbsp;Known Issues</a></li>
+<li><a class="reference internal" href="#todo" id="id18">8&nbsp;&nbsp;&nbsp;TODO</a></li>
+<li><a class="reference internal" href="#issues" id="id19">9&nbsp;&nbsp;&nbsp;ISSUES</a></li>
+<li><a class="reference internal" href="#changelog" id="id20">10&nbsp;&nbsp;&nbsp;CHANGELOG</a><ul class="auto-toc">
+<li><a class="reference internal" href="#version-1-0-1" id="id21">10.1&nbsp;&nbsp;&nbsp;2009/10/25 - Version 1.0.1</a></li>
+<li><a class="reference internal" href="#version-1-0-0" id="id22">10.2&nbsp;&nbsp;&nbsp;2009/04/13 - Version 1.0.0</a></li>
+<li><a class="reference internal" href="#version-0-3-2" id="id23">10.3&nbsp;&nbsp;&nbsp;2008/02/24 - Version 0.3.2</a></li>
+<li><a class="reference internal" href="#version-0-3-1" id="id24">10.4&nbsp;&nbsp;&nbsp;2008/02/05 - Version 0.3.1</a></li>
+<li><a class="reference internal" href="#version-0-3-0" id="id25">10.5&nbsp;&nbsp;&nbsp;2008/02/05 - Version 0.3.0</a></li>
+<li><a class="reference internal" href="#version-0-2-3" id="id26">10.6&nbsp;&nbsp;&nbsp;2007/02/04 Version 0.2.3</a></li>
+<li><a class="reference internal" href="#version-0-2-3-alpha1" id="id27">10.7&nbsp;&nbsp;&nbsp;2006/12/17 Version 0.2.3-alpha1</a></li>
+<li><a class="reference internal" href="#version-0-2-2" id="id28">10.8&nbsp;&nbsp;&nbsp;2006/04/29 Version 0.2.2</a></li>
+<li><a class="reference internal" href="#version-0-2-1" id="id29">10.9&nbsp;&nbsp;&nbsp;2005/12/16 Version 0.2.1</a></li>
+<li><a class="reference internal" href="#version-0-2-0" id="id30">10.10&nbsp;&nbsp;&nbsp;2005/08/18 Version 0.2.0</a></li>
+<li><a class="reference internal" href="#version-0-1-0" id="id31">10.11&nbsp;&nbsp;&nbsp;2005/02/01 Version 0.1.0</a></li>
+</ul>
+</li>
+</ul>
+</div>
+<div class="section" id="introduction">
+<h1><a class="toc-backref" href="#id1">1&nbsp;&nbsp;&nbsp;Introduction</a></h1>
+<p>Validation is used to check that supplied values conform to a specification.</p>
+<p>The value can be supplied as a string, e.g. from a config file. In this case
+the check will also <em>convert</em> the value to the required type. This allows you
+to add validation as a transparent layer to access data stored as strings. The
+validation checks that the data is correct <em>and</em> converts it to the expected
+type.</p>
+<p>Checks are also strings, and are easy to write. One generic system can be used
+to validate information from different sources via a single consistent
+mechanism.</p>
+<p>Checks look like function calls, and map to function calls. They can include
+parameters and keyword arguments. These arguments are passed to the relevant
+function by the <tt class="docutils literal">Validator</tt> instance, along with the value being checked.</p>
+<p>The syntax for checks also allows for specifying a default value. This default
+value can be <tt class="docutils literal">None</tt>, no matter what the type of the check. This can be used
+to indicate that a value was missing, and so holds no useful value.</p>
+<p>Functions either return a new value, or raise an exception. See <a class="reference internal" href="#validator-exceptions">Validator
+Exceptions</a> for the low down on the exception classes that <tt class="docutils literal">validate.py</tt>
+defines.</p>
+<p>Some standard functions are provided, for basic data types; these come built
+into every validator. Additional checks are easy to write: they can be provided
+when the <tt class="docutils literal">Validator</tt> is instantiated, or added afterwards.</p>
+<p>Validate was primarily written to support <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj</a>, but is designed to be
+applicable to many other situations.</p>
+<p>For support and bug reports please use the ConfigObj <a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a>.</p>
+</div>
+<div class="section" id="downloading">
+<h1><a class="toc-backref" href="#id2">2&nbsp;&nbsp;&nbsp;Downloading</a></h1>
+<p>The current version is <strong>1.0.1</strong>, dated 9th January 2010.</p>
+<p>You can get obtain validate in the following ways :</p>
+<div class="section" id="files">
+<h2><a class="toc-backref" href="#id3">2.1&nbsp;&nbsp;&nbsp;Files</a></h2>
+<ul>
+<li><p class="first"><a class="reference external" href="http://www.voidspace.org.uk/cgi-bin/voidspace/download/validate.py">validate.py</a> from Voidspace</p>
+</li>
+<li><p class="first">configobj.zip from Voidspace - See the homepage of <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj</a> for the latest
+version and download links.</p>
+<blockquote>
+<p>This contains validate.py and <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">this document</a>. (As well as <a class="reference external" href="http://www.voidspace.org.uk/python/configobj.html">ConfigObj</a> and
+the ConfigObj documentation).</p>
+</blockquote>
+</li>
+<li><p class="first">The latest development version can be obtained from the <a class="reference external" href="http://code.google.com/p/configobj/">Subversion Repository</a>.</p>
+</li>
+</ul>
+</div>
+<div class="section" id="documentation">
+<h2><a class="toc-backref" href="#id4">2.2&nbsp;&nbsp;&nbsp;Documentation</a></h2>
+<p><em>configobj.zip</em> contains <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">this document</a>.</p>
+<ul class="simple">
+<li>You can view <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">this document</a> online as the <a class="reference external" href="http://www.voidspace.org.uk/python/validate.html">Validate Homepage</a>.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="the-standard-functions">
+<h1><a class="toc-backref" href="#id5">3&nbsp;&nbsp;&nbsp;The standard functions</a></h1>
+<p>The standard functions come built-in to every <tt class="docutils literal">Validator</tt> instance. They work
+with the following basic data types :</p>
+<ul class="simple">
+<li>integer</li>
+<li>float</li>
+<li>boolean</li>
+<li>string</li>
+<li>ip_addr</li>
+</ul>
+<p>plus lists of these datatypes.</p>
+<p>Adding additional checks is done through coding simple functions.</p>
+<p>The full set of standard checks are :</p>
+<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">'integer':</th><td class="field-body"><p class="first">matches integer values (including negative). Takes optional 'min'
+and 'max' arguments:</p>
+<pre class="literal-block">
+integer()
+integer(3, 9) # any value from 3 to 9
+integer(min=0) # any positive value
+integer(max=9)
+</pre>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'float':</th><td class="field-body"><p class="first">matches float values
+Has the same parameters as the integer check.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'boolean':</th><td class="field-body"><dl class="first docutils">
+<dt>matches boolean values: <tt class="docutils literal">True</tt> or <tt class="docutils literal">False</tt>.</dt>
+<dd><p class="first">Acceptable string values for True are:</p>
+<pre class="last literal-block">
+true, on, yes, 1
+</pre>
+</dd>
+</dl>
+<p>Acceptable string values for False are:</p>
+<pre class="literal-block">
+false, off, no, 0
+</pre>
+<p>Any other value raises an error.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'string':</th><td class="field-body"><p class="first">matches any string. Takes optional keyword args 'min' and 'max' to
+specify min and max length of string.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'ip_addr':</th><td class="field-body"><p class="first">matches an Internet Protocol address, v.4, represented by a
+dotted-quad string, i.e. '1.2.3.4'.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'list':</th><td class="field-body"><p class="first">matches any list. Takes optional keyword args 'min', and 'max' to
+specify min and max sizes of the list. The list checks always
+return a list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">force_list:</th><td class="field-body"><p class="first">matches any list, but if a single value is passed in will
+coerce it into a list containing that value. Useful for
+configobj if the user forgot the trailing comma to turn
+a single value into a list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'tuple':</th><td class="field-body"><p class="first">matches any list. This check returns a tuple rather than a list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'int_list':</th><td class="field-body"><p class="first">Matches a list of integers. Takes the same arguments as list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'float_list':</th><td class="field-body"><p class="first">Matches a list of floats. Takes the same arguments as list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'bool_list':</th><td class="field-body"><p class="first">Matches a list of boolean values. Takes the same arguments as
+list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'string_list':</th><td class="field-body"><p class="first">Matches a list of strings. Takes the same arguments as list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'ip_addr_list':</th><td class="field-body"><p class="first">Matches a list of IP addresses. Takes the same arguments as
+list.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'mixed_list':</th><td class="field-body"><p class="first">Matches a list with different types in specific positions.
+List size must match the number of arguments.</p>
+<p>Each position can be one of:</p>
+<pre class="literal-block">
+int, str, boolean, float, ip_addr
+</pre>
+<p>So to specify a list with two strings followed by two integers,
+you write the check as:</p>
+<pre class="literal-block">
+mixed_list(str, str, int, int)
+</pre>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'pass':</th><td class="field-body"><p class="first">matches everything: it never fails and the value is unchanged. It is
+also the default if no check is specified.</p>
+</td>
+</tr>
+<tr class="field"><th class="field-name">'option':</th><td class="field-body"><p class="first">matches any from a list of options.
+You specify this test with:</p>
+<pre class="last literal-block">
+option('option 1', 'option 2', 'option 3')
+</pre>
+</td>
+</tr>
+</tbody>
+</table>
+<p>The following code will work without you having to specifically add the
+functions yourself.</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="c">#</span>
+<span class="n">vtor</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+<span class="n">newval1</span> <span class="o">=</span> <span class="n">vtor</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="s">&#39;integer&#39;</span><span class="p">,</span> <span class="n">value1</span><span class="p">)</span>
+<span class="n">newval2</span> <span class="o">=</span> <span class="n">vtor</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="s">&#39;boolean&#39;</span><span class="p">,</span> <span class="n">value2</span><span class="p">)</span>
+<span class="c"># etc ...</span>
+</pre></div>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Of course, if these checks fail they raise exceptions. So you should wrap
+them in <tt class="docutils literal"><span class="pre">try...except</span></tt> blocks. Better still, use ConfigObj for a higher
+level interface.</p>
+</div>
+</div>
+<div class="section" id="using-validator">
+<h1><a class="toc-backref" href="#id6">4&nbsp;&nbsp;&nbsp;Using Validator</a></h1>
+<p>Using <tt class="docutils literal">Validator</tt> is very easy. It has one public attribute and one public
+method.</p>
+<p>Shown below are the different steps in using <tt class="docutils literal">Validator</tt>.</p>
+<p>The only additional thing you need to know, is about <a class="reference internal" href="#writing-check-functions">Writing check
+functions</a>.</p>
+<div class="section" id="instantiate">
+<h2><a class="toc-backref" href="#id7">4.1&nbsp;&nbsp;&nbsp;Instantiate</a></h2>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="n">vtor</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+</pre></div>
+<p>or even :</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="c">#</span>
+<span class="n">fdict</span> <span class="o">=</span> <span class="p">{</span>
+ <span class="s">&#39;check_name1&#39;</span><span class="p">:</span> <span class="n">function1</span><span class="p">,</span>
+ <span class="s">&#39;check_name2&#39;</span><span class="p">:</span> <span class="n">function2</span><span class="p">,</span>
+ <span class="s">&#39;check_name3&#39;</span><span class="p">:</span> <span class="n">function3</span><span class="p">,</span>
+<span class="p">}</span>
+<span class="c">#</span>
+<span class="n">vtor</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">(</span><span class="n">fdict</span><span class="p">)</span>
+</pre></div>
+<p>The second method adds a set of your functions as soon as your validator is
+created. They are stored in the <tt class="docutils literal">vtor.functions</tt> dictionary. The 'key' you
+give them in this dictionary is the name you use in your checks (not the
+original function name).</p>
+<p>Dictionary keys/functions you pass in can override the built-in ones if you
+want.</p>
+</div>
+<div class="section" id="adding-functions">
+<h2><a class="toc-backref" href="#id8">4.2&nbsp;&nbsp;&nbsp;Adding functions</a></h2>
+<p>The code shown above, for adding functions on instantiation, has exactly the
+same effect as the following code :</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span>
+<span class="c">#</span>
+<span class="n">vtor</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+<span class="n">vtor</span><span class="o">.</span><span class="n">functions</span><span class="p">[</span><span class="s">&#39;check_name1&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">function1</span>
+<span class="n">vtor</span><span class="o">.</span><span class="n">functions</span><span class="p">[</span><span class="s">&#39;check_name2&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">function2</span>
+<span class="n">vtor</span><span class="o">.</span><span class="n">functions</span><span class="p">[</span><span class="s">&#39;check_name3&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="n">function3</span>
+</pre></div>
+<p><tt class="docutils literal">vtor.functions</tt> is just a dictionary that maps names to functions, so we
+could also have called <tt class="docutils literal">vtor.functions.update(fdict)</tt>.</p>
+</div>
+<div class="section" id="writing-the-check">
+<h2><a class="toc-backref" href="#id9">4.3&nbsp;&nbsp;&nbsp;Writing the check</a></h2>
+<p>As we've heard, the checks map to the names in the <tt class="docutils literal">functions</tt> dictionary.
+You've got a full list of <a class="reference internal" href="#the-standard-functions">The standard functions</a> and the arguments they
+take.</p>
+<p>If you're using <tt class="docutils literal">Validator</tt> from ConfigObj, then your checks will look like:</p>
+<pre class="literal-block">
+keyword = int_list(max=6)
+</pre>
+<p>but the check part will be identical .</p>
+</div>
+<div class="section" id="the-check-method">
+<h2><a class="toc-backref" href="#id10">4.4&nbsp;&nbsp;&nbsp;The check method</a></h2>
+<p>If you're not using <tt class="docutils literal">Validator</tt> from ConfigObj, then you'll need to call the
+<tt class="docutils literal">check</tt> method yourself.</p>
+<p>If the check fails then it will raise an exception, so you'll want to trap
+that. Here's the basic example :</p>
+<div class="highlight"><pre><span class="kn">from</span> <span class="nn">validate</span> <span class="kn">import</span> <span class="n">Validator</span><span class="p">,</span> <span class="n">ValidateError</span>
+<span class="c">#</span>
+<span class="n">vtor</span> <span class="o">=</span> <span class="n">Validator</span><span class="p">()</span>
+<span class="n">check</span> <span class="o">=</span> <span class="s">&quot;integer(0, 9)&quot;</span>
+<span class="n">value</span> <span class="o">=</span> <span class="mi">3</span>
+<span class="k">try</span><span class="p">:</span>
+ <span class="n">newvalue</span> <span class="o">=</span> <span class="n">vtor</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">check</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
+<span class="k">except</span> <span class="n">ValidateError</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;Check Failed.&#39;</span>
+<span class="k">else</span><span class="p">:</span>
+ <span class="k">print</span> <span class="s">&#39;Check passed.&#39;</span>
+</pre></div>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p class="last">Although the value can be a string, if it represents a list it should
+already have been turned into a list of strings.</p>
+</div>
+<div class="section" id="default-values">
+<h3><a class="toc-backref" href="#id11">4.4.1&nbsp;&nbsp;&nbsp;Default Values</a></h3>
+<p>Some values may not be available, and you may want to be able to specify a
+default as part of the check.</p>
+<p>You do this by passing the keyword <tt class="docutils literal">missing=True</tt> to the <tt class="docutils literal">check</tt> method, as
+well as a <tt class="docutils literal">default=value</tt> in the check. (Constructing these checks is done
+automatically by ConfigObj: you only need to know about the <tt class="docutils literal">default=value</tt>
+part) :</p>
+<div class="highlight"><pre><span class="n">check1</span> <span class="o">=</span> <span class="s">&#39;integer(default=50)&#39;</span>
+<span class="n">check2</span> <span class="o">=</span> <span class="s">&#39;option(&quot;val 1&quot;, &quot;val 2&quot;, &quot;val 3&quot;, default=&quot;val 1&quot;)&#39;</span>
+
+<span class="k">assert</span> <span class="n">vtor</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">check1</span><span class="p">,</span> <span class="s">&#39;&#39;</span><span class="p">,</span> <span class="n">missing</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="o">==</span> <span class="mi">50</span>
+<span class="k">assert</span> <span class="n">vtor</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="n">check2</span><span class="p">,</span> <span class="s">&#39;&#39;</span><span class="p">,</span> <span class="n">missing</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="o">==</span> <span class="s">&quot;val 1&quot;</span>
+</pre></div>
+<p>If you pass in <tt class="docutils literal">missing=True</tt> to the check method, then the actual value is
+ignored. If no default is specified in the check, a <tt class="docutils literal">ValidateMissingValue</tt>
+exception is raised. If a default is specified then that is passed to the
+check instead.</p>
+<p>If the check has <tt class="docutils literal">default=None</tt> (case sensitive) then <tt class="docutils literal">vtor.check</tt> will
+<em>always</em> return <tt class="docutils literal">None</tt> (the object). This makes it easy to tell your program
+that this check contains no useful value when missing, i.e. the value is
+optional, and may be omitted without harm.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">As of version 0.3.0, if you specify <tt class="docutils literal"><span class="pre">default='None'</span></tt> (note the quote marks
+around <tt class="docutils literal">None</tt>) then it will be interpreted as the string <tt class="docutils literal">'None'</tt>.</p>
+</div>
+</div>
+<div class="section" id="list-values">
+<h3><a class="toc-backref" href="#id12">4.4.2&nbsp;&nbsp;&nbsp;List Values</a></h3>
+<p>It's possible that you would like your default value to be a list. It's even
+possible that you will write your own check functions - and would like to pass
+them keyword arguments as lists from within the check.</p>
+<p>To avoid confusing syntax with commas and quotes you use a list constructor to
+specify that keyword arguments are lists. This includes the <tt class="docutils literal">default</tt> value.
+This makes checks look something like:</p>
+<pre class="literal-block">
+checkname(default=list('val1', 'val2', 'val3'))
+</pre>
+</div>
+</div>
+<div class="section" id="get-default-value">
+<h2><a class="toc-backref" href="#id13">4.5&nbsp;&nbsp;&nbsp;get_default_value</a></h2>
+<p><tt class="docutils literal">Validator</tt> instances have a <tt class="docutils literal">get_default_value</tt> method. It takes a <tt class="docutils literal">check</tt> string
+(the same string you would pass to the <tt class="docutils literal">check</tt> method) and returns the default value,
+converted to the right type. If the check doesn't define a default value then this method
+raises a <tt class="docutils literal">KeyError</tt>.</p>
+<p>If the <tt class="docutils literal">check</tt> has been seen before then it will have been parsed and cached already,
+so this method is not expensive to call (however the conversion is done each time).</p>
+</div>
+</div>
+<div class="section" id="validator-exceptions">
+<h1><a class="toc-backref" href="#id14">5&nbsp;&nbsp;&nbsp;Validator Exceptions</a></h1>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">If you only use Validator through ConfigObj, it traps these Exceptions for
+you. You will still need to know about them for writing your own check
+functions.</p>
+</div>
+<p><tt class="docutils literal">vtor.check</tt> indicates that the check has failed by raising an exception.
+The appropriate error should be raised in the check function.</p>
+<p>The base error class is <tt class="docutils literal">ValidateError</tt>. All errors (except for <tt class="docutils literal">VdtParamError</tt>)
+raised are sub-classes of this.</p>
+<p>If an unrecognised check is specified then <tt class="docutils literal">VdtUnknownCheckError</tt> is
+raised.</p>
+<p>There are also <tt class="docutils literal">VdtTypeError</tt> and <tt class="docutils literal">VdtValueError</tt>.</p>
+<p>If incorrect parameters are passed to a check function then it will (or should)
+raise <tt class="docutils literal">VdtParamError</tt>. As this indicates <em>programmer</em> error, rather than an error
+in the value, it is a subclass of <tt class="docutils literal">SyntaxError</tt> instead of <tt class="docutils literal">ValidateError</tt>.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">This means it <em>won't</em> be caught by ConfigObj - but propagated instead.</p>
+</div>
+<p>If the value supplied is the wrong type, then the check should raise
+<tt class="docutils literal">VdtTypeError</tt>. e.g. the check requires the value to be an integer (or
+representation of an integer) and something else was supplied.</p>
+<p>If the value supplied is the right type, but an unacceptable value, then the
+check should raise <tt class="docutils literal">VdtValueError</tt>. e.g. the check requires the value to
+be an integer (or representation of an integer) less than ten and a higher
+value was supplied.</p>
+<p>Both <tt class="docutils literal">VdtTypeError</tt> and <tt class="docutils literal">VdtValueError</tt> are initialised with the
+incorrect value. In other words you raise them like this :</p>
+<div class="highlight"><pre><span class="k">raise</span> <span class="n">VdtTypeError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+<span class="c">#</span>
+<span class="k">raise</span> <span class="n">VdtValueError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+</pre></div>
+<p><tt class="docutils literal">VdtValueError</tt> has the following subclasses, which should be raised if
+they are more appropriate.</p>
+<ul class="simple">
+<li><tt class="docutils literal">VdtValueTooSmallError</tt></li>
+<li><tt class="docutils literal">VdtValueTooBigError</tt></li>
+<li><tt class="docutils literal">VdtValueTooShortError</tt></li>
+<li><tt class="docutils literal">VdtValueTooLongError</tt></li>
+</ul>
+</div>
+<div class="section" id="writing-check-functions">
+<h1><a class="toc-backref" href="#id15">6&nbsp;&nbsp;&nbsp;Writing check functions</a></h1>
+<p>Writing check functions is easy.</p>
+<p>The check function will receive the value as its first argument, followed by
+any other parameters and keyword arguments.</p>
+<p>If the check fails, it should raise a <tt class="docutils literal">VdtTypeError</tt> or a
+<tt class="docutils literal">VdtValueError</tt> (or an appropriate subclass).</p>
+<p>All parameters and keyword arguments are <em>always</em> passed as strings. (Parsed
+from the check string).</p>
+<p>The value might be a string (or list of strings) and need
+converting to the right type - alternatively it might already be a list of
+integers. Our function needs to be able to handle either.</p>
+<p>If the check passes then it should return the value (possibly converted to the
+right type).</p>
+<p>And that's it !</p>
+<div class="section" id="example">
+<h2><a class="toc-backref" href="#id16">6.1&nbsp;&nbsp;&nbsp;Example</a></h2>
+<p>Here is an example function that requires a list of integers. Each integer
+must be between 0 and 99.</p>
+<p>It takes a single argument specifying the length of the list. (Which allows us
+to use the same check in more than one place). If the length can't be converted
+to an integer then we need to raise <tt class="docutils literal">VdtParamError</tt>.</p>
+<p>Next we check that the value is a list. Anything else should raise a
+<tt class="docutils literal">VdtTypeError</tt>. The list should also have 'length' entries. If the list
+has more or less entries then we will need to raise a
+<tt class="docutils literal">VdtValueTooShortError</tt> or a <tt class="docutils literal">VdtValueTooLongError</tt>.</p>
+<p>Then we need to check every entry in the list. Each entry should be an integer
+between 0 and 99, or a string representation of an integer between 0 and 99.
+Any other type is a <tt class="docutils literal">VdtTypeError</tt>, any other value is a
+<tt class="docutils literal">VdtValueError</tt> (either too big, or too small).</p>
+<div class="highlight"><pre><span class="k">def</span> <span class="nf">special_list</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="n">length</span><span class="p">):</span>
+ <span class="sd">&quot;&quot;&quot;</span>
+<span class="sd"> Check that the supplied value is a list of integers,</span>
+<span class="sd"> with &#39;length&#39; entries, and each entry between 0 and 99.</span>
+<span class="sd"> &quot;&quot;&quot;</span>
+ <span class="c"># length is supplied as a string</span>
+ <span class="c"># we need to convert it to an integer</span>
+ <span class="k">try</span><span class="p">:</span>
+ <span class="n">length</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">length</span><span class="p">)</span>
+ <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
+ <span class="k">raise</span> <span class="n">VdtParamError</span><span class="p">(</span><span class="s">&#39;length&#39;</span><span class="p">,</span> <span class="n">length</span><span class="p">)</span>
+ <span class="c">#</span>
+ <span class="c"># Check the supplied value is a list</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">list</span><span class="p">):</span>
+ <span class="k">raise</span> <span class="n">VdtTypeError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="c">#</span>
+ <span class="c"># check the length of the list is correct</span>
+ <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">&gt;</span> <span class="n">length</span><span class="p">:</span>
+ <span class="k">raise</span> <span class="n">VdtValueTooLongError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="k">elif</span> <span class="nb">len</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">length</span><span class="p">:</span>
+ <span class="k">raise</span> <span class="n">VdtValueTooShortError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="c">#</span>
+ <span class="c"># Next, check every member in the list</span>
+ <span class="c"># converting strings as necessary</span>
+ <span class="n">out</span> <span class="o">=</span> <span class="p">[]</span>
+ <span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">value</span><span class="p">:</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">,</span> <span class="nb">int</span><span class="p">)):</span>
+ <span class="c"># a value in the list</span>
+ <span class="c"># is neither an integer nor a string</span>
+ <span class="k">raise</span> <span class="n">VdtTypeError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="k">elif</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">entry</span><span class="p">,</span> <span class="p">(</span><span class="nb">str</span><span class="p">,</span> <span class="nb">unicode</span><span class="p">)):</span>
+ <span class="k">if</span> <span class="ow">not</span> <span class="n">entry</span><span class="o">.</span><span class="n">isdigit</span><span class="p">():</span>
+ <span class="k">raise</span> <span class="n">VdtTypeError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="k">else</span><span class="p">:</span>
+ <span class="n">entry</span> <span class="o">=</span> <span class="nb">int</span><span class="p">(</span><span class="n">entry</span><span class="p">)</span>
+ <span class="k">if</span> <span class="n">entry</span> <span class="o">&lt;</span> <span class="mi">0</span><span class="p">:</span>
+ <span class="k">raise</span> <span class="n">VdtValueTooSmallError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="k">elif</span> <span class="n">entry</span> <span class="o">&gt;</span> <span class="mi">99</span><span class="p">:</span>
+ <span class="k">raise</span> <span class="n">VdtValueTooBigError</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
+ <span class="n">out</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">entry</span><span class="p">)</span>
+ <span class="c">#</span>
+ <span class="c"># if we got this far, all is well</span>
+ <span class="c"># return the new list</span>
+ <span class="k">return</span> <span class="n">out</span>
+</pre></div>
+<p>If you are only using validate from ConfigObj then the error type (<em>TooBig</em>,
+<em>TooSmall</em>, etc) is lost - so you may only want to raise <tt class="docutils literal">VdtValueError</tt>.</p>
+<div class="caution">
+<p class="first admonition-title">Caution!</p>
+<p>If your function raises an exception that isn't a subclass of
+<tt class="docutils literal">ValidateError</tt>, then ConfigObj won't trap it. This means validation will
+fail.</p>
+<p class="last">This is why our function starts by checking the type of the value. If we
+are passed the wrong type (e.g. an integer rather than a list) we get a
+<tt class="docutils literal">VdtTypeError</tt> rather than bombing out when we try to iterate over
+the value.</p>
+</div>
+<p>If you are using validate in another circumstance you may want to create your
+own subclasses of <tt class="docutils literal">ValidateError</tt> which convey more specific information.</p>
+</div>
+</div>
+<div class="section" id="known-issues">
+<h1><a class="toc-backref" href="#id17">7&nbsp;&nbsp;&nbsp;Known Issues</a></h1>
+<p>The following parses and then blows up. The resulting error message
+is confusing:</p>
+<blockquote>
+<tt class="docutils literal">checkname(default=list(1, 2, 3, 4)</tt></blockquote>
+<p>This is because it parses as: <tt class="docutils literal"><span class="pre">checkname(default=&quot;list(1&quot;,</span> 2, 3, 4)</tt>.
+That isn't actually unreasonable, but the error message won't help you
+work out what has happened.</p>
+</div>
+<div class="section" id="todo">
+<h1><a class="toc-backref" href="#id18">8&nbsp;&nbsp;&nbsp;TODO</a></h1>
+<ul class="simple">
+<li>A regex check function ?</li>
+<li>A timestamp check function ? (Using the <tt class="docutils literal">parse</tt> function from <tt class="docutils literal">DateUtil</tt> perhaps).</li>
+</ul>
+</div>
+<div class="section" id="issues">
+<h1><a class="toc-backref" href="#id19">9&nbsp;&nbsp;&nbsp;ISSUES</a></h1>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">Please file any bug reports to <a class="reference external" href="mailto:fuzzyman&#37;&#52;&#48;voidspace&#46;org&#46;uk">Michael Foord</a> or the ConfigObj
+<a class="reference external" href="http://lists.sourceforge.net/lists/listinfo/configobj-develop">Mailing List</a>.</p>
+</div>
+<p>If we could pull tuples out of arguments, it would be easier
+to specify arguments for 'mixed_lists'.</p>
+</div>
+<div class="section" id="changelog">
+<h1><a class="toc-backref" href="#id20">10&nbsp;&nbsp;&nbsp;CHANGELOG</a></h1>
+<div class="section" id="version-1-0-1">
+<h2><a class="toc-backref" href="#id21">10.1&nbsp;&nbsp;&nbsp;2009/10/25 - Version 1.0.1</a></h2>
+<ul class="simple">
+<li>BUGFIX: Fixed compatibility with Python 2.3.</li>
+</ul>
+</div>
+<div class="section" id="version-1-0-0">
+<h2><a class="toc-backref" href="#id22">10.2&nbsp;&nbsp;&nbsp;2009/04/13 - Version 1.0.0</a></h2>
+<ul class="simple">
+<li>BUGFIX: can now handle multiline strings.</li>
+<li>Addition of 'force_list' validation option.</li>
+</ul>
+<p>As the API is stable and there are no known bugs or outstanding feature requests I am marking this 1.0.</p>
+</div>
+<div class="section" id="version-0-3-2">
+<h2><a class="toc-backref" href="#id23">10.3&nbsp;&nbsp;&nbsp;2008/02/24 - Version 0.3.2</a></h2>
+<p>BUGFIX: Handling of None as default value fixed.</p>
+</div>
+<div class="section" id="version-0-3-1">
+<h2><a class="toc-backref" href="#id24">10.4&nbsp;&nbsp;&nbsp;2008/02/05 - Version 0.3.1</a></h2>
+<p>BUGFIX: Unicode checks no longer broken.</p>
+</div>
+<div class="section" id="version-0-3-0">
+<h2><a class="toc-backref" href="#id25">10.5&nbsp;&nbsp;&nbsp;2008/02/05 - Version 0.3.0</a></h2>
+<p>Improved performance with a parse cache.</p>
+<p>New <tt class="docutils literal">get_default_value</tt> method. Given a check it returns the default
+value (converted to the correct type) or raises a <tt class="docutils literal">KeyError</tt> if the
+check doesn't specify a default.</p>
+<p>Added 'tuple' check and corresponding 'is_tuple' function (which always returns a tuple).</p>
+<p>BUGFIX: A quoted 'None' as a default value is no longer treated as None,
+but as the string 'None'.</p>
+<p>BUGFIX: We weren't unquoting keyword arguments of length two, so an
+empty string didn't work as a default.</p>
+<p>BUGFIX: Strings no longer pass the 'is_list' check. Additionally, the
+list checks always return lists.</p>
+<p>A couple of documentation bug fixes.</p>
+<p>Removed CHANGELOG from module.</p>
+</div>
+<div class="section" id="version-0-2-3">
+<h2><a class="toc-backref" href="#id26">10.6&nbsp;&nbsp;&nbsp;2007/02/04 Version 0.2.3</a></h2>
+<p>Release of 0.2.3</p>
+</div>
+<div class="section" id="version-0-2-3-alpha1">
+<h2><a class="toc-backref" href="#id27">10.7&nbsp;&nbsp;&nbsp;2006/12/17 Version 0.2.3-alpha1</a></h2>
+<p>By Nicola Larosa</p>
+<p>Fixed validate doc to talk of <tt class="docutils literal">boolean</tt> instead of <tt class="docutils literal">bool</tt>; changed the
+<tt class="docutils literal">is_bool</tt> function to <tt class="docutils literal">is_boolean</tt> (Sourceforge bug #1531525).</p>
+</div>
+<div class="section" id="version-0-2-2">
+<h2><a class="toc-backref" href="#id28">10.8&nbsp;&nbsp;&nbsp;2006/04/29 Version 0.2.2</a></h2>
+<p>Addressed bug where a string would pass the <tt class="docutils literal">is_list</tt> test. (Thanks to
+Konrad Wojas.)</p>
+</div>
+<div class="section" id="version-0-2-1">
+<h2><a class="toc-backref" href="#id29">10.9&nbsp;&nbsp;&nbsp;2005/12/16 Version 0.2.1</a></h2>
+<p>Fixed bug so we can handle keyword argument values with commas.</p>
+<p>We now use a list constructor for passing list values to keyword arguments
+(including <tt class="docutils literal">default</tt>):</p>
+<pre class="literal-block">
+default=list(&quot;val&quot;, &quot;val&quot;, &quot;val&quot;)
+</pre>
+<p>Added the <tt class="docutils literal">_test</tt> test.</p>
+<p>Moved a function call outside a try...except block.</p>
+</div>
+<div class="section" id="version-0-2-0">
+<h2><a class="toc-backref" href="#id30">10.10&nbsp;&nbsp;&nbsp;2005/08/18 Version 0.2.0</a></h2>
+<p>Updated by <a class="reference external" href="mailto:fuzzyman&#37;&#52;&#48;voidspace&#46;org&#46;uk">Michael Foord</a> and <a class="reference external" href="mailto:nico&#37;&#52;&#48;teknico&#46;net">Nicola Larosa</a></p>
+<p>Does type conversion as well.</p>
+</div>
+<div class="section" id="version-0-1-0">
+<h2><a class="toc-backref" href="#id31">10.11&nbsp;&nbsp;&nbsp;2005/02/01 Version 0.1.0</a></h2>
+<p>Initial version developed by <a class="reference external" href="mailto:fuzzyman&#37;&#52;&#48;voidspace&#46;org&#46;uk">Michael Foord</a>
+and Mark Andrews.</p>
+</div>
+</div>
+</div>
+</body>
+</html>
diff --git a/docs/voidspace_docutils.css b/docs/voidspace_docutils.css
new file mode 100644
index 0000000..4a626f1
--- /dev/null
+++ b/docs/voidspace_docutils.css
@@ -0,0 +1,141 @@
+/*
+:Authors: Ian Bicking, Michael Foord
+:Contact: fuzzyman@voidspace.org.uk
+:Date: 2005/08/26
+:Version: 0.1.0
+:Copyright: This stylesheet has been placed in the public domain.
+
+Stylesheet for Docutils.
+Based on ``blue_box.css`` by Ian Bicking
+and ``default.css`` revision 3442
+*/
+
+@import url(default.css);
+@import url(pysrc.css);
+
+body {
+ font-family: Arial, sans-serif;
+}
+
+em, i {
+ /* Typically serif fonts have much nicer italics */
+ font-family: Times New Roman, Times, serif;
+}
+
+
+a.target {
+ color: blue;
+}
+
+a.toc-backref {
+ text-decoration: none;
+ color: black;
+}
+
+a.toc-backref:hover {
+ background-color: inherit;
+}
+
+a:hover {
+ background-color: #cccccc;
+}
+
+div.attention, div.caution, div.danger, div.error, div.hint,
+div.important, div.note, div.tip, div.warning {
+ background-color: #cccccc;
+ padding: 3px;
+ width: 80%;
+}
+
+div.admonition p.admonition-title, div.hint p.admonition-title,
+div.important p.admonition-title, div.note p.admonition-title,
+div.tip p.admonition-title {
+ text-align: center;
+ background-color: #999999;
+ display: block;
+ margin: 0;
+}
+
+div.attention p.admonition-title, div.caution p.admonition-title,
+div.danger p.admonition-title, div.error p.admonition-title,
+div.warning p.admonition-title {
+ color: #cc0000;
+ font-family: sans-serif;
+ text-align: center;
+ background-color: #999999;
+ display: block;
+ margin: 0;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ font-family: Helvetica, Arial, sans-serif;
+ border: thin solid black;
+ /* This makes the borders rounded on Mozilla, which pleases me */
+ -moz-border-radius: 8px;
+ padding: 4px;
+}
+
+h1 {
+ background-color: #444499;
+ color: #ffffff;
+ border: medium solid black;
+}
+
+h1 a.toc-backref, h2 a.toc-backref {
+ color: #ffffff;
+}
+
+h2 {
+ background-color: #666666;
+ color: #ffffff;
+ border: medium solid black;
+}
+
+h3, h4, h5, h6 {
+ background-color: #cccccc;
+ color: #000000;
+}
+
+h3 a.toc-backref, h4 a.toc-backref, h5 a.toc-backref,
+h6 a.toc-backref {
+ color: #000000;
+}
+
+h1.title {
+ text-align: center;
+ background-color: #444499;
+ color: #eeeeee;
+ border: thick solid black;
+ -moz-border-radius: 20px;
+}
+
+table.footnote {
+ padding-left: 0.5ex;
+}
+
+table.citation {
+ padding-left: 0.5ex
+}
+
+pre.literal-block, pre.doctest-block {
+ border: thin black solid;
+ padding: 5px;
+}
+
+.image img { border-style : solid;
+ border-width : 2px;
+}
+
+img.align-center {
+ display: block;
+ margin: auto;
+ text-align: center;
+}
+
+h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
+ font-size: 100%;
+}
+
+code, tt {
+ color: #000066;
+}