1442 lines
136 KiB
HTML
1442 lines
136 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>configparser — Configuration file parser — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="netrc — netrc file processing" href="netrc.html" />
|
||
<link rel="prev" title="csv — CSV File Reading and Writing" href="csv.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/configparser.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="netrc.html" title="netrc — netrc file processing"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="csv.html" title="csv — CSV File Reading and Writing"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" accesskey="U">File Formats</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-configparser">
|
||
<span id="configparser-configuration-file-parser"></span><h1><a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> — Configuration file parser<a class="headerlink" href="#module-configparser" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/configparser.py">Lib/configparser.py</a></p>
|
||
<hr class="docutils" id="index-0" />
|
||
<p>This module provides the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> class which implements a basic
|
||
configuration language which provides a structure similar to what’s found in
|
||
Microsoft Windows INI files. You can use this to write Python programs which
|
||
can be customized by end users easily.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>This library does <em>not</em> interpret or write the value-type prefixes used in
|
||
the Windows Registry extended version of INI syntax.</p>
|
||
</div>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt>Module <a class="reference internal" href="shlex.html#module-shlex" title="shlex: Simple lexical analysis for Unix shell-like languages."><code class="xref py py-mod docutils literal notranslate"><span class="pre">shlex</span></code></a></dt><dd><p>Support for creating Unix shell-like mini-languages which can be used as
|
||
an alternate format for application configuration files.</p>
|
||
</dd>
|
||
<dt>Module <a class="reference internal" href="json.html#module-json" title="json: Encode and decode the JSON format."><code class="xref py py-mod docutils literal notranslate"><span class="pre">json</span></code></a></dt><dd><p>The json module implements a subset of JavaScript syntax which can also
|
||
be used for this purpose.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="quick-start">
|
||
<h2>Quick Start<a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
|
||
<p>Let’s take a very basic configuration file that looks like this:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[DEFAULT]</span>
|
||
<span class="na">ServerAliveInterval</span> <span class="o">=</span> <span class="s">45</span>
|
||
<span class="na">Compression</span> <span class="o">=</span> <span class="s">yes</span>
|
||
<span class="na">CompressionLevel</span> <span class="o">=</span> <span class="s">9</span>
|
||
<span class="na">ForwardX11</span> <span class="o">=</span> <span class="s">yes</span>
|
||
|
||
<span class="k">[bitbucket.org]</span>
|
||
<span class="na">User</span> <span class="o">=</span> <span class="s">hg</span>
|
||
|
||
<span class="k">[topsecret.server.com]</span>
|
||
<span class="na">Port</span> <span class="o">=</span> <span class="s">50022</span>
|
||
<span class="na">ForwardX11</span> <span class="o">=</span> <span class="s">no</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The structure of INI files is described <a class="reference external" href="#supported-ini-file-structure">in the following section</a>. Essentially, the file
|
||
consists of sections, each of which contains keys with values.
|
||
<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> classes can read and write such files. Let’s start by
|
||
creating the above configuration file programmatically.</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'ServerAliveInterval'</span><span class="p">:</span> <span class="s1">'45'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'Compression'</span><span class="p">:</span> <span class="s1">'yes'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'CompressionLevel'</span><span class="p">:</span> <span class="s1">'9'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">][</span><span class="s1">'User'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'hg'</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.com'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{}</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.com'</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'50022'</span> <span class="c1"># mutates the parser</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'ForwardX11'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'no'</span> <span class="c1"># same here</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'ForwardX11'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'yes'</span>
|
||
<span class="gp">>>> </span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'example.ini'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As you can see, we can treat a config parser much like a dictionary.
|
||
There are differences, <a class="reference external" href="#mapping-protocol-access">outlined later</a>, but
|
||
the behavior is very close to what you would expect from a dictionary.</p>
|
||
<p>Now that we have created and saved a configuration file, let’s read it
|
||
back and explore the data it holds.</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">[]</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.ini'</span><span class="p">)</span>
|
||
<span class="go">['example.ini']</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['bitbucket.org', 'topsecret.server.com']</span>
|
||
<span class="gp">>>> </span><span class="s1">'bitbucket.org'</span> <span class="ow">in</span> <span class="n">config</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="s1">'bytebong.com'</span> <span class="ow">in</span> <span class="n">config</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">][</span><span class="s1">'User'</span><span class="p">]</span>
|
||
<span class="go">'hg'</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'Compression'</span><span class="p">]</span>
|
||
<span class="go">'yes'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span> <span class="o">=</span> <span class="n">config</span><span class="p">[</span><span class="s1">'topsecret.server.com'</span><span class="p">]</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'ForwardX11'</span><span class="p">]</span>
|
||
<span class="go">'no'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">]</span>
|
||
<span class="go">'50022'</span>
|
||
<span class="gp">>>> </span><span class="k">for</span> <span class="n">key</span> <span class="ow">in</span> <span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">]:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
|
||
<span class="go">user</span>
|
||
<span class="go">compressionlevel</span>
|
||
<span class="go">serveraliveinterval</span>
|
||
<span class="go">compression</span>
|
||
<span class="go">forwardx11</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">][</span><span class="s1">'ForwardX11'</span><span class="p">]</span>
|
||
<span class="go">'yes'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As we can see above, the API is pretty straightforward. The only bit of magic
|
||
involves the <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> section which provides default values for all other
|
||
sections <a class="footnote-reference brackets" href="#id14" id="id1">1</a>. Note also that keys in sections are
|
||
case-insensitive and stored in lowercase <a class="footnote-reference brackets" href="#id14" id="id2">1</a>.</p>
|
||
</div>
|
||
<div class="section" id="supported-datatypes">
|
||
<h2>Supported Datatypes<a class="headerlink" href="#supported-datatypes" title="Permalink to this headline">¶</a></h2>
|
||
<p>Config parsers do not guess datatypes of values in configuration files, always
|
||
storing them internally as strings. This means that if you need other
|
||
datatypes, you should convert on your own:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="nb">int</span><span class="p">(</span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'Port'</span><span class="p">])</span>
|
||
<span class="go">50022</span>
|
||
<span class="gp">>>> </span><span class="nb">float</span><span class="p">(</span><span class="n">topsecret</span><span class="p">[</span><span class="s1">'CompressionLevel'</span><span class="p">])</span>
|
||
<span class="go">9.0</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Since this task is so common, config parsers provide a range of handy getter
|
||
methods to handle integers, floats and booleans. The last one is the most
|
||
interesting because simply passing the value to <code class="docutils literal notranslate"><span class="pre">bool()</span></code> would do no good
|
||
since <code class="docutils literal notranslate"><span class="pre">bool('False')</span></code> is still <code class="docutils literal notranslate"><span class="pre">True</span></code>. This is why config parsers also
|
||
provide <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>. This method is case-insensitive and
|
||
recognizes Boolean values from <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>/<code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'on'</span></code>/<code class="docutils literal notranslate"><span class="pre">'off'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'true'</span></code>/<code class="docutils literal notranslate"><span class="pre">'false'</span></code> and <code class="docutils literal notranslate"><span class="pre">'1'</span></code>/<code class="docutils literal notranslate"><span class="pre">'0'</span></code> <a class="footnote-reference brackets" href="#id14" id="id3">1</a>. For example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'ForwardX11'</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'bitbucket.org'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'ForwardX11'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'bitbucket.org'</span><span class="p">,</span> <span class="s1">'Compression'</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Apart from <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>, config parsers also
|
||
provide equivalent <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a> and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a> methods. You can register your own
|
||
converters and customize the provided ones. <a class="footnote-reference brackets" href="#id14" id="id4">1</a></p>
|
||
</div>
|
||
<div class="section" id="fallback-values">
|
||
<h2>Fallback Values<a class="headerlink" href="#fallback-values" title="Permalink to this headline">¶</a></h2>
|
||
<p>As with a dictionary, you can use a section’s <code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> method to
|
||
provide fallback values:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Port'</span><span class="p">)</span>
|
||
<span class="go">'50022'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'CompressionLevel'</span><span class="p">)</span>
|
||
<span class="go">'9'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Cipher'</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Cipher'</span><span class="p">,</span> <span class="s1">'3des-cbc'</span><span class="p">)</span>
|
||
<span class="go">'3des-cbc'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Please note that default values have precedence over fallback values.
|
||
For instance, in our example the <code class="docutils literal notranslate"><span class="pre">'CompressionLevel'</span></code> key was
|
||
specified only in the <code class="docutils literal notranslate"><span class="pre">'DEFAULT'</span></code> section. If we try to get it from
|
||
the section <code class="docutils literal notranslate"><span class="pre">'topsecret.server.com'</span></code>, we will always get the default,
|
||
even if we specify a fallback:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'CompressionLevel'</span><span class="p">,</span> <span class="s1">'3'</span><span class="p">)</span>
|
||
<span class="go">'9'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>One more thing to be aware of is that the parser-level <code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> method
|
||
provides a custom, more complex interface, maintained for backwards
|
||
compatibility. When using this method, a fallback value can be provided via
|
||
the <code class="docutils literal notranslate"><span class="pre">fallback</span></code> keyword-only argument:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'bitbucket.org'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'No such things as monsters'</span><span class="p">)</span>
|
||
<span class="go">'No such things as monsters'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The same <code class="docutils literal notranslate"><span class="pre">fallback</span></code> argument can be used with the
|
||
<a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a>, <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a> and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a> methods, for example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="s1">'BatchMode'</span> <span class="ow">in</span> <span class="n">topsecret</span>
|
||
<span class="go">False</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'BatchMode'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">True</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s1">'DEFAULT'</span><span class="p">][</span><span class="s1">'BatchMode'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'no'</span>
|
||
<span class="gp">>>> </span><span class="n">topsecret</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'BatchMode'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="supported-ini-file-structure">
|
||
<h2>Supported INI File Structure<a class="headerlink" href="#supported-ini-file-structure" title="Permalink to this headline">¶</a></h2>
|
||
<p>A configuration file consists of sections, each led by a <code class="docutils literal notranslate"><span class="pre">[section]</span></code> header,
|
||
followed by key/value entries separated by a specific string (<code class="docutils literal notranslate"><span class="pre">=</span></code> or <code class="docutils literal notranslate"><span class="pre">:</span></code> by
|
||
default <a class="footnote-reference brackets" href="#id14" id="id5">1</a>). By default, section names are case sensitive but keys are not
|
||
<a class="footnote-reference brackets" href="#id14" id="id6">1</a>. Leading and trailing whitespace is removed from keys and values.
|
||
Values can be omitted, in which case the key/value delimiter may also be left
|
||
out. Values can also span multiple lines, as long as they are indented deeper
|
||
than the first line of the value. Depending on the parser’s mode, blank lines
|
||
may be treated as parts of multiline values or ignored.</p>
|
||
<p>Configuration files may include comments, prefixed by specific
|
||
characters (<code class="docutils literal notranslate"><span class="pre">#</span></code> and <code class="docutils literal notranslate"><span class="pre">;</span></code> by default <a class="footnote-reference brackets" href="#id14" id="id7">1</a>). Comments may appear on
|
||
their own on an otherwise empty line, possibly indented. <a class="footnote-reference brackets" href="#id14" id="id8">1</a></p>
|
||
<p>For example:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Simple Values]</span>
|
||
<span class="na">key</span><span class="o">=</span><span class="s">value</span>
|
||
<span class="na">spaces in keys</span><span class="o">=</span><span class="s">allowed</span>
|
||
<span class="na">spaces in values</span><span class="o">=</span><span class="s">allowed as well</span>
|
||
<span class="na">spaces around the delimiter</span> <span class="o">=</span> <span class="s">obviously</span>
|
||
<span class="na">you can also use : to delimit keys from values</span>
|
||
|
||
<span class="k">[All Values Are Strings]</span>
|
||
<span class="na">values like this: 1000000</span>
|
||
<span class="na">or this: 3.14159265359</span>
|
||
<span class="na">are they treated as numbers? : no</span>
|
||
<span class="na">integers, floats and booleans are held as: strings</span>
|
||
<span class="na">can use the API to get converted values directly: true</span>
|
||
|
||
<span class="k">[Multiline Values]</span>
|
||
<span class="na">chorus: I'm a lumberjack, and I'm okay</span>
|
||
<span class="na">I sleep all night and I work all day</span>
|
||
|
||
<span class="k">[No Values]</span>
|
||
<span class="na">key_without_value</span>
|
||
<span class="na">empty string value here</span> <span class="o">=</span>
|
||
|
||
<span class="k">[You can use comments]</span>
|
||
<span class="c1"># like this</span>
|
||
<span class="c1">; or this</span>
|
||
|
||
<span class="c1"># By default only in an empty line.</span>
|
||
<span class="c1"># Inline comments can be harmful because they prevent users</span>
|
||
<span class="c1"># from using the delimiting characters as parts of values.</span>
|
||
<span class="c1"># That being said, this can be customized.</span>
|
||
|
||
<span class="k">[Sections Can Be Indented]</span>
|
||
<span class="na">can_values_be_as_well</span> <span class="o">=</span> <span class="s">True</span>
|
||
<span class="s"> does_that_mean_anything_special = False</span>
|
||
<span class="s"> purpose = formatting for readability</span>
|
||
<span class="s"> multiline_values = are</span>
|
||
<span class="s"> handled just fine as</span>
|
||
<span class="s"> long as they are indented</span>
|
||
<span class="s"> deeper than the first line</span>
|
||
<span class="s"> of a value</span>
|
||
<span class="s"> # Did I mention we can indent comments, too?</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="interpolation-of-values">
|
||
<h2>Interpolation of values<a class="headerlink" href="#interpolation-of-values" title="Permalink to this headline">¶</a></h2>
|
||
<p>On top of the core functionality, <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> supports
|
||
interpolation. This means values can be preprocessed before returning them
|
||
from <code class="docutils literal notranslate"><span class="pre">get()</span></code> calls.</p>
|
||
<span class="target" id="index-1"></span><dl class="class">
|
||
<dt id="configparser.BasicInterpolation">
|
||
<em class="property">class </em><code class="descclassname">configparser.</code><code class="descname">BasicInterpolation</code><a class="headerlink" href="#configparser.BasicInterpolation" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The default implementation used by <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>. It enables
|
||
values to contain format strings which refer to other values in the same
|
||
section, or values in the special default section <a class="footnote-reference brackets" href="#id14" id="id9">1</a>. Additional default
|
||
values can be provided on initialization.</p>
|
||
<p>For example:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Paths]</span>
|
||
<span class="na">home_dir: /Users</span>
|
||
<span class="na">my_dir: %(home_dir)s/lumberjack</span>
|
||
<span class="na">my_pictures: %(my_dir)s/Pictures</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the example above, <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> with <em>interpolation</em> set to
|
||
<code class="docutils literal notranslate"><span class="pre">BasicInterpolation()</span></code> would resolve <code class="docutils literal notranslate"><span class="pre">%(home_dir)s</span></code> to the value of
|
||
<code class="docutils literal notranslate"><span class="pre">home_dir</span></code> (<code class="docutils literal notranslate"><span class="pre">/Users</span></code> in this case). <code class="docutils literal notranslate"><span class="pre">%(my_dir)s</span></code> in effect would
|
||
resolve to <code class="docutils literal notranslate"><span class="pre">/Users/lumberjack</span></code>. All interpolations are done on demand so
|
||
keys used in the chain of references do not have to be specified in any
|
||
specific order in the configuration file.</p>
|
||
<p>With <code class="docutils literal notranslate"><span class="pre">interpolation</span></code> set to <code class="docutils literal notranslate"><span class="pre">None</span></code>, the parser would simply return
|
||
<code class="docutils literal notranslate"><span class="pre">%(my_dir)s/Pictures</span></code> as the value of <code class="docutils literal notranslate"><span class="pre">my_pictures</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">%(home_dir)s/lumberjack</span></code> as the value of <code class="docutils literal notranslate"><span class="pre">my_dir</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-2"></span><dl class="class">
|
||
<dt id="configparser.ExtendedInterpolation">
|
||
<em class="property">class </em><code class="descclassname">configparser.</code><code class="descname">ExtendedInterpolation</code><a class="headerlink" href="#configparser.ExtendedInterpolation" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An alternative handler for interpolation which implements a more advanced
|
||
syntax, used for instance in <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. Extended interpolation is
|
||
using <code class="docutils literal notranslate"><span class="pre">${section:option}</span></code> to denote a value from a foreign section.
|
||
Interpolation can span multiple levels. For convenience, if the
|
||
<code class="docutils literal notranslate"><span class="pre">section:</span></code> part is omitted, interpolation defaults to the current section
|
||
(and possibly the default values from the special section).</p>
|
||
<p>For example, the configuration specified above with basic interpolation,
|
||
would look like this with extended interpolation:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Paths]</span>
|
||
<span class="na">home_dir: /Users</span>
|
||
<span class="na">my_dir: ${home_dir}/lumberjack</span>
|
||
<span class="na">my_pictures: ${my_dir}/Pictures</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Values from other sections can be fetched as well:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Common]</span>
|
||
<span class="na">home_dir: /Users</span>
|
||
<span class="na">library_dir: /Library</span>
|
||
<span class="na">system_dir: /System</span>
|
||
<span class="na">macports_dir: /opt/local</span>
|
||
|
||
<span class="k">[Frameworks]</span>
|
||
<span class="na">Python: 3.2</span>
|
||
<span class="na">path: ${Common:system_dir}/Library/Frameworks/</span>
|
||
|
||
<span class="k">[Arthur]</span>
|
||
<span class="na">nickname: Two Sheds</span>
|
||
<span class="na">last_name: Jackson</span>
|
||
<span class="na">my_dir: ${Common:home_dir}/twosheds</span>
|
||
<span class="na">my_pictures: ${my_dir}/Pictures</span>
|
||
<span class="na">python_dir: ${Frameworks:path}/Python/Versions/${Frameworks:Python}</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="mapping-protocol-access">
|
||
<h2>Mapping Protocol Access<a class="headerlink" href="#mapping-protocol-access" title="Permalink to this headline">¶</a></h2>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
<p>Mapping protocol access is a generic name for functionality that enables using
|
||
custom objects as if they were dictionaries. In case of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>,
|
||
the mapping interface implementation is using the
|
||
<code class="docutils literal notranslate"><span class="pre">parser['section']['option']</span></code> notation.</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">parser['section']</span></code> in particular returns a proxy for the section’s data in
|
||
the parser. This means that the values are not copied but they are taken from
|
||
the original parser on demand. What’s even more important is that when values
|
||
are changed on a section proxy, they are actually mutated in the original
|
||
parser.</p>
|
||
<p><a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> objects behave as close to actual dictionaries as possible.
|
||
The mapping interface is complete and adheres to the
|
||
<a class="reference internal" href="collections.abc.html#collections.abc.MutableMapping" title="collections.abc.MutableMapping"><code class="xref py py-class docutils literal notranslate"><span class="pre">MutableMapping</span></code></a> ABC.
|
||
However, there are a few differences that should be taken into account:</p>
|
||
<ul>
|
||
<li><p>By default, all keys in sections are accessible in a case-insensitive manner
|
||
<a class="footnote-reference brackets" href="#id14" id="id10">1</a>. E.g. <code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">option</span> <span class="pre">in</span> <span class="pre">parser["section"]</span></code> yields only <code class="docutils literal notranslate"><span class="pre">optionxform</span></code>’ed
|
||
option key names. This means lowercased keys by default. At the same time,
|
||
for a section that holds the key <code class="docutils literal notranslate"><span class="pre">'a'</span></code>, both expressions return <code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="s2">"a"</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s2">"section"</span><span class="p">]</span>
|
||
<span class="s2">"A"</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s2">"section"</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>All sections include <code class="docutils literal notranslate"><span class="pre">DEFAULTSECT</span></code> values as well which means that
|
||
<code class="docutils literal notranslate"><span class="pre">.clear()</span></code> on a section may not leave the section visibly empty. This is
|
||
because default values cannot be deleted from the section (because technically
|
||
they are not there). If they are overridden in the section, deleting causes
|
||
the default value to be visible again. Trying to delete a default value
|
||
causes a <a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">DEFAULTSECT</span></code> cannot be removed from the parser:</p>
|
||
<ul class="simple">
|
||
<li><p>trying to delete it raises <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.clear()</span></code> leaves it intact,</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.popitem()</span></code> never returns it.</p></li>
|
||
</ul>
|
||
</li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.get(section,</span> <span class="pre">option,</span> <span class="pre">**kwargs)</span></code> - the second argument is <strong>not</strong>
|
||
a fallback value. Note however that the section-level <code class="docutils literal notranslate"><span class="pre">get()</span></code> methods are
|
||
compatible both with the mapping protocol and the classic configparser API.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">parser.items()</span></code> is compatible with the mapping protocol (returns a list of
|
||
<em>section_name</em>, <em>section_proxy</em> pairs including the DEFAULTSECT). However,
|
||
this method can also be invoked with arguments: <code class="docutils literal notranslate"><span class="pre">parser.items(section,</span> <span class="pre">raw,</span>
|
||
<span class="pre">vars)</span></code>. The latter call returns a list of <em>option</em>, <em>value</em> pairs for
|
||
a specified <code class="docutils literal notranslate"><span class="pre">section</span></code>, with all interpolations expanded (unless
|
||
<code class="docutils literal notranslate"><span class="pre">raw=True</span></code> is provided).</p></li>
|
||
</ul>
|
||
<p>The mapping protocol is implemented on top of the existing legacy API so that
|
||
subclasses overriding the original interface still should have mappings working
|
||
as expected.</p>
|
||
</div>
|
||
<div class="section" id="customizing-parser-behaviour">
|
||
<h2>Customizing Parser Behaviour<a class="headerlink" href="#customizing-parser-behaviour" title="Permalink to this headline">¶</a></h2>
|
||
<p>There are nearly as many INI format variants as there are applications using it.
|
||
<a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> goes a long way to provide support for the largest sensible
|
||
set of INI styles available. The default functionality is mainly dictated by
|
||
historical background and it’s very likely that you will want to customize some
|
||
of the features.</p>
|
||
<p>The most common way to change the way a specific config parser works is to use
|
||
the <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> options:</p>
|
||
<ul>
|
||
<li><p><em>defaults</em>, default value: <code class="docutils literal notranslate"><span class="pre">None</span></code></p>
|
||
<p>This option accepts a dictionary of key-value pairs which will be initially
|
||
put in the <code class="docutils literal notranslate"><span class="pre">DEFAULT</span></code> section. This makes for an elegant way to support
|
||
concise configuration files that don’t specify values which are the same as
|
||
the documented default.</p>
|
||
<p>Hint: if you want to specify default values for a specific section, use
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code> before you read the actual file.</p>
|
||
</li>
|
||
<li><p><em>dict_type</em>, default value: <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.OrderedDict</span></code></a></p>
|
||
<p>This option has a major impact on how the mapping protocol will behave and how
|
||
the written configuration files look. With the default ordered
|
||
dictionary, every section is stored in the order they were added to the
|
||
parser. Same goes for options within sections.</p>
|
||
<p>An alternative dictionary type can be used for example to sort sections and
|
||
options on write-back. You can also use a regular dictionary for performance
|
||
reasons.</p>
|
||
<p>Please note: there are ways to add a set of key-value pairs in a single
|
||
operation. When you use a regular dictionary in those operations, the order
|
||
of the keys will be ordered because dict preserves order from Python 3.7.
|
||
For example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">read_dict</span><span class="p">({</span><span class="s1">'section1'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'key1'</span><span class="p">:</span> <span class="s1">'value1'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'key2'</span><span class="p">:</span> <span class="s1">'value2'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'key3'</span><span class="p">:</span> <span class="s1">'value3'</span><span class="p">},</span>
|
||
<span class="gp">... </span> <span class="s1">'section2'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'keyA'</span><span class="p">:</span> <span class="s1">'valueA'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'keyB'</span><span class="p">:</span> <span class="s1">'valueB'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'keyC'</span><span class="p">:</span> <span class="s1">'valueC'</span><span class="p">},</span>
|
||
<span class="gp">... </span> <span class="s1">'section3'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'foo'</span><span class="p">:</span> <span class="s1">'x'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'y'</span><span class="p">,</span>
|
||
<span class="gp">... </span> <span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'z'</span><span class="p">}</span>
|
||
<span class="gp">... </span><span class="p">})</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['section1', 'section2', 'section3']</span>
|
||
<span class="gp">>>> </span><span class="p">[</span><span class="n">option</span> <span class="k">for</span> <span class="n">option</span> <span class="ow">in</span> <span class="n">parser</span><span class="p">[</span><span class="s1">'section3'</span><span class="p">]]</span>
|
||
<span class="go">['foo', 'bar', 'baz']</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>allow_no_value</em>, default value: <code class="docutils literal notranslate"><span class="pre">False</span></code></p>
|
||
<p>Some configuration files are known to include settings without values, but
|
||
which otherwise conform to the syntax supported by <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>. The
|
||
<em>allow_no_value</em> parameter to the constructor can be used to
|
||
indicate that such values should be accepted:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
|
||
<span class="gp">>>> </span><span class="n">sample_config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[mysqld]</span>
|
||
<span class="gp">... </span><span class="s2"> user = mysql</span>
|
||
<span class="gp">... </span><span class="s2"> pid-file = /var/run/mysqld/mysqld.pid</span>
|
||
<span class="gp">... </span><span class="s2"> skip-external-locking</span>
|
||
<span class="gp">... </span><span class="s2"> old_passwords = 1</span>
|
||
<span class="gp">... </span><span class="s2"> skip-bdb</span>
|
||
<span class="gp">... </span><span class="s2"> # we don't need ACID today</span>
|
||
<span class="gp">... </span><span class="s2"> skip-innodb</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">(</span><span class="n">allow_no_value</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">sample_config</span><span class="p">)</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings with values are treated as before:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"user"</span><span class="p">]</span>
|
||
<span class="go">'mysql'</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings without values provide None:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"skip-bdb"</span><span class="p">]</span>
|
||
|
||
<span class="gp">>>> </span><span class="c1"># Settings which aren't specified still raise an error:</span>
|
||
<span class="gp">>>> </span><span class="n">config</span><span class="p">[</span><span class="s2">"mysqld"</span><span class="p">][</span><span class="s2">"does-not-exist"</span><span class="p">]</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="c">...</span>
|
||
<span class="gr">KeyError</span>: <span class="n">'does-not-exist'</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>delimiters</em>, default value: <code class="docutils literal notranslate"><span class="pre">('=',</span> <span class="pre">':')</span></code></p>
|
||
<p>Delimiters are substrings that delimit keys from values within a section.
|
||
The first occurrence of a delimiting substring on a line is considered
|
||
a delimiter. This means values (but not keys) can contain the delimiters.</p>
|
||
<p>See also the <em>space_around_delimiters</em> argument to
|
||
<a class="reference internal" href="#configparser.ConfigParser.write" title="configparser.ConfigParser.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ConfigParser.write()</span></code></a>.</p>
|
||
</li>
|
||
<li><p><em>comment_prefixes</em>, default value: <code class="docutils literal notranslate"><span class="pre">('#',</span> <span class="pre">';')</span></code></p></li>
|
||
<li><p><em>inline_comment_prefixes</em>, default value: <code class="docutils literal notranslate"><span class="pre">None</span></code></p>
|
||
<p>Comment prefixes are strings that indicate the start of a valid comment within
|
||
a config file. <em>comment_prefixes</em> are used only on otherwise empty lines
|
||
(optionally indented) whereas <em>inline_comment_prefixes</em> can be used after
|
||
every valid value (e.g. section names, options and empty lines as well). By
|
||
default inline comments are disabled and <code class="docutils literal notranslate"><span class="pre">'#'</span></code> and <code class="docutils literal notranslate"><span class="pre">';'</span></code> are used as
|
||
prefixes for whole line comments.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> behaviour matched
|
||
<code class="docutils literal notranslate"><span class="pre">comment_prefixes=('#',';')</span></code> and <code class="docutils literal notranslate"><span class="pre">inline_comment_prefixes=(';',)</span></code>.</p>
|
||
</div>
|
||
<p>Please note that config parsers don’t support escaping of comment prefixes so
|
||
using <em>inline_comment_prefixes</em> may prevent users from specifying option
|
||
values with characters used as comment prefixes. When in doubt, avoid
|
||
setting <em>inline_comment_prefixes</em>. In any circumstances, the only way of
|
||
storing comment prefix characters at the beginning of a line in multiline
|
||
values is to interpolate the prefix, for example:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">configparser</span> <span class="k">import</span> <span class="n">ConfigParser</span><span class="p">,</span> <span class="n">ExtendedInterpolation</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span> <span class="o">=</span> <span class="n">ConfigParser</span><span class="p">(</span><span class="n">interpolation</span><span class="o">=</span><span class="n">ExtendedInterpolation</span><span class="p">())</span>
|
||
<span class="gp">>>> </span><span class="c1"># the default BasicInterpolation could be used as well</span>
|
||
<span class="gp">>>> </span><span class="n">parser</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[DEFAULT]</span>
|
||
<span class="gp">... </span><span class="s2">hash = #</span>
|
||
<span class="gp">...</span><span class="s2"></span>
|
||
<span class="gp">... </span><span class="s2">[hashes]</span>
|
||
<span class="gp">... </span><span class="s2">shebang =</span>
|
||
<span class="gp">... </span><span class="s2"> $</span><span class="si">{hash}</span><span class="s2">!/usr/bin/env python</span>
|
||
<span class="gp">... </span><span class="s2"> $</span><span class="si">{hash}</span><span class="s2"> -*- coding: utf-8 -*-</span>
|
||
<span class="gp">...</span><span class="s2"></span>
|
||
<span class="gp">... </span><span class="s2">extensions =</span>
|
||
<span class="gp">... </span><span class="s2"> enabled_extension</span>
|
||
<span class="gp">... </span><span class="s2"> another_extension</span>
|
||
<span class="gp">... </span><span class="s2"> #disabled_by_comment</span>
|
||
<span class="gp">... </span><span class="s2"> yet_another_extension</span>
|
||
<span class="gp">...</span><span class="s2"></span>
|
||
<span class="gp">... </span><span class="s2">interpolation not necessary = if # is not at line start</span>
|
||
<span class="gp">... </span><span class="s2">even in multiline values = line #1</span>
|
||
<span class="gp">... </span><span class="s2"> line #2</span>
|
||
<span class="gp">... </span><span class="s2"> line #3</span>
|
||
<span class="gp">... </span><span class="s2">"""</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'shebang'</span><span class="p">])</span>
|
||
|
||
<span class="go">#!/usr/bin/env python</span>
|
||
<span class="go"># -*- coding: utf-8 -*-</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'extensions'</span><span class="p">])</span>
|
||
|
||
<span class="go">enabled_extension</span>
|
||
<span class="go">another_extension</span>
|
||
<span class="go">yet_another_extension</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'interpolation not necessary'</span><span class="p">])</span>
|
||
<span class="go">if # is not at line start</span>
|
||
<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">parser</span><span class="p">[</span><span class="s1">'hashes'</span><span class="p">][</span><span class="s1">'even in multiline values'</span><span class="p">])</span>
|
||
<span class="go">line #1</span>
|
||
<span class="go">line #2</span>
|
||
<span class="go">line #3</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p><em>strict</em>, default value: <code class="docutils literal notranslate"><span class="pre">True</span></code></p>
|
||
<p>When set to <code class="docutils literal notranslate"><span class="pre">True</span></code>, the parser will not allow for any section or option
|
||
duplicates while reading from a single source (using <code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code>,
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">read_string()</span></code> or <code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code>). It is recommended to use strict
|
||
parsers in new applications.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>In previous versions of <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> behaviour matched
|
||
<code class="docutils literal notranslate"><span class="pre">strict=False</span></code>.</p>
|
||
</div>
|
||
</li>
|
||
<li><p><em>empty_lines_in_values</em>, default value: <code class="docutils literal notranslate"><span class="pre">True</span></code></p>
|
||
<p>In config parsers, values can span multiple lines as long as they are
|
||
indented more than the key that holds them. By default parsers also let
|
||
empty lines to be parts of values. At the same time, keys can be arbitrarily
|
||
indented themselves to improve readability. In consequence, when
|
||
configuration files get big and complex, it is easy for the user to lose
|
||
track of the file structure. Take for instance:</p>
|
||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Section]</span>
|
||
<span class="na">key</span> <span class="o">=</span> <span class="s">multiline</span>
|
||
<span class="s"> value with a gotcha</span>
|
||
|
||
<span class="na">this</span> <span class="o">=</span> <span class="s">is still a part of the multiline value of 'key'</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This can be especially problematic for the user to see if she’s using a
|
||
proportional font to edit the file. That is why when your application does
|
||
not need values with empty lines, you should consider disallowing them. This
|
||
will make empty lines split keys every time. In the example above, it would
|
||
produce two keys, <code class="docutils literal notranslate"><span class="pre">key</span></code> and <code class="docutils literal notranslate"><span class="pre">this</span></code>.</p>
|
||
</li>
|
||
<li><p><em>default_section</em>, default value: <code class="docutils literal notranslate"><span class="pre">configparser.DEFAULTSECT</span></code> (that is:
|
||
<code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code>)</p>
|
||
<p>The convention of allowing a special section of default values for other
|
||
sections or interpolation purposes is a powerful concept of this library,
|
||
letting users create complex declarative configurations. This section is
|
||
normally called <code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code> but this can be customized to point to any
|
||
other valid section name. Some typical values include: <code class="docutils literal notranslate"><span class="pre">"general"</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">"common"</span></code>. The name provided is used for recognizing default sections
|
||
when reading from any source and is used when writing configuration back to
|
||
a file. Its current value can be retrieved using the
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance.default_section</span></code> attribute and may be modified at runtime
|
||
(i.e. to convert files from one format to another).</p>
|
||
</li>
|
||
<li><p><em>interpolation</em>, default value: <code class="docutils literal notranslate"><span class="pre">configparser.BasicInterpolation</span></code></p>
|
||
<p>Interpolation behaviour may be customized by providing a custom handler
|
||
through the <em>interpolation</em> argument. <code class="docutils literal notranslate"><span class="pre">None</span></code> can be used to turn off
|
||
interpolation completely, <code class="docutils literal notranslate"><span class="pre">ExtendedInterpolation()</span></code> provides a more
|
||
advanced variant inspired by <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. More on the subject in the
|
||
<a class="reference external" href="#interpolation-of-values">dedicated documentation section</a>.
|
||
<a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> has a default value of <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
</li>
|
||
<li><p><em>converters</em>, default value: not set</p>
|
||
<p>Config parsers provide option value getters that perform type conversion. By
|
||
default <a class="reference internal" href="#configparser.ConfigParser.getint" title="configparser.ConfigParser.getint"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getint()</span></code></a>, <a class="reference internal" href="#configparser.ConfigParser.getfloat" title="configparser.ConfigParser.getfloat"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getfloat()</span></code></a>, and
|
||
<a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a> are implemented. Should other getters be
|
||
desirable, users may define them in a subclass or pass a dictionary where each
|
||
key is a name of the converter and each value is a callable implementing said
|
||
conversion. For instance, passing <code class="docutils literal notranslate"><span class="pre">{'decimal':</span> <span class="pre">decimal.Decimal}</span></code> would add
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">getdecimal()</span></code> on both the parser object and all section proxies. In
|
||
other words, it will be possible to write both
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance.getdecimal('section',</span> <span class="pre">'key',</span> <span class="pre">fallback=0)</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">parser_instance['section'].getdecimal('key',</span> <span class="pre">0)</span></code>.</p>
|
||
<p>If the converter needs to access the state of the parser, it can be
|
||
implemented as a method on a config parser subclass. If the name of this
|
||
method starts with <code class="docutils literal notranslate"><span class="pre">get</span></code>, it will be available on all section proxies, in
|
||
the dict-compatible form (see the <code class="docutils literal notranslate"><span class="pre">getdecimal()</span></code> example above).</p>
|
||
</li>
|
||
</ul>
|
||
<p>More advanced customization may be achieved by overriding default values of
|
||
these parser attributes. The defaults are defined on the classes, so they may
|
||
be overridden by subclasses or by attribute assignment.</p>
|
||
<dl class="attribute">
|
||
<dt id="configparser.ConfigParser.BOOLEAN_STATES">
|
||
<code class="descclassname">ConfigParser.</code><code class="descname">BOOLEAN_STATES</code><a class="headerlink" href="#configparser.ConfigParser.BOOLEAN_STATES" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>By default when using <a class="reference internal" href="#configparser.ConfigParser.getboolean" title="configparser.ConfigParser.getboolean"><code class="xref py py-meth docutils literal notranslate"><span class="pre">getboolean()</span></code></a>, config parsers
|
||
consider the following values <code class="docutils literal notranslate"><span class="pre">True</span></code>: <code class="docutils literal notranslate"><span class="pre">'1'</span></code>, <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>, <code class="docutils literal notranslate"><span class="pre">'true'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'on'</span></code> and the following values <code class="docutils literal notranslate"><span class="pre">False</span></code>: <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, <code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'false'</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">'off'</span></code>. You can override this by specifying a custom dictionary of strings
|
||
and their Boolean outcomes. For example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'funky'</span><span class="p">:</span> <span class="s1">'nope'</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'funky'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="c">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">Not a boolean: nope</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">BOOLEAN_STATES</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'sure'</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span> <span class="s1">'nope'</span><span class="p">:</span> <span class="kc">False</span><span class="p">}</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="p">[</span><span class="s1">'section1'</span><span class="p">]</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'funky'</span><span class="p">)</span>
|
||
<span class="go">False</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Other typical Boolean pairs include <code class="docutils literal notranslate"><span class="pre">accept</span></code>/<code class="docutils literal notranslate"><span class="pre">reject</span></code> or
|
||
<code class="docutils literal notranslate"><span class="pre">enabled</span></code>/<code class="docutils literal notranslate"><span class="pre">disabled</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.optionxform">
|
||
<code class="descclassname">ConfigParser.</code><code class="descname">optionxform</code><span class="sig-paren">(</span><em>option</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.optionxform" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>This method transforms option names on every read, get, or set
|
||
operation. The default converts the name to lowercase. This also
|
||
means that when a configuration file gets written, all keys will be
|
||
lowercase. Override this method if that’s unsuitable.
|
||
For example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[Section1]</span>
|
||
<span class="gp">... </span><span class="s2">Key = Value</span>
|
||
<span class="gp">...</span><span class="s2"></span>
|
||
<span class="gp">... </span><span class="s2">[Section2]</span>
|
||
<span class="gp">... </span><span class="s2">AnotherKey = Value</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">typical</span><span class="p">[</span><span class="s1">'Section1'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['key']</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">typical</span><span class="p">[</span><span class="s1">'Section2'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['anotherkey']</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">optionxform</span> <span class="o">=</span> <span class="k">lambda</span> <span class="n">option</span><span class="p">:</span> <span class="n">option</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">custom</span><span class="p">[</span><span class="s1">'Section1'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['Key']</span>
|
||
<span class="gp">>>> </span><span class="nb">list</span><span class="p">(</span><span class="n">custom</span><span class="p">[</span><span class="s1">'Section2'</span><span class="p">]</span><span class="o">.</span><span class="n">keys</span><span class="p">())</span>
|
||
<span class="go">['AnotherKey']</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The optionxform function transforms option names to a canonical form.
|
||
This should be an idempotent function: if the name is already in
|
||
canonical form, it should be returned unchanged.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="configparser.ConfigParser.SECTCRE">
|
||
<code class="descclassname">ConfigParser.</code><code class="descname">SECTCRE</code><a class="headerlink" href="#configparser.ConfigParser.SECTCRE" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A compiled regular expression used to parse section headers. The default
|
||
matches <code class="docutils literal notranslate"><span class="pre">[section]</span></code> to the name <code class="docutils literal notranslate"><span class="pre">"section"</span></code>. Whitespace is considered
|
||
part of the section name, thus <code class="docutils literal notranslate"><span class="pre">[</span>  <span class="pre">larch</span>  <span class="pre">]</span></code> will be read as a section of
|
||
name <code class="docutils literal notranslate"><span class="pre">"</span>  <span class="pre">larch</span>  <span class="pre">"</span></code>. Override this attribute if that’s unsuitable. For
|
||
example:</p>
|
||
<div class="highlight-pycon3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">re</span>
|
||
<span class="gp">>>> </span><span class="n">config</span> <span class="o">=</span> <span class="s2">"""</span>
|
||
<span class="gp">... </span><span class="s2">[Section 1]</span>
|
||
<span class="gp">... </span><span class="s2">option = value</span>
|
||
<span class="gp">...</span><span class="s2"></span>
|
||
<span class="gp">... </span><span class="s2">[ Section 2 ]</span>
|
||
<span class="gp">... </span><span class="s2">another = val</span>
|
||
<span class="gp">... </span><span class="s2">"""</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">typical</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['Section 1', ' Section 2 ']</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">SECTCRE</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="sa">r</span><span class="s2">"\[ *(?P<header>[^]]+?) *\]"</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">read_string</span><span class="p">(</span><span class="n">config</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">custom</span><span class="o">.</span><span class="n">sections</span><span class="p">()</span>
|
||
<span class="go">['Section 1', 'Section 2']</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>While ConfigParser objects also use an <code class="docutils literal notranslate"><span class="pre">OPTCRE</span></code> attribute for recognizing
|
||
option lines, it’s not recommended to override it because that would
|
||
interfere with constructor options <em>allow_no_value</em> and <em>delimiters</em>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="legacy-api-examples">
|
||
<h2>Legacy API Examples<a class="headerlink" href="#legacy-api-examples" title="Permalink to this headline">¶</a></h2>
|
||
<p>Mainly because of backwards compatibility concerns, <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a>
|
||
provides also a legacy API with explicit <code class="docutils literal notranslate"><span class="pre">get</span></code>/<code class="docutils literal notranslate"><span class="pre">set</span></code> methods. While there
|
||
are valid use cases for the methods outlined below, mapping protocol access is
|
||
preferred for new projects. The legacy API is at times more advanced,
|
||
low-level and downright counterintuitive.</p>
|
||
<p>An example of writing to a configuration file:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Please note that using RawConfigParser's set functions, you can assign</span>
|
||
<span class="c1"># non-string values to keys internally, but will receive an error when</span>
|
||
<span class="c1"># attempting to write to a file or when you get it in non-raw mode. Setting</span>
|
||
<span class="c1"># values using the mapping protocol or ConfigParser's set() does not allow</span>
|
||
<span class="c1"># such assignments to take place.</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">add_section</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'an_int'</span><span class="p">,</span> <span class="s1">'15'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_bool'</span><span class="p">,</span> <span class="s1">'true'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_float'</span><span class="p">,</span> <span class="s1">'3.1415'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">,</span> <span class="s1">'fun'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">,</span> <span class="s1">'Python'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="s1">'</span><span class="si">%(bar)s</span><span class="s1"> is </span><span class="si">%(baz)s</span><span class="s1">!'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Writing our configuration file to 'example.cfg'</span>
|
||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">configfile</span><span class="p">:</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">configfile</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>An example of reading the configuration file again:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">RawConfigParser</span><span class="p">()</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># getfloat() raises an exception if the value is not a float</span>
|
||
<span class="c1"># getint() and getboolean() also do this for their respective types</span>
|
||
<span class="n">a_float</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">getfloat</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_float'</span><span class="p">)</span>
|
||
<span class="n">an_int</span> <span class="o">=</span> <span class="n">config</span><span class="o">.</span><span class="n">getint</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'an_int'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">a_float</span> <span class="o">+</span> <span class="n">an_int</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Notice that the next output does not interpolate '%(bar)s' or '%(baz)s'.</span>
|
||
<span class="c1"># This is because we are using a RawConfigParser().</span>
|
||
<span class="k">if</span> <span class="n">config</span><span class="o">.</span><span class="n">getboolean</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'a_bool'</span><span class="p">):</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To get interpolation, use <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
|
||
<span class="n">cfg</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">cfg</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Set the optional *raw* argument of get() to True if you wish to disable</span>
|
||
<span class="c1"># interpolation in a single get operation.</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">False</span><span class="p">))</span> <span class="c1"># -> "Python is fun!"</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">raw</span><span class="o">=</span><span class="kc">True</span><span class="p">))</span> <span class="c1"># -> "%(bar)s is %(baz)s!"</span>
|
||
|
||
<span class="c1"># The optional *vars* argument is a dict with members that will take</span>
|
||
<span class="c1"># precedence in interpolation.</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="nb">vars</span><span class="o">=</span><span class="p">{</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'Documentation'</span><span class="p">,</span>
|
||
<span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'evil'</span><span class="p">}))</span>
|
||
|
||
<span class="c1"># The optional *fallback* argument can be used to provide a fallback value</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span>
|
||
<span class="c1"># -> "Python is fun!"</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'Monty is not.'</span><span class="p">))</span>
|
||
<span class="c1"># -> "Python is fun!"</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="s1">'No such things as monsters.'</span><span class="p">))</span>
|
||
<span class="c1"># -> "No such things as monsters."</span>
|
||
|
||
<span class="c1"># A bare print(cfg.get('Section1', 'monster')) would raise NoOptionError</span>
|
||
<span class="c1"># but we can also use:</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">cfg</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'monster'</span><span class="p">,</span> <span class="n">fallback</span><span class="o">=</span><span class="kc">None</span><span class="p">))</span>
|
||
<span class="c1"># -> None</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Default values are available in both types of ConfigParsers. They are used in
|
||
interpolation if an option used is not defined elsewhere.</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">configparser</span>
|
||
|
||
<span class="c1"># New instance with 'bar' and 'baz' defaulting to 'Life' and 'hard' each</span>
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">({</span><span class="s1">'bar'</span><span class="p">:</span> <span class="s1">'Life'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">:</span> <span class="s1">'hard'</span><span class="p">})</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">(</span><span class="s1">'example.cfg'</span><span class="p">)</span>
|
||
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span> <span class="c1"># -> "Python is fun!"</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">remove_option</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'bar'</span><span class="p">)</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">remove_option</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'baz'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="n">config</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s1">'Section1'</span><span class="p">,</span> <span class="s1">'foo'</span><span class="p">))</span> <span class="c1"># -> "Life is hard!"</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="configparser-objects">
|
||
<span id="id11"></span><h2>ConfigParser Objects<a class="headerlink" href="#configparser-objects" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="class">
|
||
<dt id="configparser.ConfigParser">
|
||
<em class="property">class </em><code class="descclassname">configparser.</code><code class="descname">ConfigParser</code><span class="sig-paren">(</span><em>defaults=None</em>, <em>dict_type=collections.OrderedDict</em>, <em>allow_no_value=False</em>, <em>delimiters=('='</em>, <em>':')</em>, <em>comment_prefixes=('#'</em>, <em>';')</em>, <em>inline_comment_prefixes=None</em>, <em>strict=True</em>, <em>empty_lines_in_values=True</em>, <em>default_section=configparser.DEFAULTSECT</em>, <em>interpolation=BasicInterpolation()</em>, <em>converters={}</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The main configuration parser. When <em>defaults</em> is given, it is initialized
|
||
into the dictionary of intrinsic defaults. When <em>dict_type</em> is given, it
|
||
will be used to create the dictionary objects for the list of sections, for
|
||
the options within a section, and for the default values.</p>
|
||
<p>When <em>delimiters</em> is given, it is used as the set of substrings that
|
||
divide keys from values. When <em>comment_prefixes</em> is given, it will be used
|
||
as the set of substrings that prefix comments in otherwise empty lines.
|
||
Comments can be indented. When <em>inline_comment_prefixes</em> is given, it will
|
||
be used as the set of substrings that prefix comments in non-empty lines.</p>
|
||
<p>When <em>strict</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), the parser won’t allow for
|
||
any section or option duplicates while reading from a single source (file,
|
||
string or dictionary), raising <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> or
|
||
<a class="reference internal" href="#configparser.DuplicateOptionError" title="configparser.DuplicateOptionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateOptionError</span></code></a>. When <em>empty_lines_in_values</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>
|
||
(default: <code class="docutils literal notranslate"><span class="pre">True</span></code>), each empty line marks the end of an option. Otherwise,
|
||
internal empty lines of a multiline option are kept as part of the value.
|
||
When <em>allow_no_value</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (default: <code class="docutils literal notranslate"><span class="pre">False</span></code>), options without
|
||
values are accepted; the value held for these is <code class="docutils literal notranslate"><span class="pre">None</span></code> and they are
|
||
serialized without the trailing delimiter.</p>
|
||
<p>When <em>default_section</em> is given, it specifies the name for the special
|
||
section holding default values for other sections and interpolation purposes
|
||
(normally named <code class="docutils literal notranslate"><span class="pre">"DEFAULT"</span></code>). This value can be retrieved and changed on
|
||
runtime using the <code class="docutils literal notranslate"><span class="pre">default_section</span></code> instance attribute.</p>
|
||
<p>Interpolation behaviour may be customized by providing a custom handler
|
||
through the <em>interpolation</em> argument. <code class="docutils literal notranslate"><span class="pre">None</span></code> can be used to turn off
|
||
interpolation completely, <code class="docutils literal notranslate"><span class="pre">ExtendedInterpolation()</span></code> provides a more
|
||
advanced variant inspired by <code class="docutils literal notranslate"><span class="pre">zc.buildout</span></code>. More on the subject in the
|
||
<a class="reference external" href="#interpolation-of-values">dedicated documentation section</a>.</p>
|
||
<p>All option names used in interpolation will be passed through the
|
||
<a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> method just like any other option name reference. For
|
||
example, using the default implementation of <a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> (which
|
||
converts option names to lower case), the values <code class="docutils literal notranslate"><span class="pre">foo</span> <span class="pre">%(bar)s</span></code> and <code class="docutils literal notranslate"><span class="pre">foo</span>
|
||
<span class="pre">%(BAR)s</span></code> are equivalent.</p>
|
||
<p>When <em>converters</em> is given, it should be a dictionary where each key
|
||
represents the name of a type converter and each value is a callable
|
||
implementing the conversion from string to the desired datatype. Every
|
||
converter gets its own corresponding <code class="xref py py-meth docutils literal notranslate"><span class="pre">get*()</span></code> method on the parser
|
||
object and section proxies.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.1: </span>The default <em>dict_type</em> is <a class="reference internal" href="collections.html#collections.OrderedDict" title="collections.OrderedDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">collections.OrderedDict</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><em>allow_no_value</em>, <em>delimiters</em>, <em>comment_prefixes</em>, <em>strict</em>,
|
||
<em>empty_lines_in_values</em>, <em>default_section</em> and <em>interpolation</em> were
|
||
added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>The <em>converters</em> argument was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>defaults</em> argument is read with <a class="reference internal" href="#configparser.ConfigParser.read_dict" title="configparser.ConfigParser.read_dict"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_dict()</span></code></a>,
|
||
providing consistent behavior across the parser: non-string
|
||
keys and values are implicitly converted to strings.</p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.defaults">
|
||
<code class="descname">defaults</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.defaults" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a dictionary containing the instance-wide defaults.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.sections">
|
||
<code class="descname">sections</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.sections" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a list of the sections available; the <em>default section</em> is not
|
||
included in the list.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.add_section">
|
||
<code class="descname">add_section</code><span class="sig-paren">(</span><em>section</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.add_section" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Add a section named <em>section</em> to the instance. If a section by the given
|
||
name already exists, <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> is raised. If the
|
||
<em>default section</em> name is passed, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised. The name
|
||
of the section must be a string; if not, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Non-string section names raise <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.has_section">
|
||
<code class="descname">has_section</code><span class="sig-paren">(</span><em>section</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.has_section" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Indicates whether the named <em>section</em> is present in the configuration.
|
||
The <em>default section</em> is not acknowledged.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.options">
|
||
<code class="descname">options</code><span class="sig-paren">(</span><em>section</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.options" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a list of options available in the specified <em>section</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.has_option">
|
||
<code class="descname">has_option</code><span class="sig-paren">(</span><em>section</em>, <em>option</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.has_option" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the given <em>section</em> exists, and contains the given <em>option</em>, return
|
||
<a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>; otherwise return <a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>. If the specified
|
||
<em>section</em> is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal notranslate"><span class="pre">None</span></code></a> or an empty string, DEFAULT is assumed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><em>filenames</em>, <em>encoding=None</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Attempt to read and parse an iterable of filenames, returning a list of
|
||
filenames which were successfully parsed.</p>
|
||
<p>If <em>filenames</em> is a string, a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object or a
|
||
<a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>, it is treated as
|
||
a single filename. If a file named in <em>filenames</em> cannot be opened, that
|
||
file will be ignored. This is designed so that you can specify an
|
||
iterable of potential configuration file locations (for example, the
|
||
current directory, the user’s home directory, and some system-wide
|
||
directory), and all existing configuration files in the iterable will be
|
||
read.</p>
|
||
<p>If none of the named files exist, the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>
|
||
instance will contain an empty dataset. An application which requires
|
||
initial values to be loaded from a file should load the required file or
|
||
files using <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code></a> before calling <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> for any
|
||
optional files:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">configparser</span><span class="o">,</span> <span class="nn">os</span>
|
||
|
||
<span class="n">config</span> <span class="o">=</span> <span class="n">configparser</span><span class="o">.</span><span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read_file</span><span class="p">(</span><span class="nb">open</span><span class="p">(</span><span class="s1">'defaults.cfg'</span><span class="p">))</span>
|
||
<span class="n">config</span><span class="o">.</span><span class="n">read</span><span class="p">([</span><span class="s1">'site.cfg'</span><span class="p">,</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">expanduser</span><span class="p">(</span><span class="s1">'~/.myapp.cfg'</span><span class="p">)],</span>
|
||
<span class="n">encoding</span><span class="o">=</span><span class="s1">'cp1250'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>The <em>encoding</em> parameter. Previously, all files were read using the
|
||
default encoding for <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.6.1: </span>The <em>filenames</em> parameter accepts a <a class="reference internal" href="../glossary.html#term-path-like-object"><span class="xref std std-term">path-like object</span></a>.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7: </span>The <em>filenames</em> parameter accepts a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.read_file">
|
||
<code class="descname">read_file</code><span class="sig-paren">(</span><em>f</em>, <em>source=None</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read_file" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and parse configuration data from <em>f</em> which must be an iterable
|
||
yielding Unicode strings (for example files opened in text mode).</p>
|
||
<p>Optional argument <em>source</em> specifies the name of the file being read. If
|
||
not given and <em>f</em> has a <code class="xref py py-attr docutils literal notranslate"><span class="pre">name</span></code> attribute, that is used for
|
||
<em>source</em>; the default is <code class="docutils literal notranslate"><span class="pre">'<???>'</span></code>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>Replaces <a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readfp()</span></code></a>.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.read_string">
|
||
<code class="descname">read_string</code><span class="sig-paren">(</span><em>string</em>, <em>source='<string>'</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read_string" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Parse configuration data from a string.</p>
|
||
<p>Optional argument <em>source</em> specifies a context-specific name of the
|
||
string passed. If not given, <code class="docutils literal notranslate"><span class="pre">'<string>'</span></code> is used. This should
|
||
commonly be a filesystem path or a URL.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.read_dict">
|
||
<code class="descname">read_dict</code><span class="sig-paren">(</span><em>dictionary</em>, <em>source='<dict>'</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.read_dict" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Load configuration from any object that provides a dict-like <code class="docutils literal notranslate"><span class="pre">items()</span></code>
|
||
method. Keys are section names, values are dictionaries with keys and
|
||
values that should be present in the section. If the used dictionary
|
||
type preserves order, sections and their keys will be added in order.
|
||
Values are automatically converted to strings.</p>
|
||
<p>Optional argument <em>source</em> specifies a context-specific name of the
|
||
dictionary passed. If not given, <code class="docutils literal notranslate"><span class="pre"><dict></span></code> is used.</p>
|
||
<p>This method can be used to copy state between parsers.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.get">
|
||
<code class="descname">get</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>*</em>, <em>raw=False</em>, <em>vars=None</em><span class="optional">[</span>, <em>fallback</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.get" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Get an <em>option</em> value for the named <em>section</em>. If <em>vars</em> is provided, it
|
||
must be a dictionary. The <em>option</em> is looked up in <em>vars</em> (if provided),
|
||
<em>section</em>, and in <em>DEFAULTSECT</em> in that order. If the key is not found
|
||
and <em>fallback</em> is provided, it is used as a fallback value. <code class="docutils literal notranslate"><span class="pre">None</span></code> can
|
||
be provided as a <em>fallback</em> value.</p>
|
||
<p>All the <code class="docutils literal notranslate"><span class="pre">'%'</span></code> interpolations are expanded in the return values, unless
|
||
the <em>raw</em> argument is true. Values for interpolation keys are looked up
|
||
in the same manner as the option.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>Arguments <em>raw</em>, <em>vars</em> and <em>fallback</em> are keyword only to protect
|
||
users from trying to use the third argument as the <em>fallback</em> fallback
|
||
(especially when using the mapping protocol).</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.getint">
|
||
<code class="descname">getint</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>*</em>, <em>raw=False</em>, <em>vars=None</em><span class="optional">[</span>, <em>fallback</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getint" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to an integer. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>, <em>vars</em> and
|
||
<em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.getfloat">
|
||
<code class="descname">getfloat</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>*</em>, <em>raw=False</em>, <em>vars=None</em><span class="optional">[</span>, <em>fallback</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getfloat" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to a floating point number. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>,
|
||
<em>vars</em> and <em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.getboolean">
|
||
<code class="descname">getboolean</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>*</em>, <em>raw=False</em>, <em>vars=None</em><span class="optional">[</span>, <em>fallback</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.getboolean" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A convenience method which coerces the <em>option</em> in the specified <em>section</em>
|
||
to a Boolean value. Note that the accepted values for the option are
|
||
<code class="docutils literal notranslate"><span class="pre">'1'</span></code>, <code class="docutils literal notranslate"><span class="pre">'yes'</span></code>, <code class="docutils literal notranslate"><span class="pre">'true'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'on'</span></code>, which cause this method to
|
||
return <code class="docutils literal notranslate"><span class="pre">True</span></code>, and <code class="docutils literal notranslate"><span class="pre">'0'</span></code>, <code class="docutils literal notranslate"><span class="pre">'no'</span></code>, <code class="docutils literal notranslate"><span class="pre">'false'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'off'</span></code>, which
|
||
cause it to return <code class="docutils literal notranslate"><span class="pre">False</span></code>. These string values are checked in a
|
||
case-insensitive manner. Any other value will cause it to raise
|
||
<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>. See <a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> for explanation of <em>raw</em>, <em>vars</em> and
|
||
<em>fallback</em>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.items">
|
||
<code class="descname">items</code><span class="sig-paren">(</span><em>raw=False</em>, <em>vars=None</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.items" title="Permalink to this definition">¶</a></dt>
|
||
<dt>
|
||
<code class="descname">items</code><span class="sig-paren">(</span><em>section</em>, <em>raw=False</em>, <em>vars=None</em><span class="sig-paren">)</span></dt>
|
||
<dd><p>When <em>section</em> is not given, return a list of <em>section_name</em>,
|
||
<em>section_proxy</em> pairs, including DEFAULTSECT.</p>
|
||
<p>Otherwise, return a list of <em>name</em>, <em>value</em> pairs for the options in the
|
||
given <em>section</em>. Optional arguments have the same meaning as for the
|
||
<a class="reference internal" href="#configparser.ConfigParser.get" title="configparser.ConfigParser.get"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code></a> method.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.set">
|
||
<code class="descname">set</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.set" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the given section exists, set the given option to the specified value;
|
||
otherwise raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. <em>option</em> and <em>value</em> must be
|
||
strings; if not, <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>fileobject</em>, <em>space_around_delimiters=True</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write a representation of the configuration to the specified <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file
|
||
object</span></a>, which must be opened in text mode (accepting strings). This
|
||
representation can be parsed by a future <a class="reference internal" href="#configparser.ConfigParser.read" title="configparser.ConfigParser.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> call. If
|
||
<em>space_around_delimiters</em> is true, delimiters between
|
||
keys and values are surrounded by spaces.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.remove_option">
|
||
<code class="descname">remove_option</code><span class="sig-paren">(</span><em>section</em>, <em>option</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.remove_option" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Remove the specified <em>option</em> from the specified <em>section</em>. If the
|
||
section does not exist, raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. If the option
|
||
existed to be removed, return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal notranslate"><span class="pre">True</span></code></a>; otherwise return
|
||
<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal notranslate"><span class="pre">False</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.remove_section">
|
||
<code class="descname">remove_section</code><span class="sig-paren">(</span><em>section</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.remove_section" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Remove the specified <em>section</em> from the configuration. If the section in
|
||
fact existed, return <code class="docutils literal notranslate"><span class="pre">True</span></code>. Otherwise return <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt>
|
||
<code class="descname">optionxform</code><span class="sig-paren">(</span><em>option</em><span class="sig-paren">)</span></dt>
|
||
<dd><p>Transforms the option name <em>option</em> as found in an input file or as passed
|
||
in by client code to the form that should be used in the internal
|
||
structures. The default implementation returns a lower-case version of
|
||
<em>option</em>; subclasses may override this or client code can set an attribute
|
||
of this name on instances to affect this behavior.</p>
|
||
<p>You don’t need to subclass the parser to use this method, you can also
|
||
set it on an instance, to a function that takes a string argument and
|
||
returns a string. Setting it to <code class="docutils literal notranslate"><span class="pre">str</span></code>, for example, would make option
|
||
names case sensitive:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">cfgparser</span> <span class="o">=</span> <span class="n">ConfigParser</span><span class="p">()</span>
|
||
<span class="n">cfgparser</span><span class="o">.</span><span class="n">optionxform</span> <span class="o">=</span> <span class="nb">str</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Note that when reading configuration files, whitespace around the option
|
||
names is stripped before <a class="reference internal" href="#configparser.ConfigParser.optionxform" title="configparser.ConfigParser.optionxform"><code class="xref py py-meth docutils literal notranslate"><span class="pre">optionxform()</span></code></a> is called.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.ConfigParser.readfp">
|
||
<code class="descname">readfp</code><span class="sig-paren">(</span><em>fp</em>, <em>filename=None</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.ConfigParser.readfp" title="Permalink to this definition">¶</a></dt>
|
||
<dd><div class="deprecated">
|
||
<p><span class="versionmodified deprecated">Deprecated since version 3.2: </span>Use <a class="reference internal" href="#configparser.ConfigParser.read_file" title="configparser.ConfigParser.read_file"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read_file()</span></code></a> instead.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span><a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readfp()</span></code></a> now iterates on <em>fp</em> instead of calling <code class="docutils literal notranslate"><span class="pre">fp.readline()</span></code>.</p>
|
||
</div>
|
||
<p>For existing code calling <a class="reference internal" href="#configparser.ConfigParser.readfp" title="configparser.ConfigParser.readfp"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readfp()</span></code></a> with arguments which don’t
|
||
support iteration, the following generator may be used as a wrapper
|
||
around the file-like object:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">readline_generator</span><span class="p">(</span><span class="n">fp</span><span class="p">):</span>
|
||
<span class="n">line</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
|
||
<span class="k">while</span> <span class="n">line</span><span class="p">:</span>
|
||
<span class="k">yield</span> <span class="n">line</span>
|
||
<span class="n">line</span> <span class="o">=</span> <span class="n">fp</span><span class="o">.</span><span class="n">readline</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Instead of <code class="docutils literal notranslate"><span class="pre">parser.readfp(fp)</span></code> use
|
||
<code class="docutils literal notranslate"><span class="pre">parser.read_file(readline_generator(fp))</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="configparser.MAX_INTERPOLATION_DEPTH">
|
||
<code class="descclassname">configparser.</code><code class="descname">MAX_INTERPOLATION_DEPTH</code><a class="headerlink" href="#configparser.MAX_INTERPOLATION_DEPTH" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The maximum depth for recursive interpolation for <code class="xref py py-meth docutils literal notranslate"><span class="pre">get()</span></code> when the <em>raw</em>
|
||
parameter is false. This is relevant only when the default <em>interpolation</em>
|
||
is used.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="rawconfigparser-objects">
|
||
<span id="id13"></span><h2>RawConfigParser Objects<a class="headerlink" href="#rawconfigparser-objects" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="class">
|
||
<dt id="configparser.RawConfigParser">
|
||
<em class="property">class </em><code class="descclassname">configparser.</code><code class="descname">RawConfigParser</code><span class="sig-paren">(</span><em>defaults=None</em>, <em>dict_type=collections.OrderedDict</em>, <em>allow_no_value=False</em>, <em>*</em>, <em>delimiters=('='</em>, <em>':')</em>, <em>comment_prefixes=('#'</em>, <em>';')</em>, <em>inline_comment_prefixes=None</em>, <em>strict=True</em>, <em>empty_lines_in_values=True</em>, <em>default_section=configparser.DEFAULTSECT</em><span class="optional">[</span>, <em>interpolation</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Legacy variant of the <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a>. It has interpolation
|
||
disabled by default and allows for non-string section names, option
|
||
names, and values via its unsafe <code class="docutils literal notranslate"><span class="pre">add_section</span></code> and <code class="docutils literal notranslate"><span class="pre">set</span></code> methods,
|
||
as well as the legacy <code class="docutils literal notranslate"><span class="pre">defaults=</span></code> keyword argument handling.</p>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>Consider using <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> instead which checks types of
|
||
the values to be stored internally. If you don’t want interpolation, you
|
||
can use <code class="docutils literal notranslate"><span class="pre">ConfigParser(interpolation=None)</span></code>.</p>
|
||
</div>
|
||
<dl class="method">
|
||
<dt id="configparser.RawConfigParser.add_section">
|
||
<code class="descname">add_section</code><span class="sig-paren">(</span><em>section</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser.add_section" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Add a section named <em>section</em> to the instance. If a section by the given
|
||
name already exists, <a class="reference internal" href="#configparser.DuplicateSectionError" title="configparser.DuplicateSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DuplicateSectionError</span></code></a> is raised. If the
|
||
<em>default section</em> name is passed, <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised.</p>
|
||
<p>Type of <em>section</em> is not checked which lets users create non-string named
|
||
sections. This behaviour is unsupported and may cause internal errors.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="configparser.RawConfigParser.set">
|
||
<code class="descname">set</code><span class="sig-paren">(</span><em>section</em>, <em>option</em>, <em>value</em><span class="sig-paren">)</span><a class="headerlink" href="#configparser.RawConfigParser.set" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>If the given section exists, set the given option to the specified value;
|
||
otherwise raise <a class="reference internal" href="#configparser.NoSectionError" title="configparser.NoSectionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">NoSectionError</span></code></a>. While it is possible to use
|
||
<a class="reference internal" href="#configparser.RawConfigParser" title="configparser.RawConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawConfigParser</span></code></a> (or <a class="reference internal" href="#configparser.ConfigParser" title="configparser.ConfigParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">ConfigParser</span></code></a> with <em>raw</em> parameters
|
||
set to true) for <em>internal</em> storage of non-string values, full
|
||
functionality (including interpolation and output to files) can only be
|
||
achieved using string values.</p>
|
||
<p>This method lets users assign non-string values to keys internally. This
|
||
behaviour is unsupported and will cause errors when attempting to write
|
||
to a file or get it in non-raw mode. <strong>Use the mapping protocol API</strong>
|
||
which does not allow such assignments to take place.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="exceptions">
|
||
<h2>Exceptions<a class="headerlink" href="#exceptions" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="exception">
|
||
<dt id="configparser.Error">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">Error</code><a class="headerlink" href="#configparser.Error" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for all other <a class="reference internal" href="#module-configparser" title="configparser: Configuration file parser."><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code></a> exceptions.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.NoSectionError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">NoSectionError</code><a class="headerlink" href="#configparser.NoSectionError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when a specified section is not found.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.DuplicateSectionError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">DuplicateSectionError</code><a class="headerlink" href="#configparser.DuplicateSectionError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised if <code class="xref py py-meth docutils literal notranslate"><span class="pre">add_section()</span></code> is called with the name of a section
|
||
that is already present or in strict parsers when a section if found more
|
||
than once in a single input file, string or dictionary.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2: </span>Optional <code class="docutils literal notranslate"><span class="pre">source</span></code> and <code class="docutils literal notranslate"><span class="pre">lineno</span></code> attributes and arguments to
|
||
<a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> were added.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.DuplicateOptionError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">DuplicateOptionError</code><a class="headerlink" href="#configparser.DuplicateOptionError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised by strict parsers if a single option appears twice during
|
||
reading from a single file, string or dictionary. This catches misspellings
|
||
and case sensitivity-related errors, e.g. a dictionary may have two keys
|
||
representing the same case-insensitive configuration key.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.NoOptionError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">NoOptionError</code><a class="headerlink" href="#configparser.NoOptionError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when a specified option is not found in the specified
|
||
section.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.InterpolationError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">InterpolationError</code><a class="headerlink" href="#configparser.InterpolationError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for exceptions raised when problems occur performing string
|
||
interpolation.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.InterpolationDepthError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">InterpolationDepthError</code><a class="headerlink" href="#configparser.InterpolationDepthError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when string interpolation cannot be completed because the
|
||
number of iterations exceeds <a class="reference internal" href="#configparser.MAX_INTERPOLATION_DEPTH" title="configparser.MAX_INTERPOLATION_DEPTH"><code class="xref py py-const docutils literal notranslate"><span class="pre">MAX_INTERPOLATION_DEPTH</span></code></a>. Subclass of
|
||
<a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.InterpolationMissingOptionError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">InterpolationMissingOptionError</code><a class="headerlink" href="#configparser.InterpolationMissingOptionError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when an option referenced from a value does not exist.
|
||
Subclass of <a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.InterpolationSyntaxError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">InterpolationSyntaxError</code><a class="headerlink" href="#configparser.InterpolationSyntaxError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when the source text into which substitutions are made does
|
||
not conform to the required syntax. Subclass of <a class="reference internal" href="#configparser.InterpolationError" title="configparser.InterpolationError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InterpolationError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.MissingSectionHeaderError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">MissingSectionHeaderError</code><a class="headerlink" href="#configparser.MissingSectionHeaderError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when attempting to parse a file which has no section
|
||
headers.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="configparser.ParsingError">
|
||
<em class="property">exception </em><code class="descclassname">configparser.</code><code class="descname">ParsingError</code><a class="headerlink" href="#configparser.ParsingError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Exception raised when errors occur attempting to parse a file.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.2: </span>The <code class="docutils literal notranslate"><span class="pre">filename</span></code> attribute and <a class="reference internal" href="../reference/datamodel.html#object.__init__" title="object.__init__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__init__()</span></code></a> argument were renamed to
|
||
<code class="docutils literal notranslate"><span class="pre">source</span></code> for consistency.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p class="rubric">Footnotes</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id14"><span class="brackets">1</span><span class="fn-backref">(<a href="#id1">1</a>,<a href="#id2">2</a>,<a href="#id3">3</a>,<a href="#id4">4</a>,<a href="#id5">5</a>,<a href="#id6">6</a>,<a href="#id7">7</a>,<a href="#id8">8</a>,<a href="#id9">9</a>,<a href="#id10">10</a>)</span></dt>
|
||
<dd><p>Config parsers allow for heavy customization. If you are interested in
|
||
changing the behaviour outlined by the footnote reference, consult the
|
||
<a class="reference internal" href="#customizing-parser-behaviour">Customizing Parser Behaviour</a> section.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">configparser</span></code> — Configuration file parser</a><ul>
|
||
<li><a class="reference internal" href="#quick-start">Quick Start</a></li>
|
||
<li><a class="reference internal" href="#supported-datatypes">Supported Datatypes</a></li>
|
||
<li><a class="reference internal" href="#fallback-values">Fallback Values</a></li>
|
||
<li><a class="reference internal" href="#supported-ini-file-structure">Supported INI File Structure</a></li>
|
||
<li><a class="reference internal" href="#interpolation-of-values">Interpolation of values</a></li>
|
||
<li><a class="reference internal" href="#mapping-protocol-access">Mapping Protocol Access</a></li>
|
||
<li><a class="reference internal" href="#customizing-parser-behaviour">Customizing Parser Behaviour</a></li>
|
||
<li><a class="reference internal" href="#legacy-api-examples">Legacy API Examples</a></li>
|
||
<li><a class="reference internal" href="#configparser-objects">ConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#rawconfigparser-objects">RawConfigParser Objects</a></li>
|
||
<li><a class="reference internal" href="#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="csv.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">csv</span></code> — CSV File Reading and Writing</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="netrc.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">netrc</span></code> — netrc file processing</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/configparser.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="netrc.html" title="netrc — netrc file processing"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="csv.html" title="csv — CSV File Reading and Writing"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="fileformats.html" >File Formats</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |