diff options
| author | fuzzyman <devnull@localhost> | 2010-01-09 20:35:14 +0000 |
|---|---|---|
| committer | fuzzyman <devnull@localhost> | 2010-01-09 20:35:14 +0000 |
| commit | be6d95eebe622b5dd5fd1b8025d4b013e3175928 (patch) | |
| tree | 7fab57824e47cdc656bc2e45b42d76ded2b261a5 /docs | |
| parent | 52e42f1993ba545e62f1604932d7ec5bbeb8b654 (diff) | |
| download | configobj-git-be6d95eebe622b5dd5fd1b8025d4b013e3175928.tar.gz | |
Adding more files for building docs.
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/configobj.html | 2614 | ||||
| -rw-r--r-- | docs/configobj.txt | 11 | ||||
| -rw-r--r-- | docs/default.css | 293 | ||||
| -rw-r--r-- | docs/docutils.conf | 3 | ||||
| -rw-r--r-- | docs/template.tmp | 8 | ||||
| -rw-r--r-- | docs/validate.html | 639 | ||||
| -rw-r--r-- | docs/voidspace_docutils.css | 141 |
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 Introduction</a></li> +<li><a class="reference internal" href="#downloading" id="id28">2 Downloading</a><ul class="auto-toc"> +<li><a class="reference internal" href="#installing" id="id29">2.1 Installing</a></li> +<li><a class="reference internal" href="#documentation" id="id30">2.2 Documentation</a></li> +<li><a class="reference internal" href="#development-version" id="id31">2.3 Development Version</a></li> +</ul> +</li> +<li><a class="reference internal" href="#configobj-in-the-real-world" id="id32">3 ConfigObj in the Real World</a></li> +<li><a class="reference internal" href="#getting-started" id="id33">4 Getting Started</a><ul class="auto-toc"> +<li><a class="reference internal" href="#reading-a-config-file" id="id34">4.1 Reading a Config File</a></li> +<li><a class="reference internal" href="#writing-a-config-file" id="id35">4.2 Writing a Config File</a></li> +<li><a class="reference internal" href="#config-files" id="id36">4.3 Config Files</a></li> +</ul> +</li> +<li><a class="reference internal" href="#configobj-specifications" id="id37">5 ConfigObj specifications</a><ul class="auto-toc"> +<li><a class="reference internal" href="#methods" id="id38">5.1 Methods</a><ul class="auto-toc"> +<li><a class="reference internal" href="#write" id="id39">5.1.1 write</a></li> +<li><a class="reference internal" href="#validate" id="id40">5.1.2 validate</a><ul class="auto-toc"> +<li><a class="reference internal" href="#return-value" id="id41">5.1.2.1 Return Value</a></li> +<li><a class="reference internal" href="#mentioning-default-values" id="id42">5.1.2.2 Mentioning Default Values</a></li> +<li><a class="reference internal" href="#mentioning-repeated-sections-and-values" id="id43">5.1.2.3 Mentioning Repeated Sections and Values</a></li> +<li><a class="reference internal" href="#mentioning-simpleval" id="id44">5.1.2.4 Mentioning SimpleVal</a></li> +<li><a class="reference internal" href="#mentioning-copy-mode" id="id45">5.1.2.5 Mentioning copy Mode</a></li> +</ul> +</li> +<li><a class="reference internal" href="#reload" id="id46">5.1.3 reload</a></li> +<li><a class="reference internal" href="#reset" id="id47">5.1.4 reset</a></li> +</ul> +</li> +<li><a class="reference internal" href="#attributes" id="id48">5.2 Attributes</a><ul class="auto-toc"> +<li><a class="reference internal" href="#interpolation" id="id49">5.2.1 interpolation</a></li> +<li><a class="reference internal" href="#stringify" id="id50">5.2.2 stringify</a></li> +<li><a class="reference internal" href="#bom" id="id51">5.2.3 BOM</a></li> +<li><a class="reference internal" href="#initial-comment" id="id52">5.2.4 initial_comment</a></li> +<li><a class="reference internal" href="#final-comment" id="id53">5.2.5 final_comment</a></li> +<li><a class="reference internal" href="#list-values" id="id54">5.2.6 list_values</a></li> +<li><a class="reference internal" href="#encoding" id="id55">5.2.7 encoding</a></li> +<li><a class="reference internal" href="#default-encoding" id="id56">5.2.8 default_encoding</a></li> +<li><a class="reference internal" href="#unrepr" id="id57">5.2.9 unrepr</a></li> +<li><a class="reference internal" href="#write-empty-values" id="id58">5.2.10 write_empty_values</a></li> +<li><a class="reference internal" href="#newlines" id="id59">5.2.11 newlines</a></li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#the-config-file-format" id="id60">6 The Config File Format</a></li> +<li><a class="reference internal" href="#sections" id="id61">7 Sections</a><ul class="auto-toc"> +<li><a class="reference internal" href="#section-attributes" id="id62">7.1 Section Attributes</a></li> +<li><a class="reference internal" href="#section-methods" id="id63">7.2 Section Methods</a></li> +<li><a class="reference internal" href="#walking-a-section" id="id64">7.3 Walking a Section</a></li> +<li><a class="reference internal" href="#examples" id="id65">7.4 Examples</a></li> +</ul> +</li> +<li><a class="reference internal" href="#exceptions" id="id66">8 Exceptions</a></li> +<li><a class="reference internal" href="#validation" id="id67">9 Validation</a><ul class="auto-toc"> +<li><a class="reference internal" href="#configspec" id="id68">9.1 configspec</a></li> +<li><a class="reference internal" href="#type-conversion" id="id69">9.2 Type Conversion</a></li> +<li><a class="reference internal" href="#default-values" id="id70">9.3 Default Values</a><ul class="auto-toc"> +<li><a class="reference internal" href="#id13" id="id71">9.3.1 List Values</a></li> +</ul> +</li> +<li><a class="reference internal" href="#repeated-sections" id="id72">9.4 Repeated Sections</a></li> +<li><a class="reference internal" href="#repeated-values" id="id73">9.5 Repeated Values</a></li> +<li><a class="reference internal" href="#copy-mode" id="id74">9.6 Copy Mode</a></li> +<li><a class="reference internal" href="#validation-and-interpolation" id="id75">9.7 Validation and Interpolation</a></li> +<li><a class="reference internal" href="#extra-values" id="id76">9.8 Extra Values</a></li> +<li><a class="reference internal" href="#simpleval" id="id77">9.9 SimpleVal</a></li> +</ul> +</li> +<li><a class="reference internal" href="#empty-values" id="id78">10 Empty values</a></li> +<li><a class="reference internal" href="#unrepr-mode" id="id79">11 unrepr mode</a></li> +<li><a class="reference internal" href="#string-interpolation" id="id80">12 String Interpolation</a></li> +<li><a class="reference internal" href="#comments" id="id81">13 Comments</a></li> +<li><a class="reference internal" href="#flatten-errors" id="id82">14 flatten_errors</a><ul class="auto-toc"> +<li><a class="reference internal" href="#example-usage" id="id83">14.1 Example Usage</a></li> +</ul> +</li> +<li><a class="reference internal" href="#get-extra-values" id="id84">15 get_extra_values</a><ul class="auto-toc"> +<li><a class="reference internal" href="#id14" id="id85">15.1 Example Usage</a></li> +</ul> +</li> +<li><a class="reference internal" href="#credits" id="id86">16 CREDITS</a></li> +<li><a class="reference internal" href="#license" id="id87">17 LICENSE</a></li> +<li><a class="reference internal" href="#todo" id="id88">18 TODO</a></li> +<li><a class="reference internal" href="#issues" id="id89">19 ISSUES</a></li> +<li><a class="reference internal" href="#changelog" id="id90">20 CHANGELOG</a><ul class="auto-toc"> +<li><a class="reference internal" href="#version-4-7-0" id="id91">20.1 20010/01/09 - Version 4.7.0</a></li> +<li><a class="reference internal" href="#version-4-6-0" id="id92">20.2 2009/04/13 - Version 4.6.0</a></li> +<li><a class="reference internal" href="#version-4-5-3" id="id93">20.3 2008/06/27 - Version 4.5.3</a></li> +<li><a class="reference internal" href="#version-4-5-2" id="id94">20.4 2008/02/05 - Version 4.5.2</a></li> +<li><a class="reference internal" href="#version-4-5-1" id="id95">20.5 2008/02/05 - Version 4.5.1</a></li> +<li><a class="reference internal" href="#version-4-5-0" id="id96">20.6 2008/02/05 - Version 4.5.0</a></li> +<li><a class="reference internal" href="#version-4-4-0" id="id97">20.7 2007/02/04 - Version 4.4.0</a></li> +<li><a class="reference internal" href="#version-4-3-3-alpha4" id="id98">20.8 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 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 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 2006/12/09 - Version 4.3.3-alpha1</a></li> +<li><a class="reference internal" href="#version-4-3-2" id="id102">20.12 2006/06/04 - Version 4.3.2</a></li> +<li><a class="reference internal" href="#version-4-3-1" id="id103">20.13 2006/04/29 - Version 4.3.1</a></li> +<li><a class="reference internal" href="#version-4-3-0" id="id104">20.14 2006/03/24 - Version 4.3.0</a></li> +<li><a class="reference internal" href="#version-4-2-0" id="id105">20.15 2006/02/16 - Version 4.2.0</a></li> +<li><a class="reference internal" href="#version-4-1-0" id="id106">20.16 2005/12/14 - Version 4.1.0</a></li> +<li><a class="reference internal" href="#version-4-0-2" id="id107">20.17 2005/12/02 - Version 4.0.2</a></li> +<li><a class="reference internal" href="#version-4-0-1" id="id108">20.18 2005/11/05 - Version 4.0.1</a></li> +<li><a class="reference internal" href="#version-4-0-0" id="id109">20.19 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 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 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 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 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 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 2004/05/24 - Version 3.0.0</a></li> +<li><a class="reference internal" href="#version-2-0-0-beta" id="id116">20.26 2004/03/14 - Version 2.0.0 beta</a></li> +<li><a class="reference internal" href="#version-1-0-5" id="id117">20.27 2004/01/29 - Version 1.0.5</a></li> +<li><a class="reference internal" href="#origins" id="id118">20.28 Origins</a></li> +</ul> +</li> +<li><a class="reference internal" href="#footnotes" id="id119">21 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 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 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 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 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 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 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 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 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">'keyword1'</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">'keyword2'</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">'section1'</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">'keyword3'</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">'keyword4'</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">'section1'</span><span class="p">][</span><span class="s">'keyword3'</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">'section1'</span><span class="p">][</span><span class="s">'keyword4'</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 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">'keyword1'</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">'keyword2'</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">'section1'</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">'section1'</span><span class="p">][</span><span class="s">'keyword3'</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">'section1'</span><span class="p">][</span><span class="s">'keyword4'</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">'keyword5'</span><span class="p">:</span> <span class="n">value5</span><span class="p">,</span> + <span class="s">'keyword6'</span><span class="p">:</span> <span class="n">value6</span><span class="p">,</span> + <span class="s">'sub-section'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword7'</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">'section2'</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">'section3'</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">'section3'</span><span class="p">][</span><span class="s">'keyword 8'</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">'section3'</span><span class="p">][</span><span class="s">'keyword 9'</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 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' + +[ "section 1" ] +# 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 "section 1" + '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 = "value 9" +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 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">' '</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">' '</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 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 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 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">'Succeeded.'</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">'UTF8'</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 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 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 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 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">'Succeeded.'</span> +</pre></div> +</div> +<div class="section" id="mentioning-copy-mode"> +<h4><a class="toc-backref" href="#id45">5.1.2.5 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 "afraid".''' +# +keyword3 = """ A multi line value +on several +lines""" # with a comment +keyword4 = """I won't be "afraid".""" +</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 +[ "section name 2" ] # 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">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</span><span class="p">,</span> + <span class="s">'section 1'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</span><span class="p">,</span> + <span class="s">'sub-section'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</span><span class="p">,</span> + <span class="s">'nested section'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</span><span class="p">,</span> + <span class="p">},</span> + <span class="p">},</span> + <span class="s">'sub-section2'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</span><span class="p">,</span> + <span class="p">},</span> + <span class="s">'sub-section3'</span><span class="p">:</span> <span class="p">{</span> + <span class="s">'keyword1'</span><span class="p">:</span> <span class="s">'value1'</span><span class="p">,</span> + <span class="s">'keyword2'</span><span class="p">:</span> <span class="s">'value2'</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 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">'key1'</span><span class="p">:</span> <span class="s">'value 1'</span><span class="p">,</span> + <span class="s">'key2'</span><span class="p">:</span> <span class="s">'value 2'</span> + <span class="p">}</span> +<span class="n">config</span><span class="p">[</span><span class="s">'vals'</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">'vals'</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">'vals'</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 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 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">"""</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">"""</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 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 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">"""</span> +<span class="sd"> A function to encode or decode using the 'string-escape' 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"> """</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 > 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'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">'string-escape'</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">'string-escape'</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'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'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">'string-escape'</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">'string-escape'</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'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 'XXXX' as a placeholder</span> +<span class="n">config</span> <span class="o">=</span> <span class="s">'''</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">'''</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">'XXXX'</span><span class="p">,</span> <span class="s">'CLIENT1'</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">'XXXX'</span><span class="p">,</span> <span class="s">'CLIENT1'</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">'CLIENT1key1'</span><span class="p">:</span> <span class="s">'CLIENT1value1'</span><span class="p">,</span> <span class="s">'CLIENT1key2'</span><span class="p">:</span> <span class="s">'CLIENT1value2'</span><span class="p">,</span> +<span class="s">'CLIENT1key3'</span><span class="p">:</span> <span class="s">'CLIENT1value3'</span><span class="p">,</span> +<span class="s">'CLIENT1section1'</span><span class="p">:</span> <span class="p">{</span><span class="s">'CLIENT1key1'</span><span class="p">:</span> <span class="s">'CLIENT1value1'</span><span class="p">,</span> + <span class="s">'CLIENT1key2'</span><span class="p">:</span> <span class="s">'CLIENT1value2'</span><span class="p">,</span> <span class="s">'CLIENT1key3'</span><span class="p">:</span> <span class="s">'CLIENT1value3'</span><span class="p">},</span> +<span class="s">'CLIENT1section2'</span><span class="p">:</span> <span class="p">{</span><span class="s">'CLIENT1key1'</span><span class="p">:</span> <span class="s">'CLIENT1value1'</span><span class="p">,</span> + <span class="s">'CLIENT1key2'</span><span class="p">:</span> <span class="s">'CLIENT1value2'</span><span class="p">,</span> <span class="s">'CLIENT1key3'</span><span class="p">:</span> <span class="s">'CLIENT1value3'</span><span class="p">,</span> + <span class="s">'CLIENT1section1'</span><span class="p">:</span> <span class="p">{</span><span class="s">'CLIENT1key1'</span><span class="p">:</span> <span class="s">'CLIENT1value1'</span><span class="p">,</span> + <span class="s">'CLIENT1key2'</span><span class="p">:</span> <span class="s">'CLIENT1value2'</span><span class="p">,</span> <span class="s">'CLIENT1key3'</span><span class="p">:</span> <span class="s">'CLIENT1value3'</span><span class="p">}}})</span> +</pre></div> +</div> +</div> +<div class="section" id="exceptions"> +<h1><a class="toc-backref" href="#id66">8 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 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 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">'UTF8'</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 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 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 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 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 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 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">'default.ini'</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">'new_default.ini'</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 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 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 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">'All values present.'</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">'No values present!'</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">'"</span><span class="si">%s</span><span class="s">" missing.'</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 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">'''</span> +<span class="s"> key =</span> +<span class="s"> key2 = # a comment</span> +<span class="s">'''</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">'key'</span><span class="p">:</span> <span class="s">''</span><span class="p">,</span> <span class="s">'key2'</span><span class="p">:</span> <span class="s">''</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 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">"Must be quoted."</tt></div> +<div class="line">Backslash : <tt class="docutils literal">"The backslash must be escaped \\"</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 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 +"ConfigParser" or "Template" (case-insensitive, so "configparser" and +"template" 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 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 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 "3" is of the wrong type</em>.</blockquote> +<div class="section" id="example-usage"> +<h2><a class="toc-backref" href="#id83">14.1 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">'[missing section]'</span><span class="p">)</span> + <span class="n">section_string</span> <span class="o">=</span> <span class="s">', '</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">'Missing value or section.'</span> + <span class="k">print</span> <span class="n">section_string</span><span class="p">,</span> <span class="s">' = '</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 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 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">'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">'section'</span> + + <span class="n">section_string</span> <span class="o">=</span> <span class="s">', '</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">"top level"</span> + <span class="k">print</span> <span class="s">'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">'</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 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 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 & 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 +"AS IS" 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 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 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 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 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. "value = 1, , 2"</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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 Introduction</a></li> +<li><a class="reference internal" href="#downloading" id="id2">2 Downloading</a><ul class="auto-toc"> +<li><a class="reference internal" href="#files" id="id3">2.1 Files</a></li> +<li><a class="reference internal" href="#documentation" id="id4">2.2 Documentation</a></li> +</ul> +</li> +<li><a class="reference internal" href="#the-standard-functions" id="id5">3 The standard functions</a></li> +<li><a class="reference internal" href="#using-validator" id="id6">4 Using Validator</a><ul class="auto-toc"> +<li><a class="reference internal" href="#instantiate" id="id7">4.1 Instantiate</a></li> +<li><a class="reference internal" href="#adding-functions" id="id8">4.2 Adding functions</a></li> +<li><a class="reference internal" href="#writing-the-check" id="id9">4.3 Writing the check</a></li> +<li><a class="reference internal" href="#the-check-method" id="id10">4.4 The check method</a><ul class="auto-toc"> +<li><a class="reference internal" href="#default-values" id="id11">4.4.1 Default Values</a></li> +<li><a class="reference internal" href="#list-values" id="id12">4.4.2 List Values</a></li> +</ul> +</li> +<li><a class="reference internal" href="#get-default-value" id="id13">4.5 get_default_value</a></li> +</ul> +</li> +<li><a class="reference internal" href="#validator-exceptions" id="id14">5 Validator Exceptions</a></li> +<li><a class="reference internal" href="#writing-check-functions" id="id15">6 Writing check functions</a><ul class="auto-toc"> +<li><a class="reference internal" href="#example" id="id16">6.1 Example</a></li> +</ul> +</li> +<li><a class="reference internal" href="#known-issues" id="id17">7 Known Issues</a></li> +<li><a class="reference internal" href="#todo" id="id18">8 TODO</a></li> +<li><a class="reference internal" href="#issues" id="id19">9 ISSUES</a></li> +<li><a class="reference internal" href="#changelog" id="id20">10 CHANGELOG</a><ul class="auto-toc"> +<li><a class="reference internal" href="#version-1-0-1" id="id21">10.1 2009/10/25 - Version 1.0.1</a></li> +<li><a class="reference internal" href="#version-1-0-0" id="id22">10.2 2009/04/13 - Version 1.0.0</a></li> +<li><a class="reference internal" href="#version-0-3-2" id="id23">10.3 2008/02/24 - Version 0.3.2</a></li> +<li><a class="reference internal" href="#version-0-3-1" id="id24">10.4 2008/02/05 - Version 0.3.1</a></li> +<li><a class="reference internal" href="#version-0-3-0" id="id25">10.5 2008/02/05 - Version 0.3.0</a></li> +<li><a class="reference internal" href="#version-0-2-3" id="id26">10.6 2007/02/04 Version 0.2.3</a></li> +<li><a class="reference internal" href="#version-0-2-3-alpha1" id="id27">10.7 2006/12/17 Version 0.2.3-alpha1</a></li> +<li><a class="reference internal" href="#version-0-2-2" id="id28">10.8 2006/04/29 Version 0.2.2</a></li> +<li><a class="reference internal" href="#version-0-2-1" id="id29">10.9 2005/12/16 Version 0.2.1</a></li> +<li><a class="reference internal" href="#version-0-2-0" id="id30">10.10 2005/08/18 Version 0.2.0</a></li> +<li><a class="reference internal" href="#version-0-1-0" id="id31">10.11 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 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 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 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 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 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">'integer'</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">'boolean'</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 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 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">'check_name1'</span><span class="p">:</span> <span class="n">function1</span><span class="p">,</span> + <span class="s">'check_name2'</span><span class="p">:</span> <span class="n">function2</span><span class="p">,</span> + <span class="s">'check_name3'</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 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">'check_name1'</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">'check_name2'</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">'check_name3'</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 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 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">"integer(0, 9)"</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">'Check Failed.'</span> +<span class="k">else</span><span class="p">:</span> + <span class="k">print</span> <span class="s">'Check passed.'</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 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">'integer(default=50)'</span> +<span class="n">check2</span> <span class="o">=</span> <span class="s">'option("val 1", "val 2", "val 3", default="val 1")'</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">''</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">''</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">"val 1"</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 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 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 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 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 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">"""</span> +<span class="sd"> Check that the supplied value is a list of integers,</span> +<span class="sd"> with 'length' entries, and each entry between 0 and 99.</span> +<span class="sd"> """</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">'length'</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">></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"><</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"><</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">></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 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="list(1",</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 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 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%40voidspace.org.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 CHANGELOG</a></h1> +<div class="section" id="version-1-0-1"> +<h2><a class="toc-backref" href="#id21">10.1 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 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 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 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 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 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 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 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 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("val", "val", "val") +</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 2005/08/18 Version 0.2.0</a></h2> +<p>Updated by <a class="reference external" href="mailto:fuzzyman%40voidspace.org.uk">Michael Foord</a> and <a class="reference external" href="mailto:nico%40teknico.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 2005/02/01 Version 0.1.0</a></h2> +<p>Initial version developed by <a class="reference external" href="mailto:fuzzyman%40voidspace.org.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; +} |